PhpCodeArcheology: Code-Qualität messen, nicht raten

Die meisten statischen Analyse-Tools für PHP sagen dir, was kaputt ist. PHPStan findet Typfehler. Psalm findet Bugs. Das ist wichtig und richtig.

Aber was ist mit den Fragen, die sich nicht um Bugs drehen? Ist die Architektur meines Projekts noch tragfähig? Wo entstehen die nächsten Probleme? Hat mein Refactoring überhaupt geholfen?

Dafür habe ich PhpCodeArcheology gebaut.

Was es ist

PhpCodeArcheology ist ein statisches Analyse-Tool für PHP, das sich auf Architektur und Wartbarkeit konzentriert. Im Gegensatz zu PHPStan oder Psalm (die auf Typsicherheit und Bug-Erkennung abzielen) misst PhpCodeArcheology die strukturelle Gesundheit deiner Codebase.

Man kann es sich als Alternative zu PHPMetrics vorstellen — mit tieferer Git-Integration, Baseline-Management und KI-fähiger Ausgabe.

Was es kann

60+ Metriken auf Datei-, Klassen-, Methoden- und Funktionsebene:

• Cyclomatic Complexity, Cognitive Complexity
• Maintainability Index, LCOM
• Halstead-Metriken, Coupling, Instability
• Type Coverage

14 Problem-Detektoren: God Class, zu komplexe Methoden, toter Code, zirkuläre Abhängigkeiten, tiefe Vererbung, Security Smells, SOLID-Verletzungen, niedrige Type Coverage, untesteter komplexer Code — und mehr.

Health Score: Eine einzelne Zahl von 0-100 mit A-F Bewertung. Destilliert Komplexität, Coupling, Kohäsion, Testabdeckung und Churn in einen Wert.

Git-Integration: Churn-Analyse, Hotspot-Erkennung (Dateien mit hoher Änderungsfrequenz UND hoher Komplexität), Author-Tracking.

6 Report-Formate: HTML (interaktives Dashboard), Markdown, JSON, SARIF (für GitHub Code Scanning), AI-Summary, Knowledge Graph.

Baseline-Management: Aktuellen Problemstand als Baseline speichern. Ab dann werden nur noch neue Probleme gemeldet. Ideal für Teams, die nicht alles auf einmal fixen können, aber verhindern wollen, dass es schlimmer wird.

MCP-Support für KI-Assistenten

PhpCodeArcheology ist das erste PHP-Analyse-Tool mit nativem MCP-Support (Model Context Protocol). Das bedeutet: KI-Assistenten wie Claude können deine Analyse-Ergebnisse direkt abfragen — ohne Dateien zu parsen oder JSON zu interpretieren.

Einrichtung mit Claude Code:

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

Danach stehen 11 MCP-Tools zur Verfügung: Health Score abfragen, Probleme filtern, Metriken für einzelne Klassen holen, Hotspots anzeigen, Refactoring-Prioritäten ermitteln, Abhängigkeiten analysieren, Impact-Analyse durchführen, Testabdeckung prüfen.

Die KI kennt damit deinen Code nicht nur syntaktisch, sondern versteht seine architektonische Qualität.

Schnellstart

Installation:

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

Analyse starten — ohne Konfiguration:

./vendor/bin/phpcodearcheology

Das scannt dein src/-Verzeichnis und erstellt einen HTML-Report in tmp/report. Fertig. Keine Config-Datei nötig.

Für den schnellen Überblick im Terminal:

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

Wann es sich lohnt

• Du übernimmst ein Legacy-Projekt und willst verstehen, wo die Leichen liegen
• Du willst nach einem Refactoring objektiv wissen, ob es geholfen hat (compare-Command)
• Du brauchst einen Quality Gate in deiner CI-Pipeline (--fail-on=error)
• Du willst deinem KI-Assistenten Kontext über die Code-Qualität geben (MCP-Server)
• Du willst im Team transparent über Code-Qualität sprechen — mit Zahlen statt Bauchgefühl

Links

• GitHub: PhpCodeArcheology/PhpCodeArcheology
• Dokumentation: phpcodearcheology.github.io
• Lizenz: MIT — frei nutzbar, auch kommerziell

PhpCodeArcheology ist Open Source und wird aktiv weiterentwickelt. Feedback, Issues und Contributions sind willkommen — direkt auf GitHub.