Automatisierte PHP-Upgrades mit Rector: Möglichkeiten und Grenzen

Sie haben eine PHP-7.4-Anwendung, die seit Jahren zuverlässig läuft, und die Frage steht im Raum: Wie kommen Sie auf PHP 8.3, ohne monatelang stumpfe Syntax-Änderungen von Hand nachzuziehen? Genau hier kommt Rector ins Spiel. Das Werkzeug verspricht automatisierte Code-Transformationen im großen Stil. Die ehrliche Antwort vorweg: Rector ist exzellent für das, wofür es gebaut wurde — und nutzlos für das, was viele fälschlich davon erwarten. Dieser Artikel zeigt Ihnen die Grenze zwischen beidem.

Was macht ein Rector PHP Upgrade eigentlich?

Rector ist ein Kommandozeilen-Tool, das Ihren PHP-Quellcode über den abstrakten Syntaxbaum (AST) analysiert und nach festen Regeln umschreibt. Anders als ein einfaches Such-und-Ersetzen versteht Rector die Struktur des Codes — es weiß, was eine Methode, ein Typ oder ein Funktionsaufruf ist.

Konkret bedeutet das: Sie definieren in einer rector.php ein Set von Regeln oder ein fertiges Set wie LevelSetList::UP_TO_PHP_83, lassen erst vendor/bin/rector process --dry-run laufen und sehen als Diff, was Rector ändern würde. Erst der Lauf ohne --dry-run schreibt die Dateien tatsächlich um. Dieser Dry-Run ist kein Detail, sondern Ihre wichtigste Sicherheitsstufe.

Wofür sich Rector wirklich lohnt

Die Stärke liegt bei repetitiven, mechanischen Änderungen, die über hunderte Dateien identisch sind. Genau diese Arbeit ist fehleranfällig, wenn ein Mensch sie manuell macht, und langweilig genug, dass Konzentrationsfehler garantiert sind.

• PHP-Versions-Upgrades: curly-brace-Array-Zugriff ($arr{0}) auf eckige Klammern umstellen, each() ersetzen, ternäre Ausdrücke klammern, Union-Types und Konstruktor-Property-Promotion einführen.
• Framework-Migrationen: Rector pflegt dedizierte Regelsätze für Symfony und teilweise für Laravel-Umgebungen, etwa um veraltete Service-Definitionen oder umbenannte Klassen automatisch anzupassen.
• Annotations zu Attributen: Der Wechsel von Doctrine- oder Symfony-Annotations (@ORM\Entity) auf native PHP-8-Attribute (#[ORM\Entity]) über eine große Codebasis von Hand ist eine Zumutung — Rector erledigt das in Minuten.
• Code-Qualität: Sets wie DEAD_CODE oder CODE_QUALITY entfernen ungenutzte Variablen und vereinfachen unnötig komplexe Konstrukte.

Für diese Klassen von Änderungen ist ein Rector PHP Upgrade nicht nur schneller als Handarbeit, sondern konsistenter. Das Tool wendet dieselbe Regel auf jede Fundstelle gleich an — es wird nicht müde und übersieht nichts.

Wo die Grenzen von Rector liegen

Und jetzt der Teil, den Verkaufsseiten gern weglassen. Rector transformiert Syntax und bekannte Muster. Es versteht Ihre Fachlogik nicht. Sobald eine Änderung ein Verständnis dafür verlangt, warum Ihr Code etwas tut, ist Rector am Ende.

• Verhaltensänderungen der PHP-Runtime: Wenn eine PHP-Version die Rückgabe einer Funktion oder das Fehlerverhalten ändert (etwa strengere Typprüfungen), kann Rector die Syntax anpassen, aber nicht entscheiden, ob Ihre umgebende Logik damit noch korrekt ist.
• Dynamischer Code: Aufrufe über call_user_func, Magic Methods, variable Variablen oder reflection-getriebene Konstrukte sind für den statischen AST-Ansatz teils unsichtbar. Rector kann nur umschreiben, was es statisch erkennt.
• Architektur-Entscheidungen: Rector führt keine Schichten ein, entkoppelt keine God-Klasse und ersetzt kein selbstgebautes ORM. Solche Umbauten verlangen Urteilsvermögen, das kein Regelsatz abbildet.
• SQL und Infrastruktur: Datenbank-Migrationen, Änderungen an Stored Procedures oder veraltete mysql_*-Funktionen in Kombination mit Geschäftslogik brauchen menschliche Prüfung, auch wenn Rector die reine Funktionsumbenennung mitnimmt.

Wie sicher ist ein automatisiertes Rector PHP Upgrade?

Ein Rector-Lauf ist nur so sicher wie Ihre Testabdeckung. Rector garantiert, dass der Code nach der Transformation syntaktisch gültig und meist auch funktional äquivalent ist — aber ausschließlich für die Muster, die eine Regel abdeckt. Ob Ihre Anwendung sich danach fachlich noch identisch verhält, weiß nur Ihre Testsuite.

Das ist der Kern: Eine gewachsene Anwendung, die seit Jahren im Produktivbetrieb läuft, hat ihre Fachlogik längst bewiesen. Das Problem ist selten diese Logik, sondern der Code drumherum — veraltete Syntax, alte Framework-Versionen, fehlende Typen. Genau dieses Drumherum ist Rectors Zuhause. Bevor Sie aber einen einzigen Regelsatz scharf schalten, brauchen Sie ein Sicherheitsnetz.

Vorgehen: Rector in fünf realistischen Schritten

1. Charakterisierungstests schreiben. Wo automatisierte Tests fehlen, sichern Sie kritische Abläufe zuerst mit Tests ab, die das heutige Verhalten festhalten — auch wenn es fachlich fragwürdig aussieht.
2. Klein anfangen. Wenden Sie ein einzelnes Set (etwa nur die nächste PHP-Minor-Version) auf ein einzelnes Verzeichnis an, nicht das ganze Projekt auf einmal.
3. Dry-Run lesen, nicht überfliegen. Der Diff aus --dry-run ist Ihre Reviewgrundlage. Jede Regel, die Sie nicht verstehen, deaktivieren Sie, bis Sie sie verstehen.
4. In kleinen Commits mergen. Ein Set pro Commit. Bricht später etwas, ist die Ursache in Minuten gefunden statt in einem 4000-Zeilen-Sammel-Diff.
5. Testsuite und statische Analyse nachschalten. Lassen Sie nach jedem Set die Tests und ein Tool wie PHPStan laufen. Rot bedeutet: eine Regel hat eine Annahme getroffen, die für Ihren Code nicht galt.

Rector ersetzt keine Neuentwicklung — und das ist gut so

Wer glaubt, Rector modernisiere eine Alt-Anwendung per Knopfdruck, wird enttäuscht. Wer versteht, dass Rector die mechanische Hälfte einer Migration übernimmt, gewinnt Wochen. Die andere Hälfte — das Urteil darüber, was der Code bedeuten soll — bleibt bei Ihnen. Und das ist die Hälfte, die den Wert Ihrer Anwendung ausmacht.

Das relativiert auch den oft reflexhaften Ruf nach Neuentwicklung. Eine Neuentwicklung wirft nicht nur den alten Code weg, sondern das über Jahre eingesammelte, oft undokumentierte Fachwissen darin. Sie ist in aller Regel die teuerste und riskanteste Option. Ein Rector-gestütztes Upgrade ist meist der pragmatischere Weg: Sie behalten die bewährte Logik und erneuern gezielt das Fundament darunter.

Praxis-Tipp: Aktivieren Sie niemals ein komplettes LevelSetList über mehrere PHP-Versionen auf einmal. Gehen Sie Minor-Version für Minor-Version, jede mit eigener Testrunde. Der große Sprung spart auf dem Papier Zeit und kostet sie in der Fehlersuche doppelt zurück.

Wenn Sie vor genau so einem Upgrade stehen und unsicher sind, welche Änderungen Sie Rector überlassen können und welche menschliche Prüfung brauchen, unterstützt LegacyWerk bei der Modernisierung gewachsener PHP-Anwendungen — vom Sicherheitsnetz aus Tests bis zum kontrollierten Versionssprung.