PhpCodeArcheology: Measure Code Quality, Don't Guess

Most PHP static analysis tools tell you what’s broken. PHPStan finds type errors. Psalm finds bugs. That’s important work.

But what about the questions that aren’t about bugs? Is my project’s architecture still sound? Where will the next problems emerge? Did my refactoring actually help?

That’s why I built PhpCodeArcheology.

What it is

PhpCodeArcheology is a PHP static analysis tool focused on architecture and maintainability. Unlike PHPStan or Psalm (which target type safety and bug detection), PhpCodeArcheology measures the structural health of your codebase.

Think of it as an alternative to PHPMetrics — with deeper git integration, baseline management, and AI-ready output.

What it does

60+ metrics at file, class, method, and function level:

• Cyclomatic complexity, cognitive complexity
• Maintainability index, LCOM
• Halstead metrics, coupling, instability
• Type coverage

14 problem detectors: God Class, overly complex methods, dead code, circular dependencies, deep inheritance, security smells, SOLID violations, low type coverage, untested complex code — and more.

Health Score: A single 0–100 number with A–F grading. Distils complexity, coupling, cohesion, test coverage, and churn into one value.

Git integration: Churn analysis, hotspot detection (files with high change frequency AND high complexity), author tracking.

6 report formats: HTML (interactive dashboard), Markdown, JSON, SARIF (for GitHub Code Scanning), AI summary, knowledge graph.

Baseline management: Save the current problem set as a baseline. From that point on, only new problems are reported. Ideal for teams who can’t fix everything at once but need to stop things from getting worse.

MCP support for AI assistants

PhpCodeArcheology is the first PHP analysis tool with native MCP support (Model Context Protocol). AI assistants like Claude can query your analysis results directly — no file parsing or JSON interpretation needed.

Setup with Claude Code:

claude mcp add phpcodearcheology -- vendor/bin/phpcodearcheology mcp

This gives you 11 MCP tools: query the health score, filter problems, get metrics for individual classes, view hotspots, determine refactoring priorities, analyse dependencies, run impact analysis, check test coverage.

Your AI assistant doesn’t just know your code syntactically — it understands its architectural quality.

Quick start

Installation:

composer require --dev php-code-archeology/php-code-archeology

Run the analysis — no config needed:

./vendor/bin/phpcodearcheology

This scans your src/ directory and generates an HTML report in tmp/report. Done. No config file required.

For a quick terminal overview:

./vendor/bin/phpcodearcheology --quick src/

When it’s worth using

• You inherit a legacy project and want to know where the bodies are buried
• You want to objectively verify whether a refactoring helped (compare command)
• You need a quality gate in your CI pipeline (--fail-on=error)
• You want to give your AI assistant context about code quality (MCP server)
• You want to discuss code quality in your team — with numbers, not gut feelings

Links

• GitHub: PhpCodeArcheology/PhpCodeArcheology
• Documentation: phpcodearcheology.github.io
• License: MIT — free to use, including commercially

PhpCodeArcheology is open source and actively maintained. Feedback, issues, and contributions are welcome — directly on GitHub.