Chetkov/php-clean-architecture

This system is a PHP-based tool for enforcing and analyzing clean architecture principles within a codebase. It utilizes Abstract Syntax Tree (AST) parsing to discover source units, map dependencies, and detect architectural violations against configurable component rules. The tool provides a CLI interface to check for violations, generate self-contained HTML reports with interactive visualizations, and track architectural history over time.

15 changes.

This period marks the initial release of the PHP Clean Architecture tool, establishing the core infrastructure for static analysis and reporting. The work focused on building the AST-based dependency finder, defining the clean architecture model classes, and implementing the CLI interface for checking and generating architectural reports.

17 changes.

This period focused on modernizing the reporting interface by replacing legacy views with a React-based Single Page Application, while simultaneously introducing AST-based source and dependency discovery for PHP files. The work also included comprehensive test coverage for the new analysis components, configuration inheritance, and report generation lifecycle.

The tool now records a history of analysis reports, enabling a timeline view of architectural changes over time. This is implemented via new \ReportHistorySnapshotBuilder\ and \ReportHistoryStorage\ classes that generate and persist JSON snapshots of reports, including metadata like git branch/commit and summary metrics. The \ConfigTreeRunner\ and \PHPCleanArchitectureFacade\ have been updated to support recording this history during check and report generation phases.

src · high confidence

New executable scripts have been added to the \bin\ directory to support the clean architecture analysis workflow. \phpca-allow-current-state\ saves the current architectural state for future comparison. \phpca-build-reports\ generates HTML reports of architectural violations, with an optional \--with-history\ flag to record history. \phpca-check\ performs a check against the allowed state and lists any violations. \phpca-debug-unmatched-files\ helps identify files not covered by the architecture rules. All scripts support a \PHPCA\_ALLOWED\_PATHS\ environment variable to restrict analysis to specific files.

bin · high confidence

A new configuration file for the Phasor static analysis tool has been added to the project. The configuration sets the target PHP version to 7.4, defines the source directories to analyze (bin, src, vendor), and enables strict checking for methods, objects, parameters, properties, and returns. It also configures specific behaviors regarding null casts, array casts, and detection of dead code and unused variables.

.phan · medium confidence

A new StringHelper class has been introduced in the Service/Helper directory, providing static methods for string manipulation including removing spaces, collapsing multiple spaces, and escaping backslashes. The file includes strict typing and is part of the Chetkov\\PHPCleanArchitecture\\Service\\Helper namespace.

src/Service/Helper · high confidence

The application now includes new console helper classes to improve terminal interaction. A new Console class provides a reliable method for detecting terminal width, falling back to a default if the 'tput' command is unavailable, and offers static methods for writing formatted output. Additionally, a ProgressBar class has been introduced to render animated progress indicators in the terminal, supporting customizable width and text formatting.

src/Infrastructure/Console · high confidence

The application now provides real-time console feedback during static analysis and report rendering. A new EventManager coordinates listeners that print start/finish messages and execution times for analysis and report building phases. Additionally, progress bars are displayed for file analysis and unit-of-code report rendering, showing component names, statuses, and elapsed time to improve user visibility into long-running processes.

src/Infrastructure/Event · high confidence

Introduced a new type classification system in the \src/Model/Type\ directory, providing a way to identify and categorize PHP types. The \Type\ abstract class and its concrete implementations (\TypeClass\, \TypeInterface\, \TypeTrait\, \TypePrimitive\, \TypeUndefined\) allow the application to determine whether a given string represents a class, interface, trait, primitive, or undefined type. This enables more robust type checking and reflection within the clean architecture model layer.

src/Model/Type · high confidence

The tool is introduced as a PHP package for automating architecture quality control, analyzing dependencies, and visualizing architecture metrics. It supports PHP 7.4+ runtime with PHP 8.5 syntax parsing via AST. Key features include configurable component definitions with public/private API restrictions, legacy code migration tracking, report history/timeline, nested report suites, and CLI commands for checking and building reports. The package includes example configurations, README documentation, and standard PHP tooling configs (phpcs, phpstan, phpunit).

(repo-wide) · high confidence

The system now uses an Abstract Syntax Tree (AST) based approach to find dependencies, replacing the previous method. This change introduces a new \AstDependenciesFinder\ that leverages the \PhpParser\ library to parse PHP code and identify dependencies more accurately. The implementation includes a \DependencyNameNormalizer\ to handle class name normalization and an \ExclusionChecker\ to filter out internal references like 'self', 'static', 'parent', and 'void'. This shift to AST analysis allows for more robust dependency tracking within the codebase.

src/Service/Analysis/DependenciesFinder · high confidence

A new \PhpParserSourceUnitDiscovery\ implementation has been added to parse PHP source files using the \php-parser\ library. This component extracts structured \SourceUnit\ objects (classes, interfaces, traits, and enums) from the codebase by analyzing the Abstract Syntax Tree (AST). It also provides a fallback mechanism to handle files that fail to parse or contain no discoverable units, ensuring that source discovery remains robust even when static analysis encounters syntax errors or unexpected file structures.

src/Service/Analysis/SourceDiscovery · high confidence

Added new interfaces for the service layer: EventListenerInterface with a handle method, and EventManagerInterface with subscribe, unsubscribe, notify, and releaseAll methods. These interfaces define the contract for event handling and management within the application's service layer, enabling decoupled event-driven architecture.

src/Service · high confidence

The report generation system has been refactored to produce self-contained Single Page Application (SPA) reports. A new \ReportRenderingService\ orchestrates the creation of a standalone HTML report that embeds all necessary CSS and JavaScript assets inline, ensuring the report is fully portable. Report data is embedded directly into the HTML head as a JSON script tag, and the \ReportSuiteRenderer\ now generates a hierarchical suite structure that links to individual component reports. This change replaces the previous report generation approach with a modern, self-contained HTML5 report format.

src/Service/Report/SpaReport · high confidence

Added the EventInterface, ProgressiveTrait, and TimedTrait to the Model/Event namespace. The interface defines the contract for event objects, while the traits provide reusable state management for progress tracking (position/totalPositions) and timing (microTime), enabling consistent event data structures across the application.

src/Model/Event · high confidence

Added new event classes to track the analysis process: AnalysisStartedEvent and AnalysisFinishedEvent mark the overall start and end of an analysis run. ComponentAnalysisStartedEvent and ComponentAnalysisFinishedEvent (extending the abstract ComponentAnalysisEvent) track the processing of individual components. FileAnalyzedEvent reports on individual file analysis, including status (OK or SKIPPED) and file path. These events enable external listeners to react to specific stages of the analysis pipeline.

src/Service/Analysis/Event · high confidence

Added new model classes including AnalysisContext, Component, Restrictions, and UnitOfCode to support clean architecture analysis. The AnalysisContext class manages the state of components and units of code, while the Component class handles component configuration and path management. The Restrictions class defines allowed and forbidden dependencies, public and private paths, and allowed states for components. The UnitOfCode class represents a unit of code with its type, dependencies, and component association. These changes enable more structured and maintainable code analysis for clean architecture principles.

src/Model · high confidence

The report module has been replaced with a new single-page application (SPA) built with React. This introduces a modernized user interface for architecture reports, featuring a sidebar with component lists and modernization progress, a main area for interactive graphs and dependency maps, and support for global search and filtering. The change includes a new \main.jsx\ entry point and \styles.css\ for the SPA, along with the compiled assets, shifting the report experience from a traditional multi-page or static view to a dynamic, client-side rendered application.

frontend/report-app, src/Service/Report/SpaReport/Assets · high confidence

Introduced a new interface, ReportRenderingServiceInterface, which defines the contract for the report rendering service. This change supports the broader refactoring to extract an interface from the existing ReportRenderingService implementation, facilitating better testability and adherence to clean architecture principles.

src/Service/Report · high confidence

The configuration service now supports nested report suites and hierarchical config inheritance. A new \ConfigInheritanceResolver\ merges inherited keys (exclusions, factories, restrictions, vendor\_based\_components) from parent contexts, while \ConfigTreeBuilder\ recursively builds an \EffectiveConfigNode\ tree. Additionally, \AllowedStateStorageResolver\ and \AllowedStateStorageContext\ manage the generation and inheritance of allowed state storage paths for nested components, ensuring each child node receives the correct storage path based on its position in the config tree.

src/Service/Config · high confidence

Added ComponentAnalyzer, SourceFileFinder, SourceLineCounter, and CompositeCountableIterator to the analysis service. ComponentAnalyzer now orchestrates the analysis of a given component by discovering source files, counting lines of code, and finding dependencies, while SourceFileFinder handles the logic for locating PHP files (including those with shebangs) and SourceLineCounter provides line counts. This refactors the internal mechanics of how the system processes and reports on code structure.

src/Service/Analysis · high confidence

Added a set of new event classes to track the lifecycle of report generation. This includes \ReportBuildingStarted\ and \ReportBuildingFinished\ events for the overall build process, \ReportRenderingStarted\ and \ReportRenderingFinished\ events for the rendering phase, and specific progress events for \Component\ and \UnitOfCode\ reporting. These events provide granular visibility into the report generation pipeline.

src/Service/Report/Event · medium confidence

The report generation interface has been replaced with a new Single Page Application (SPA) built with Vite and React. This change introduces a modern frontend structure for the report module, moving away from the previous implementation to provide an improved user experience for generating and viewing reports.

frontend · medium confidence

Added automated tests for CLI scripts, facade, and report history; Added test fixtures for ReportMatrixProject; Added test fixtures for clean architecture analysis; Added test fixtures for legacy rate project; Added test fixtures for source and vendor discovery; Added test support classes for dependency, event, and report rendering; Added tests for ConfigTreeBuilder; Added tests for console terminal width detection; Added tests for the new AST-based dependency parsing and source discovery; Expanded test fixtures for dependency parsing.

The project now includes a PHP backend defined in composer.json with dependencies for static analysis and testing, alongside a new frontend report application built with React and Vite. The root package.json establishes a workspace structure to manage the frontend build, while test fixtures for vendor discovery have been added.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 73 → 67 (-5.3)
• Rubric changed (rubric-2026.08.19 → rubric-2026.09.15) — scores are not directly comparable.

• Code Health 89 → 88 (-0.7)
• Architecture 99 → 94 (-5.0)
• Maturity 65 → 62 (-2.5)
• Readiness 74 → 68 (-6.0)
• Security 82 → 92 (+9.4)
• Accessibility 83 → 64 (-18.8)

• Change coupling: main.jsx ↔ ReportDataBuilder.php (frontend/report-app/src/main.jsx)
• Coverage not included — suite not readable by the collector
• Dependency hygiene not measured — dependency manifest found but not parsed for hygiene
• Duplicated block (10 lines × 2) (src/Model/Component.php)
• Duplicated block (10 lines × 3) (src/ConfigTreeRunner.php)
• Duplicated block (13 lines × 2) (src/ConfigTreeRunner.php)
• Duplicated block (13 lines × 4) (src/ConfigTreeRunner.php)
• Duplicated block (16 lines × 2) (src/Service/Report/SpaReport/ReportRenderingService.php)
• Duplicated block (6 lines × 2) (src/Infrastructure/Event/Listener/Analysis/ComponentAnalysisEventListener.php)
• Duplicated block (9 lines × 2) (src/Service/Report/SpaReport/ReportAssetInliner.php)
• High CVE: [GHSA redacted] (frontend/report-app/package-lock.json)
• High vulnerability: [GHSA redacted] (frontend/report-app/package-lock.json)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• Low CVE: [GHSA redacted] (frontend/report-app/package-lock.json)
• Low vulnerability: [GHSA redacted] (frontend/report-app/package-lock.json)
• No exposed public API
• …and 2 more

• Change coupling: example.phpca-config.php ↔ PHPCleanArchitectureFacade.php (example.phpca-config.php)
• Change coupling: example.phpca-config.php ↔ Restrictions.php (example.phpca-config.php)
• Dependency hygiene PARTLY measured — Composer dependencies read, no committed lock to grade for currency
• Documentation: no installation or build instructions (README.md)
• Documentation: no usage examples (README.md)
• Duplicated block (10 lines × 2) (src/Service/Report/SpaReport/ReportAssetInliner.php)
• Duplicated block (11 lines × 3) (src/ConfigTreeRunner.php)
• Duplicated block (12 lines × 2) (src/Model/Component.php)
• Duplicated block (13 lines × 2) (src/ConfigTreeRunner.php)
• Duplicated block (13 lines × 2) (src/Infrastructure/Event/Listener/Analysis/ComponentAnalysisEventListener.php)
• Duplicated block (13 lines × 4) (src/ConfigTreeRunner.php)
• Duplicated block (15 lines × 2) (src/Service/Report/SpaReport/ReportRenderingService.php)
• Duplicated block (5 lines × 2) (src/Infrastructure/Event/Listener/Analysis/FileAnalyzedEventListener.php)
• Duplicated block (6 lines × 2) (src/Infrastructure/Event/Listener/Analysis/AnalysisEventListener.php)
• Duplicated block (7 lines × 2) (src/Infrastructure/Event/Listener/Analysis/ComponentAnalysisEventListener.php)
• Duplicated block (7 lines × 2) (src/Service/Report/History/ReportHistoryStorage.php)
• Duplicated block (8 lines × 2) (src/Infrastructure/Event/Listener/Analysis/AnalysisEventListener.php)
• Duplicated block (8 lines × 2) (src/Service/Report/SpaReport/ReportRenderingService.php)
• Duplicated block (8 lines × 9) (src/ConfigTreeRunner.php)
• Duplicated block (9 lines × 2) (src/Service/Analysis/Event/ComponentAnalysisEvent.php)
• …and 33 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

Chetkov/php-clean-architecture was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.