PHPackages php-code-archeology/php-code-archeology - 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. [Testing & Quality](/categories/testing) 4. / 5. php-code-archeology/php-code-archeology ActiveComposer-plugin[Testing & Quality](/categories/testing) php-code-archeology/php-code-archeology ======================================= Static analyzer for PHP project archeology. Calculates various metrics for your codebase. v2.11.0(2mo ago)825.2k↑440%7[6 issues](https://github.com/PhpCodeArcheology/PhpCodeArcheology/issues)[11 PRs](https://github.com/PhpCodeArcheology/PhpCodeArcheology/pulls)MITPHPPHP >=8.2CI passing Since Jul 14Pushed 2w ago2 watchersCompare [ Source](https://github.com/PhpCodeArcheology/PhpCodeArcheology)[ Packagist](https://packagist.org/packages/php-code-archeology/php-code-archeology)[ Docs](https://PhpCodeArcheology.org)[ GitHub Sponsors](https://github.com/marcuskober)[ RSS](/packages/php-code-archeology-php-code-archeology/feed)WikiDiscussions main Synced yesterday READMEChangelog (10)Dependencies (25)Versions (68)Used By (0) [![PhpCodeArcheology Logo](docs/logo.svg)](docs/logo.svg) PhpCodeArcheology ================= [](#phpcodearcheology) [![Packagist Version](https://camo.githubusercontent.com/3090f82d1f49894d7d668d7bb14ee922fbc6adec626f2adb8a607aa8267e112a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7068702d636f64652d61726368656f6c6f67792f7068702d636f64652d61726368656f6c6f6779)](https://packagist.org/packages/php-code-archeology/php-code-archeology)[![PHP Version](https://camo.githubusercontent.com/a60bdd70d56d0e8f5e4435a12a8c3ff44ae5bf9c64334312993841860dcab6e2/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f7068702d636f64652d61726368656f6c6f67792f7068702d636f64652d61726368656f6c6f6779)](https://packagist.org/packages/php-code-archeology/php-code-archeology)[![License](https://camo.githubusercontent.com/03001f1b982fe753eff0e089a2b68956c1eb662212fcbb2401fabac286ecbb3f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f7068702d636f64652d61726368656f6c6f67792f7068702d636f64652d61726368656f6c6f6779)](https://packagist.org/packages/php-code-archeology/php-code-archeology)[![PhpCodeArcheology MCP server](https://camo.githubusercontent.com/6347bd3ec1ccb79f8c9235f519ff75e03a1d3926a52be2ccd0be79bf9ce5e211/68747470733a2f2f676c616d612e61692f6d63702f736572766572732f506870436f646541726368656f6c6f67792f506870436f646541726368656f6c6f67792f6261646765732f73636f72652e737667)](https://glama.ai/mcp/servers/PhpCodeArcheology/PhpCodeArcheology) **PhpCodeArcheology** is a PHP static analysis tool that measures code quality through 60+ metrics including cyclomatic complexity, maintainability index, coupling, and cohesion. It generates comprehensive reports for files, classes, methods, and functions — detecting code smells, identifying hotspots via git churn analysis, and tracking quality trends over time. Unlike PHPStan or Psalm (which focus on type safety and bug detection), PhpCodeArcheology focuses on **architecture and maintainability** — giving you the insights you need to understand and improve your codebase structure. Think of it as an alternative to PHPMetrics with deeper git integration, baseline management, and AI-ready output. [![PhpCodeArcheology Dashboard](docs/screenshot-dashboard-v2.8.0.png)](docs/screenshot-dashboard-v2.8.0.png) Features -------- [](#features) - **60+ code quality metrics** per file, class, and function — cyclomatic complexity, cognitive complexity, maintainability index, LCOM, Halstead metrics, coupling, instability, and more - **Problem detection** with 14 built-in rules — God Class, too complex, dead code, security smells, SOLID violations, deep inheritance, low type coverage, untested complex code - **Test analysis** — auto-detects PHPUnit/Pest/Codeception, maps test files to production classes, integrates Clover XML for line-level coverage, highlights untested hotspots - **Git integration** — churn analysis, hotspot detection (high churn + high complexity), author tracking - **Source code display** — view method source code directly in the HTML report with PHP syntax highlighting and a nesting-depth heatmap that reveals complexity hotspots at a glance ([details below](#source-code-display)) - **Multiple report formats** — interactive HTML, Markdown, JSON, SARIF (GitHub Code Scanning), AI summary, Knowledge Graph (JSON) - **Health Score** — single 0-100 score with A-F grading for your entire project - **Technical Debt Score** — weighted problem score normalised per 100 logical lines of code - **History tracking** — trend charts across multiple analysis runs - **Baseline management** — track only new problems, ignore existing ones (ideal for legacy projects) - **CI/CD ready** — configurable exit codes, SARIF for GitHub Code Scanning, JSON for custom tooling - **Quick mode** — fast terminal-only output without report generation - **CLAUDE.md generation** — auto-generated project overview for AI coding assistants - **AI integration** — native MCP server for AI assistants like Claude Code ([details below](#ai-integration-mcp-server)) Quick Start ----------- [](#quick-start) ``` composer require --dev php-code-archeology/php-code-archeology ./vendor/bin/phpcodearcheology ``` No config file needed — the tool works out of the box. It scans your `src` directory and creates an HTML report in `tmp/report`. Open `tmp/report/index.html` in your browser. > **Tip:** Add `tmp/report` to your `.gitignore` to keep generated reports out of version control. Table of Contents ----------------- [](#table-of-contents) - [Prerequisites](#prerequisites) - [Installation](#installation) - [Using the Composer Plugin](#using-the-composer-plugin) - [CLI Options](#cli-options) - [Subcommands](#subcommands) - [Configuration](#configuration) - [Test Analysis](#test-analysis) - [Report Types](#report-types) - [Source Code Display](#source-code-display) - [Knowledge Graph Export](#knowledge-graph-export) - [Key Metrics](#key-metrics) - [AI Integration (MCP Server)](#ai-integration-mcp-server) - [Understanding the Health Score](#understanding-the-health-score) - [Memory and Performance](#memory-and-performance) - [A Note on Metric Accuracy (v2.7.0)](#a-note-on-metric-accuracy-v270) - [Development](#development) - [Roadmap](#roadmap) - [Contributing](#contributing) Prerequisites ------------- [](#prerequisites) - PHP 8.2 or higher (works on 8.2, 8.3, 8.4, 8.5) - Composer Installation ------------ [](#installation) ``` composer require --dev php-code-archeology/php-code-archeology ``` ### Global Installation [](#global-installation) ``` composer global require php-code-archeology/php-code-archeology ``` Make sure `~/.composer/vendor/bin` (or `~/.config/composer/vendor/bin`) is in your `$PATH`. Then run from any directory: ``` phpcodearcheology /path/to/your/project ``` ### Docker [](#docker) ``` docker build -t phpcodearcheology https://github.com/PhpCodeArcheology/PhpCodeArcheology.git ``` Run against a local project: ``` docker run --rm -v "$(pwd)":/project -v "$(pwd)/report":/output phpcodearcheology /project ``` This mounts your project into the container and writes the HTML report to `./report/`. ### PHAR (for legacy codebases) [](#phar-for-legacy-codebases) If your project has dependency conflicts with PhpCodeArcheology's requirements (e.g. an older `nikic/php-parser` version), download the standalone PHAR from the [Releases](https://github.com/PhpCodeArcheology/PhpCodeArcheology/releases) page. The PHAR ships all dependencies bundled, so it works without touching your project's `composer.json`. ``` # Download the PHAR and checksum from the latest release curl -LO https://github.com/PhpCodeArcheology/PhpCodeArcheology/releases/latest/download/phpcodearcheology.phar curl -LO https://github.com/PhpCodeArcheology/PhpCodeArcheology/releases/latest/download/phpcodearcheology.phar.sha256 # Verify checksum shasum -a 256 -c phpcodearcheology.phar.sha256 # macOS sha256sum -c phpcodearcheology.phar.sha256 # Linux # Run it (PHP 8.2+) php phpcodearcheology.phar --quick src/ ``` Use the PHAR when: your project's dependencies collide with PhpCodeArcheology's, you want a CI step without a `composer require --dev`, or you analyse a legacy codebase where adding dev-deps is risky. Using the Composer Plugin ------------------------- [](#using-the-composer-plugin) PhpCodeArcheology registers itself as a Composer plugin, so you can run the analysis directly via Composer: ``` composer codearch:analyze ``` When no path is given and no config file exists, it automatically detects your PSR-4 source directories from `composer.json`. All CLI options are supported: ``` composer codearch:analyze -- --quick composer codearch:analyze -- --report-type=json --coverage-file=clover.xml composer codearch:analyze -- src/ lib/ ``` To create a config file interactively: ``` ./vendor/bin/phpcodearcheology init ``` CLI Options ----------- [](#cli-options) ``` ./vendor/bin/phpcodearcheology [options] [path...] ``` OptionDescription`--report-type=TYPE`Report format: `html` (default), `markdown`, `json`, `sarif`, `ai-summary`, `graph`. Comma-separated for multiple: `html,json``--report-dir=DIR`Output directory (default: `tmp/report`)`--quick`Fast analysis with terminal output only, no report generation`--no-color`Disable coloured terminal output (also respects `NO_COLOR` env)`--fail-on=LEVEL`Exit 1 on `error` or `warning` (for CI pipelines)`--generate-claude-md`Generate a `CLAUDE.md` project overview`--git-root=DIR`Git repository root (default: current directory)`--extensions=EXT`File extensions to analyse (comma-separated, default: `php`)`--exclude=DIR`Directories to exclude (comma-separated)`--coverage-file=FILE`Clover XML coverage file from PHPUnit/Pest for line-level coverage data`--source-code`Include source code with syntax highlighting and nesting heatmap in the HTML report ([details below](#source-code-display))`--version`Show versionSubcommands ----------- [](#subcommands) ### `init` — Create Config File [](#init--create-config-file) ``` ./vendor/bin/phpcodearcheology init ``` Interactively creates a `php-codearch-config.yaml` with sensible defaults. Detects common source directories (`src`, `app`, `lib`) automatically. ### `compare` — Compare Two Reports [](#compare--compare-two-reports) ``` ./vendor/bin/phpcodearcheology compare report-before.json report-after.json ``` Shows a delta view of metrics, problem counts, and lists new/resolved problems. Useful for answering: "Did my refactoring actually help?" ### `baseline` — Track New Problems Only [](#baseline--track-new-problems-only) ``` ./vendor/bin/phpcodearcheology baseline create src ./vendor/bin/phpcodearcheology baseline check src ``` `create` saves the current problem set as a baseline. `check` runs a fresh analysis and reports only problems that are **new** compared to the baseline. Returns exit code 1 if new errors are found — ideal for CI pipelines on legacy projects. Configuration ------------- [](#configuration) Create a `php-codearch-config.yaml` in your project root (or use `init`): ``` include: - "src" exclude: - "vendor" extensions: - "php" packageSize: 2 reportDir: "tmp/report" reportType: "html" git: enable: true since: "6 months ago" root: "." # Git repository root (useful for monorepos or subdirectory analysis) graph: methodCalls: true # Track cross-class method calls in the knowledge graph (default: true) php: version: "8.2" # Target PHP version for parsing (default: host PHP version) shortOpenTags: false # Treat