PHPackages v.chetkov/php-clean-architecture - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. v.chetkov/php-clean-architecture ActiveLibrary[Utility & Helpers](/categories/utility) v.chetkov/php-clean-architecture ================================ PHP Clean Architecture 1.2.3(1mo ago)14661.1k↓43.8%7MITPHPPHP >=7.4CI failing Since May 13Pushed 1mo ago7 watchersCompare [ Source](https://github.com/Chetkov/php-clean-architecture)[ Packagist](https://packagist.org/packages/v.chetkov/php-clean-architecture)[ RSS](/packages/vchetkov-php-clean-architecture/feed)WikiDiscussions master Synced today READMEChangelog (10)Dependencies (30)Versions (40)Used By (0) To continue in English go to [README-EN.md](README-EN.md) PHP Clean Architecture ====================== [](#php-clean-architecture) Инструмент для автоматизации контроля над качеством архитектуры приложений, написанных на PHP, а также для анализа и визуализации архитектурных метрик. Идея его создания была навеяна книгой Роберта Мартина "Чистая Архитектура". Если еще не читал, можешь ознакомиться с ключевыми идеями, на которых базируется инструмент: Быстрый старт ------------- [](#быстрый-старт) ``` composer require v.chetkov/php-clean-architecture --dev cp vendor/v.chetkov/php-clean-architecture/example.phpca-config.php phpca-config.php vendor/bin/phpca-check phpca-config.php vendor/bin/phpca-build-reports phpca-config.php ``` Совместимость ------------- [](#совместимость) Пакет можно подключать к проектам на PHP 7.4 и выше. Сам анализатор умеет читать код с синтаксисом PHP 8.5 через AST. Это значит, что проверяемый проект может использовать современный PHP-синтаксис, а сам инструмент при этом остается совместимым с более старым runtime, начиная с PHP 7.4. Конфигурация ------------ [](#конфигурация) Скопируйте образец конфига в корень проекта: ``` cp vendor/v.chetkov/php-clean-architecture/example.phpca-config.php phpca-config.php ``` Все детали конфигурации подробно описаны в образце конфига: ### Основные секции конфига [](#основные-секции-конфига) - `reports_dir` - директория, куда `phpca-build-reports` сохранит HTML-отчет. В образцовом конфиге значение можно переопределить через `PHPCA_REPORTS_DIR`. - `history` - необязательное сохранение архитектурных снимков для timeline-режима отчета. - `debug_scan_paths` - необязательные директории или файлы, которые `phpca-debug-unmatched-files` будет сканировать для поиска PHP-файлов вне компонентов. - `components` - список архитектурных компонентов проекта. - `roots` - директории или файлы компонента: `path` задает путь, `namespace` задает соответствующий PHP namespace, `legacy` помечает root как старую часть кода для отчета о прогрессе миграции. - `excluded` - пути внутри компонента, которые нужно исключить из анализа этого компонента. - `restrictions.allowed_dependencies` - компоненты, от которых текущему компоненту разрешено зависеть. - `restrictions.forbidden_dependencies` - компоненты, от которых текущему компоненту явно запрещено зависеть. Не стоит использовать одновременно с `allowed_dependencies`. - `restrictions.public_elements` - публичный API компонента для других компонентов. - `restrictions.private_elements` - приватный API компонента для других компонентов. - `restrictions.max_allowable_distance` - максимально допустимое расстояние компонента от Main Sequence. - `restrictions.check_acyclic_dependencies_principle` - проверка Acyclic Dependencies Principle. - `restrictions.check_stable_dependencies_principle` - проверка Stable Dependencies Principle. - `vendor_based_components` - автоматическое создание компонентов для Composer-зависимостей из `vendor`. - `exclusions.allowed_state` - сохраненное разрешенное состояние для постепенного внедрения правил. - `factories` - технические фабрики анализатора, рендера отчета и event manager. В обычном проекте их чаще всего не нужно менять. ### Публичный и приватный API компонента [](#публичный-и-приватный-api-компонента) `public_elements` и `private_elements` описывают API компонента для других компонентов, а не запрет на использование элемента внутри его собственного компонента. Например, `ComponentA\Service` может зависеть от `ComponentA\Internal\Model`. Это внутренняя зависимость компонента, она может отображаться в dependency graph как internal, но не считается private API violation. А вот `ComponentB\Service` не должен зависеть от `ComponentA\Internal\Model`, если этот элемент не входит в публичный API `ComponentA` или явно указан в `private_elements`. ### Legacy rate и прогресс миграции [](#legacy-rate-и-прогресс-миграции) Если проект постепенно переезжает из старой структуры в новую, root компонента можно пометить как legacy: ``` 'roots' => [ [ 'path' => __DIR__ . '/src/Catalog', 'namespace' => 'App\Catalog', ], [ 'path' => __DIR__ . '/legacy/Catalog', 'namespace' => 'Legacy\Catalog', 'legacy' => true, ], ], ``` Все файлы, найденные в root с `legacy: true`, считаются legacy. Если ключ не указан, root считается modern. В отчете появляется прогресс модернизации: основной процент считается по физическим строкам PHP-файлов, а рядом показываются и строки кода, и количество `UnitOfCode` для всей системы, каждого компонента и каждого вложенного `sub`-отчета. ### История отчетов и timeline [](#история-отчетов-и-timeline) Если нужно видеть, как архитектура меняется от релиза к релизу или от CI-запуска к CI-запуску, включите историю: ``` 'history' => [ 'enabled' => true, 'dir' => __DIR__ . '/var/phpca-history', 'collect_on_check' => true, ], ``` `dir` лучше хранить вне `reports_dir`, потому что директория отчета пересоздается при каждой генерации. В history сохраняются компактные snapshots: дата, git metadata, summary, метрики компонентов, legacy/modernization, A/I данные и ребра графа компонентов для корневого отчета и всех вложенных `sub`-отчетов. `phpca-build-reports` при включенной истории записывает новый snapshot и встраивает историю в self-contained HTML-отчет. Если нужно записать снимок без генерации UI, используйте `phpca-check --record-history` или включите `history.collect_on_check`. ### Вложенные отчеты [](#вложенные-отчеты) Для больших систем один общий граф часто становится слишком шумным. В таких случаях архитектуру можно описывать рекурсивно: верхний уровень показывает крупные компоненты системы, а внутри каждого компонента можно описать слои, подкомпоненты или следующий уровень декомпозиции. Компонент верхнего уровня может содержать `sub`-конфиг: ``` 'components' => [ 'AgentWorkspace' => [ 'roots' => [...], 'sub' => require __DIR__ . '/phpca-configs/layers/AgentWorkspace.php', ], ], ``` Формат `sub` такой же, как у обычного `phpca-config.php`. Такой файл можно запускать отдельно, а можно подключить из родительского конфига через `require`. При запуске из родительского конфига: - `phpca-check` последовательно проверяет корневой конфиг и все вложенные `sub`-конфиги; - `phpca-build-reports` создает один SPA-отчет, в котором можно переходить между уровнями анализа; - локальный `reports_dir` вложенного конфига игнорируется; - путь вложенного отчета строится от корневого `reports_dir` по иерархии компонентов. Наследование задается явно: ``` 'inherit' => ['factories', 'vendor_based_components', 'exclusions'], ``` Если `inherit` не указан, вложенный конфиг ничего не наследует. `components` не наследуются никогда. Такой подход позволяет держать несколько удобных уровней архитектурного контроля: - система целиком: зависимости между bounded contexts или крупными модулями; - компонент: зависимости между слоями `Domain`, `Application`, `Infrastructure`, `Presentation`; - подкомпонент: более тонкая внутренняя декомпозиция, если она нужна проекту. Также полезно прочитать статьи: - - Обнаружение исходников ---------------------- [](#обнаружение-исходников) Анализатор читает PHP-файлы через AST и определяет объявленные `class`, `interface`, `trait` и `enum` из содержимого файла. Поэтому имя элемента больше не обязано совпадать с путем по PSR-4: компонент может указывать на legacy-директорию или отдельный файл, а найденный символ будет привязан к компоненту по root path из конфига. Если в файле нет объявленных символов, например это executable script, используется fallback по `namespace` root-а и относительному пути. При включенном `vendor_based_components` учитываются Composer `psr-4`, `psr-0`, `classmap`, `files`, `autoload-dev` и `exclude-from-classmap`. Синтаксис PHP 8.5 поддерживается на уровне AST-парсинга: pipe operator, `clone()` с изменением свойств, `#[NoDiscard]`, closures/first-class callables и casts в constant expressions, attributes on constants и final promoted properties. CLI-команды ----------- [](#cli-команды) Все команды принимают путь к конфигу первым аргументом. Если путь не передан, используется `phpca-config.php` из текущего проекта. ``` vendor/bin/phpca-check phpca-config.php vendor/bin/phpca-build-reports phpca-config.php vendor/bin/phpca-allow-current-state phpca-config.php vendor/bin/phpca-debug-unmatched-files phpca-config.php ``` `PHPCA_ALLOWED_PATHS` ограничивает анализ списком файлов. Это удобно для CI по измененным файлам. Значение передается как список путей, разделенных переводом строки. `PHPCA_REPORTS_DIR` можно использовать в образцовом конфиге для переопределения `reports_dir` без изменения файла конфигурации. `phpca-check --record-history` сохраняет архитектурный snapshot без генерации отчета. `phpca-build-reports --with-history`принудительно записывает snapshot даже если `history.enabled` не включен в конфиге. `phpca-debug-unmatched-files` также принимает дополнительные пути после конфига. Если они переданы, команда сканирует только их: ``` vendor/bin/phpca-debug-unmatched-files phpca-config.php src ``` Использование ------------- [](#использование) 1. Формирование отчета для анализа. ``` vendor/bin/phpca-build-reports phpca-config.php ``` Команда создает статический HTML-отчет. Отчет можно открыть локально в браузере без запуска сервера. Путь к конфигу можно не передавать, если используется стандартный `phpca-config.php` в текущей директории. ### Что есть в отчете [](#что-есть-в-отчете) Отчет рассчитан не только на маленькие проекты, но и на большие кодовые базы, где важно быстро перейти от общей картины к конкретной зависимости. Основные возможности: - обзор системы с количеством компонентов, юнитов, зависимостей и активных проблем; - матрица Robert C. Martin A/I с зонами боли и бесполезности; - Distance from Main Sequence и метрики компонента с цветовой оценкой качества; - общий граф компонентов и граф выбранного компонента; - внешние компоненты и библиотеки на графе как отдельные external nodes; - фильтр компонентов графа: один выбранный компонент показывает его окружение, несколько выбранных компонентов показывают только связи между ними; - drag, zoom, reset viewport, fullscreen и разные варианты компоновки графа; - глобальный поиск по компонентам, юнитам, путям и зависимостям; - вкладки нарушений, зависимостей и юнитов; - Dependency Explorer с группировкой `компонент -> дерево директорий -> файл -> конкретные unit-зависимости`; - цветовая индикация `allowed`, `internal`, `allowed state`, `private API` и `blocked`; - копирование путей файлов и полных имен юнитов из dependency details; - URL-навигация: выбранный отчет, компонент, вкладка, юнит и поиск восстанавливаются после обновления страницы; - timeline по сохраненным снимкам с autoplay и сравнением с предыдущим снимком; - локализация RU / EN / 中文. Пример отчета на большом проекте: [![Обзор suite-отчета](docs/images/report-suite-overview.png)](docs/images/report-suite-overview.png) [![Карта зависимостей с внешними компонентами](docs/images/report-dependency-graph.png)](docs/images/report-dependency-graph.png) [![Детали зависимостей компонента](docs/images/report-dependency-details.png)](docs/images/report-dependency-details.png) 2. Check для CI. ``` vendor/bin/phpca-check phpca-config.php ``` Если код нарушает ограничения, заданные конфигом, команда выводит найденные проблемы и завершается с ошибкой. Рекомендуется добавить запуск `phpca-check` в CI, чтобы код, попавший в сборку, соответствовал архитектурным правилам проекта. 3. Разрешенное состояние. ``` vendor/bin/phpca-allow-current-state phpca-config.php ``` Команда сохраняет текущее состояние проекта и взаимосвязи между существующими классами в отдельный файл. При последующих запусках `phpca-check` проблемы, относящиеся к сохраненному состоянию, будут проигнорированы. Чтобы `phpca-check` учитывал сохраненное состояние, в конфиге должны быть включены `exclusions.allowed_state.enabled` и указан путь к `exclusions.allowed_state.storage`. Для suite-конфига команда проходит корневой конфиг и все вложенные `sub`-конфиги. Если вложенный конфиг наследует `exclusions`, его состояние сохраняется в отдельный файл, построенный от корневого storage по иерархии компонентов, например `phpca-allowed-state/catalog/domain.php`. Если во вложенном конфиге явно указан свой `exclusions.allowed_state.storage`, используется этот путь. Это дает возможность подключать php-clean-architecture не только к новым проектам, но и к уже существующим проектам, где архитектурные проблемы нужно устранять постепенно. 4. Отчет/Check по списку файлов Если нужно проверить не весь проект, а только его часть, например список измененных файлов, можно передать ограничение через переменную окружения `PHPCA_ALLOWED_PATHS`. Пример: ``` PHPCA_ALLOWED_PATHS="$(git diff master --name-only)" PHPCA_REPORTS_DIR="phpca-report" vendor/bin/phpca-build-reports phpca-config.php ``` 5. Поиск файлов вне компонентов. ``` vendor/bin/phpca-debug-unmatched-files phpca-config.php src ``` Команда показывает PHP-файлы, которые находятся в области сканирования, но не попали ни в один компонент и не исключены явно. Это удобно при первичной настройке конфига и при развитии большой системы: можно быстро увидеть файлы, для которых еще не принято архитектурное решение. Если пути после конфига не переданы, команда использует `PHPCA_ALLOWED_PATHS`. Если и он пустой, команда выбирает область сканирования из конфига: для обычного конфига это общий родитель component roots, для вложенного `sub`-конфига - roots родительского компонента. Поведение можно переопределить секцией `debug_scan_paths`. Если unmatched-файлы найдены, команда выводит их список и завершается с кодом `1`; если все файлы покрыты компонентами или exclusions, выводит `No unmatched files!` и завершается с кодом `0`. ### Health Score 59 — FairBetter than 98% of packages Maintenance94 Actively maintained with recent releases Popularity45 Moderate usage in the ecosystem Community13 Small or concentrated contributor base Maturity68 Established project with proven stability Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~71 days Recently: every ~0 days Total 32 Last Release 33d ago Major Versions 0.1.4 → 1.0.02026-05-09 PHP version history (2 changes)1.0.0PHP ^8.3 1.1.0PHP >=7.4 ### Community Maintainers ![](https://www.gravatar.com/avatar/d777a22e45abd7db2a1de4aa1557688f67c0b0ad9f0a928dce3f6cd7e4860b06?d=identicon)[Chetkov](/maintainers/Chetkov) --- Top Contributors [![Chetkov](https://avatars.githubusercontent.com/u/12594577?v=4)](https://github.com/Chetkov "Chetkov (188 commits)") --- Tags architectureclean-architecturephpstatic-analysis ### Code Quality TestsPHPUnit Static AnalysisPHPStan Code StylePHP\_CodeSniffer Type Coverage Yes ### Embed Badge ![Health badge](/badges/vchetkov-php-clean-architecture/health.svg) ``` [![Health](https://phpackages.com/badges/vchetkov-php-clean-architecture/health.svg)](https://phpackages.com/packages/vchetkov-php-clean-architecture) ``` ### Alternatives [symfony/symfony The Symfony PHP framework 31.4k87.2M2.2k](/packages/symfony-symfony)[matomo/matomo Matomo is the leading Free/Libre open analytics platform 21.7k38.9k](/packages/matomo-matomo)[tempest/framework The PHP framework that gets out of your way. 2.2k34.4k15](/packages/tempest-framework)[contao/core-bundle Contao Open Source CMS 1231.6M2.8k](/packages/contao-core-bundle)[metamodels/core MetaModels core 10156.4k68](/packages/metamodels-core)[terminal42/contao-node Node bundle for Contao Open Source CMS 3177.0k6](/packages/terminal42-contao-node) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)