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.
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)
- **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)
Quick Start
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
- Prerequisites
- Installation
- Using the Composer Plugin
- CLI Options
- Subcommands
- Configuration
- Test Analysis
- Report Types
- Source Code Display
- Knowledge Graph Export
- Key Metrics
- AI Integration (MCP Server)
- Understanding the Health Score
- Memory and Performance
- A Note on Metric Accuracy (v2.7.0)
- Development
- Roadmap
- Contributing
Prerequisites
- PHP 8.2 or higher (works on 8.2, 8.3, 8.4, 8.5)
- Composer
Installation
Global Installation
Make sure ~/.composer/vendor/bin (or ~/.config/composer/vendor/bin) is in your $PATH. Then run from any directory:
Docker
Run against a local project:
This mounts your project into the container and writes the HTML report to ./report/.
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 page. The PHAR ships all dependencies bundled, so it works without touching your project's composer.json.