PHPMD 3 Upgrade, so migriert ihr von Version 2 ohne kaputte Pipeline

Das PHPMD 3 Upgrade beginnt meist mit einer roten Pipeline. Renovate oder Dependabot heben die Version an, der Merge Request sieht harmlos aus, und dann bricht der Job ab. Die Option --reportfile gibt es nicht mehr. Der Aufruf phpmd src text codesize wird nicht mehr verstanden. Und ein Skript, das auf Exit Code 1 prüft, meldet plötzlich Erfolg, obwohl PHPMD gar nicht gelaufen ist.

Version 3 ist das größte Update in der Geschichte des PHP Mess Detector. Es lohnt sich. Ihr bekommt parallele Analyse, YAML Konfiguration und Attribute statt Kommentaren. Hier steht, wie ihr in sechs Schritten umsteigt, ohne dass euer Team einen Tag lang Pipelines repariert.

Was sich mit PHPMD 3 ändert

PHPMD sucht in PHP Code nach Stellen, die schwer zu warten sind. Zu lange Methoden, zu komplexe Klassen, ungenutzte Variablen, schlechte Namen. Was das Tool im Detail kann und wie es sich von PHPStan unterscheidet, steht in unserem Glossar zum PHP Mess Detector.

Für das Upgrade zählen vor allem diese Punkte aus den Release Notes zu PHPMD 3.0.0:

• PHPMD 3 braucht mindestens PHP 8.1 und baut auf PDepend 3 auf.
• Die Kommandozeile läuft über Symfony Console. Der Aufruf heißt jetzt phpmd analyze.
• Mehrere Optionen sind umbenannt oder entfernt.
• Bei Verarbeitungsfehlern endet PHPMD mit Exit Code 3 statt 1.
• Grenzwerte melden erst, wenn ein Wert über dem Maximum liegt.
• Das Attribut #[SuppressWarnings] ersetzt den Kommentar.

Schritt 1, die PHP Version der Pipeline prüfen

Bevor ihr irgendetwas anfasst, schaut auf die PHP Version, mit der PHPMD in der Pipeline läuft. Das ist nicht immer die Version eurer Anwendung. Viele Teams fahren die Qualitätstools in einem eigenen Container. Läuft der noch unter PHP 8.1, bleibt euch nur PHPMD 2. Hebt dann zuerst das Image an.

Schritt 2, PHPMD per Composer aktualisieren

Das Update selbst ist ein Befehl. PDepend 3 kommt als Abhängigkeit automatisch mit.

composer require --dev "phpmd/phpmd:^3.0"

Macht das Update in einem eigenen Branch, getrennt von anderen Abhängigkeiten. So seht ihr sofort, ob ein roter Job von PHPMD kommt oder von etwas anderem.

Schritt 3, alte XML Rulesets mit phpmd migrate umwandeln

PHPMD 3 liest weiter XML. Neu sind YAML, JSON und PHP als Formate für die Konfiguration. Der Befehl phpmd migrate wandelt eure bestehende XML Datei in YAML um. Die genauen Optionen zeigt euch phpmd migrate --help. Ohne bestehende Datei legt phpmd init eine neue phpmd.yml mit einem kurzen Assistenten an.

vendor/bin/phpmd migrate --help
vendor/bin/phpmd init

Prüft danach eure Grenzwerte. Die Properties reportLevel, minimum, maxfields und maxmethods heißen jetzt einheitlich maximum. Die alten Namen funktionieren als Alias weiter. Wichtiger ist eine andere Änderung. Regeln melden erst über dem Maximum. Eine Methode, die genau auf dem Grenzwert liegt, wurde früher gemeldet und rutscht jetzt durch. Wollt ihr das alte Verhalten behalten, senkt den Wert um eins.

Schritt 4, Aufrufe und Optionen in den Skripten anpassen

Sucht in Makefile, composer.json Scripts, Git Hooks und CI Dateien nach jedem Aufruf von PHPMD. Diese Optionen müsst ihr ersetzen:

PHPMD 2	PHPMD 3
phpmd src text codesize	phpmd analyze --ruleset codesize src
--ignore	--exclude
--extensions	--suffixes
--reportfile	--reportfile-text, --reportfile-xml und weitere je Format
--minimumpriority	--minimum-priority
--maximumpriority	--maximum-priority

Ein typischer Aufruf in der Pipeline sieht danach so aus:

vendor/bin/phpmd analyze --no-progress --ruleset codesize --ruleset unusedcode src/

Die Option --no-progress hält das Log sauber. Die Fortschrittsanzeige landet sonst auf stderr und macht CI Logs unnötig lang. Für große Projekte lohnt sich zusätzlich --threads, damit PHPMD Dateien parallel parst.

Schritt 5, Exit Codes in der CI prüfen

Dieser Schritt wird am häufigsten vergessen. PHPMD endet mit 0, wenn alles sauber ist, und mit 2, wenn Regelverstöße gefunden wurden. Kann PHPMD gar nicht arbeiten, etwa wegen einer kaputten Konfiguration, kommt jetzt eine 3. Früher war das eine 1.

GitHub Actions und GitLab CI lassen den Job bei jedem Code ungleich 0 scheitern. Da passiert nichts. Gefährlich sind eigene Skripte, die Exit Codes auswerten. Ein Skript, das nur auf 1 als Fehler prüft, behandelt die 3 als Erfolg. Dann läuft eure Pipeline grün, obwohl gar keine Analyse stattgefunden hat.

vendor/bin/phpmd analyze --no-progress src/
status=$?

if [ "$status" -eq 3 ]; then
  echo "PHPMD konnte nicht laufen"
  exit 1
fi

if [ "$status" -eq 2 ]; then
  echo "PHPMD hat Regelverstöße gefunden"
  exit 1
fi

Wie PHPMD mit PHPStan, Tests und Code Stil zu einer festen Kette in der Pipeline wird, zeigt unser Beitrag zu Quality Gates in der Pipeline.

Schritt 6, Kommentare durch Attribute ersetzen

Bisher habt ihr einzelne Meldungen mit @SuppressWarnings(PHPMD.UnusedLocalVariable) im Kommentar unterdrückt. Das funktioniert weiter, gilt aber als veraltet. Der neue Weg ist ein Attribut mit der Klasse der Regel.

use PHPMD\Attribute\SuppressWarnings;
use PHPMD\Rule\UnusedLocalVariable;

#[SuppressWarnings(UnusedLocalVariable::class)]
public function example()
{
    $unused = 42;
}

Der Vorteil zeigt sich nach dem Umbau. Die neue Regel UnusedSuppression meldet Attribute, die nichts mehr unterdrücken. In gewachsenen Projekten sammeln sich solche Ausnahmen über Jahre. Mit dieser Regel räumt ihr sie Stück für Stück weg. Für alte Kommentare greift sie allerdings nicht. Auch deshalb lohnt sich der Wechsel auf Attribute.

Die Baseline nach dem Upgrade neu aufbauen

Nutzt ihr eine Baseline, prüft sie nach dem Upgrade. Die geänderten Grenzwerte und neuen Regeln können zusätzliche Meldungen erzeugen. Erzeugt die Baseline einmal bewusst neu und committet sie in einem eigenen Commit. Dann sieht jeder im Review, was sich verschoben hat.

vendor/bin/phpmd analyze --ruleset codesize --generate-baseline src/

Danach arbeitet --update-baseline strenger als früher. Neue Verstöße landen nicht mehr still in der Datei. PHPMD gibt sie aus und endet mit Exit Code 2. So wächst die Altlast nicht heimlich weiter. Alle Details zur Umstellung stehen im offiziellen Upgrade Guide von PHPMD.

Warum PHPMD auch Coding Agents hilft

Coding Agents schreiben Code, der läuft. Ob eine Methode nach drei Runden Nacharbeit 200 Zeilen hat, kümmert sie wenig. Tests bleiben grün, PHPStan meckert nicht, und die Komplexität steigt still mit jedem Auftrag.

PHPMD gibt dem Agent eine klare Grenze. Läuft die Analyse als Quality Gate, bekommt der Agent eine konkrete Meldung zurück. Welche Methode, welche Regel, welcher Wert. Mit diesem Feedback kann er selbst nachbessern, bevor ein Mensch den Pull Request liest. Das spart Review Zeit und hält den Code für die nächste Änderung lesbar. Unser Grundsatz bleibt gleich: erst Quality Gates, dann KI.

Wie sich Agents mit klaren Grenzen im Zaum halten lassen, zeigt auch unser Beitrag zu Scope Creep bei Coding Agents. Und warum Refactoring mit KI ohne solche Leitplanken schnell schiefgeht, steht in KI Refactoring zerstört die Applikation.

Häufige Fragen zum PHPMD 3 Upgrade

Muss ich sofort auf PHPMD 3 umsteigen?

Nein. PHPMD 2 läuft weiter. Neue Regeln, parallele Analyse und die Unterstützung für Attribute gibt es aber nur in Version 3. Plant den Umstieg als eigenen Schritt mit eigenem Branch.

Funktionieren meine alten XML Rulesets noch?

Ja, PHPMD 3 liest XML weiter. Mit phpmd migrate könnt ihr sie in YAML umwandeln. Prüft danach die Grenzwerte, weil Regeln jetzt erst über dem Maximum melden.

Brauche ich PHPMD, wenn ich schon PHPStan nutze?

Beide Tools prüfen verschiedene Dinge. PHPStan findet Fehler wie falsche Typen. PHPMD findet Wartungsprobleme wie zu lange Methoden und hohe Komplexität. In Legacy Projekten ist die Kombination sinnvoll. Einen Überblick über weitere Tools gibt unser Beitrag zu den besten PHP Refactoring Tools.

Fazit

Das PHPMD 3 Upgrade ist kein großes Projekt, wenn ihr es in Ruhe macht. PHP Version prüfen, per Composer aktualisieren, Konfiguration migrieren, Aufrufe anpassen, Exit Codes prüfen und Kommentare durch Attribute ersetzen. Danach habt ihr ein schnelleres Tool, eine sauberere Konfiguration und ein Quality Gate, das auch Coding Agents verstehen.