From 8ddbcc2695add2747a08f19fefc100e4ec0be2df Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 1 Jan 2026 17:38:32 +0000 Subject: [PATCH 1/4] docs: add Quick Start section and improve Introduction **Introduction improvements:** - Add clear definition of what PHPArkitect does - Add "Why PHPArkitect?" section explaining key benefits - Include multiple code examples showing common use cases - Make the value proposition immediately clear **Quick Start section:** - Add 3-step quick start guide for new users - Include minimal working configuration example - Provide clear next steps after setup - Move quick start before detailed installation options This makes the README more approachable for newcomers while keeping all detailed information accessible. --- README.md | 70 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 68 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 51188f40..62fa10ef 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,7 @@ 1. [Introduction](#introduction) +1. [Quick Start](#quick-start) 1. [Installation](#installation) 1. [Usage](#usage) 1. [Available rules](#available-rules) @@ -13,14 +14,32 @@ # Introduction -PHPArkitect helps you to keep your PHP codebase coherent and solid, by allowing you to add architectural constraint checks to your workflow. -You can express the constraint that you want to enforce, in simple and readable PHP code, for example: +**PHPArkitect** is a tool to enforce architectural constraints in your PHP codebase. It helps you maintain clean architecture by preventing violations of your design rules during development and in CI/CD pipelines. + +## Why PHPArkitect? + +As projects grow, maintaining architectural consistency becomes challenging. PHPArkitect helps you: + +- **Prevent architectural drift**: Ensure your Domain layer doesn't depend on Infrastructure code +- **Enforce naming conventions**: Make sure all Controllers end with "Controller", all Services with "Service", etc. +- **Maintain layered architecture**: Keep your application, domain, and infrastructure layers properly separated +- **Catch violations early**: Get immediate feedback in your IDE or CI pipeline before code review +- **Document architecture as code**: Your architectural rules become executable and self-documenting + +## Example + +You can express architectural constraints in simple, readable PHP code: ```php Rule::allClasses() ->that(new ResideInOneOfTheseNamespaces('App\Controller')) ->should(new HaveNameMatching('*Controller')) ->because('it\'s a symfony naming convention'); + +Rule::allClasses() + ->that(new ResideInOneOfTheseNamespaces('App\Domain')) + ->should(new NotHaveDependencyOutsideNamespace('App\Domain')) + ->because('we want to protect our domain from external dependencies'); ``` Since selecting classes by namespace is very common, there's a convenient shortcut: @@ -33,6 +52,53 @@ Rule::namespace('App\Controller') You can also specify multiple namespaces: `Rule::namespace('App\Controller', 'App\Service')`. +# Quick Start + +Get started with PHPArkitect in 3 simple steps: + +## 1. Install via Composer + +```bash +composer require --dev phparkitect/phparkitect +``` + +## 2. Create a configuration file + +Create a `phparkitect.php` file in your project root: + +```php +that(new ResideInOneOfTheseNamespaces('App\Controller')) + ->should(new HaveNameMatching('*Controller')) + ->because('we want uniform naming for controllers'); + + $config->add($classSet, ...$rules); +}; +``` + +## 3. Run the check + +```bash +vendor/bin/phparkitect check +``` + +That's it! PHPArkitect will analyze your code and report any architectural violations. + +**Next steps**: Check out the [Available rules](#available-rules) section to explore all the constraints you can enforce. # Installation ## Using Composer From 38caa8fe271850715771524f6f61ead8fa7025fd Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 1 Jan 2026 17:42:33 +0000 Subject: [PATCH 2/4] docs: add GitHub Actions integration section Add official GitHub Action integration documentation to help users easily set up PHPArkitect in their CI/CD pipelines. - Include complete workflow example - Add links to GitHub Action repository and Marketplace - Position before Laravel integration for better visibility - Provide configuration examples for PHP version and Arkitect version This makes it easier for teams to enforce architectural rules in their pull request workflows. --- README.md | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/README.md b/README.md index 62fa10ef..859789c8 100644 --- a/README.md +++ b/README.md @@ -568,5 +568,41 @@ $rules[] = Rule::allClasses() # Integrations +## GitHub Actions + +You can easily integrate PHPArkitect into your CI/CD pipeline using the official GitHub Action. + +Add this to your `.github/workflows/arkitect.yml`: + +```yaml +name: Arkitect + +on: + pull_request: + push: + branches: + - main + +jobs: + arkitect: + runs-on: ubuntu-latest + name: Arkitect + steps: + - uses: actions/checkout@v4 + + - name: Run Arkitect + uses: phparkitect/arkitect-github-actions@v1 + with: + php_version: '8.2' + arkitect_version: 'latest' +``` + +**Resources:** +- [GitHub Action Repository](https://github.com/phparkitect/arkitect-github-actions) +- [GitHub Marketplace](https://github.com/marketplace/actions/phparkitect-arkitect) + +The action supports multiple PHP versions and allows you to specify which PHPArkitect version to use. + ## Laravel + If you plan to use Arkitect with Laravel, [smortexa](https://github.com/smortexa) wrote a nice wrapper with some predefined rules for laravel: https://github.com/smortexa/laravel-arkitect From 2a1f19b7299a6ecdfebff5bd02ace9fae81598c5 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 1 Jan 2026 17:54:56 +0000 Subject: [PATCH 3/4] docs: fix GitHub Actions syntax with correct parameters Corrected the GitHub Action usage example to use the actual documented parameters: - Use docker://phparkitect/arkitect-github-actions instead of @v1 - Use PHP_VERSION as environment variable (not input parameter) - Use 'args: check' instead of incorrect php_version/arkitect_version - Update description to reflect actual capabilities Thanks to user feedback for catching this error. --- README.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 859789c8..71d27b7d 100644 --- a/README.md +++ b/README.md @@ -591,17 +591,18 @@ jobs: - uses: actions/checkout@v4 - name: Run Arkitect - uses: phparkitect/arkitect-github-actions@v1 + uses: docker://phparkitect/arkitect-github-actions + env: + PHP_VERSION: '8.2' with: - php_version: '8.2' - arkitect_version: 'latest' + args: check ``` **Resources:** - [GitHub Action Repository](https://github.com/phparkitect/arkitect-github-actions) - [GitHub Marketplace](https://github.com/marketplace/actions/phparkitect-arkitect) -The action supports multiple PHP versions and allows you to specify which PHPArkitect version to use. +The action supports multiple PHP versions through the `PHP_VERSION` environment variable. ## Laravel From bd507f94f3481882d2dee74f5cd27cc3977ad66f Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 1 Jan 2026 19:05:55 +0000 Subject: [PATCH 4/4] docs: simplify GitHub Actions section to avoid doc duplication Remove inline YAML example and instead reference the official GitHub Action repository for setup instructions. This prevents documentation drift and ensures users always get the most up-to-date configuration examples from the authoritative source. --- README.md | 33 +++------------------------------ 1 file changed, 3 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index 71d27b7d..3bca2226 100644 --- a/README.md +++ b/README.md @@ -572,37 +572,10 @@ $rules[] = Rule::allClasses() You can easily integrate PHPArkitect into your CI/CD pipeline using the official GitHub Action. -Add this to your `.github/workflows/arkitect.yml`: +For setup instructions and usage examples, please refer to the official documentation: -```yaml -name: Arkitect - -on: - pull_request: - push: - branches: - - main - -jobs: - arkitect: - runs-on: ubuntu-latest - name: Arkitect - steps: - - uses: actions/checkout@v4 - - - name: Run Arkitect - uses: docker://phparkitect/arkitect-github-actions - env: - PHP_VERSION: '8.2' - with: - args: check -``` - -**Resources:** -- [GitHub Action Repository](https://github.com/phparkitect/arkitect-github-actions) -- [GitHub Marketplace](https://github.com/marketplace/actions/phparkitect-arkitect) - -The action supports multiple PHP versions through the `PHP_VERSION` environment variable. +- [GitHub Action Repository](https://github.com/phparkitect/arkitect-github-actions) - Complete setup guide and examples +- [GitHub Marketplace](https://github.com/marketplace/actions/phparkitect-arkitect) - Action listing ## Laravel