Rector-Regeln in PhpStorm interaktiv anwenden und Vorschau nutzen

1. Wofuer Rector in einem Magento-Projekt sinnvoll ist

Rector ist ein Werkzeug fuer automatisierte Code-Transformationen: es liest PHP-Code als AST ein, wendet definierte Regeln an und schreibt den transformierten Code zurueck. Typische Anwendungsfaelle in einem Magento-Projekt sind das Nachziehen von Constructor Property Promotion in aelteren Klassen, das Ersetzen veralteter array()-Syntax durch die Kurzform, oder das automatisierte Hinzufuegen von Typdeklarationen, wo PHPStan bereits einen eindeutigen Typ inferieren kann.

Der entscheidende Unterschied zu einer einfachen Suchen-und-Ersetzen-Operation ist, dass Rector den Code strukturell versteht. Eine Regel wie AddVoidReturnTypeWhereNoReturnRector erkennt zuverlaessig, ob eine Methode wirklich nie einen Wert zurueckgibt, auch ueber mehrere verschachtelte Kontrollstrukturen hinweg, und fuegt nur dann den void-Rueckgabetyp hinzu. Das macht Rector fuer grossflaechige Modernisierungen deutlich sicherer als reguläre Ausdrücke.

2. Rector-Unterstuetzung in PhpStorm einrichten

Ueber ein entsprechendes Plugin aus dem PhpStorm-Marketplace laesst sich Rector direkt in die IDE integrieren, sodass Regeln nicht mehr ausschliesslich ueber das Terminal, sondern per Rechtsklick auf eine Datei oder ein Verzeichnis im Projektbaum gestartet werden koennen. Die Integration nutzt im Hintergrund weiterhin das im Projekt per Composer installierte rector/rector-Paket und die dort hinterlegte PHP-Version, sodass keine separate Konfiguration fuer die IDE noetig ist.

Fuer das Docker-Setup von Mark Shust bedeutet das konkret, dass Rector als Dev-Dependency ueber bin/composer require --dev rector/rector installiert wird und anschliessend sowohl ueber bin/cli vendor/bin/rector process als auch ueber die PhpStorm-Integration nutzbar ist, sofern der PHP-Interpreter der IDE korrekt auf den Container gemappt ist.

# Rector als Dev-Dependency installieren
bin/composer require --dev rector/rector

# Testlauf ohne Aenderungen (Dry-Run) direkt im Container
bin/cli vendor/bin/rector process app/code/Mironsoft/SeoSuite --dry-run

3. Projektspezifische rector.php verstehen und in PhpStorm nutzen

Rector wird ueber eine rector.php-Konfigurationsdatei im Projekt-Root gesteuert, in der Regelsets und einzelne Regeln explizit aktiviert werden. Fuer ein Magento-Projekt ist es sinnvoll, den Scope bewusst auf app/code/Mironsoft einzuschraenken und den Vendor-Code sowie generierte Dateien ueber withSkip() explizit auszuschliessen, da Rector sonst versucht, auch Magento-Core-Code zu transformieren, was weder sinnvoll noch gewuenscht ist.

PhpStorm liest diese rector.php beim Start der Integration ein und zeigt in der Regel-Auswahl nur die tatsaechlich im Projekt aktivierten Regeln an, nicht die komplette Rector-Regelbibliothek. Das ist wichtig, weil es verhindert, dass versehentlich eine Regel angewendet wird, die im Projektkontext gar nicht vorgesehen ist, etwa eine Regel aus einem Levelset fuer eine PHP-Version, die im Projekt noch nicht als Zielversion definiert ist.

<?php

declare(strict_types=1);

use Rector\Config\RectorConfig;
use Rector\Php84\Rector\Param\PromoteNullOrFalseFalsyPropertyRector;
use Rector\Set\ValueObject\LevelSetList;

return RectorConfig::configure()
    ->withPaths([__DIR__ . '/app/code/Mironsoft'])
    ->withSkip([
        __DIR__ . '/vendor',
        __DIR__ . '/generated',
    ])
    ->withSets([LevelSetList::UP_TO_PHP_84])
    ->withRules([PromoteNullOrFalseFalsyPropertyRector::class]);

4. Die Diff-Vorschau vor der Anwendung nutzen

Der zentrale Sicherheitsmechanismus, sowohl in der reinen CLI-Nutzung als auch in der PhpStorm-Integration, ist der Dry-Run-Modus. Rector zeigt dabei fuer jede Datei, die eine Regel veraendern wuerde, einen vollstaendigen Diff an, ohne die Datei tatsaechlich zu schreiben. In PhpStorm erscheint dieser Diff im gewohnten Diff-Viewer der IDE, sodass sich Aenderungen Datei fuer Datei durchgehen, einzeln akzeptieren oder verwerfen lassen, statt einen kompletten Batch-Lauf blind zu uebernehmen.

Bei einer Regel wie ClassPropertyAssignToConstructorPromotionRector, die bestehende Property-Zuweisungen im Konstruktor durch Constructor Property Promotion ersetzt, lohnt sich diese Vorschau besonders: Bei Klassen mit komplexer Konstruktorlogik, etwa bedingten Zuweisungen oder zusaetzlicher Validierung im Konstruktorkoerper, kann die automatische Transformation zu semantisch leicht abweichendem Code fuehren. Der Diff macht solche Grenzfaelle sichtbar, bevor sie ungeprueft gemergt werden.

- private StoreManagerInterface $storeManager;
-
- public function __construct(StoreManagerInterface $storeManager)
- {
-     $this->storeManager = $storeManager;
- }
+ public function __construct(
+     private readonly StoreManagerInterface $storeManager
+ ) {
+ }

5. Einzelne Regeln statt kompletter Regelsets anwenden

Statt ein komplettes Levelset wie UP_TO_PHP_84 in einem Durchgang auf ein bestehendes Modul anzuwenden, ist es in der Praxis sicherer, einzelne Regeln nacheinander gezielt auszuwaehlen. Die PhpStorm-Integration erlaubt es, aus der Liste der im Projekt aktivierten Regeln eine einzelne auszuwaehlen und nur diese auf eine Datei oder ein Verzeichnis anzuwenden, was den Diff pro Durchgang deutlich kleiner und einfacher pruefbar macht.

Ein bewaehrtes Vorgehen fuer die Modernisierung eines bestehenden Mironsoft-Moduls: zuerst nur Typdeklarations-Regeln anwenden und committen, danach separat Constructor-Property-Promotion-Regeln, danach Array-Syntax-Regeln. Jeder dieser Schritte erzeugt einen eigenen, klar nachvollziehbaren Commit, was Code-Reviews erheblich erleichtert im Vergleich zu einem einzigen riesigen Rector-Commit mit hunderten Zeilen ueber mehrere thematisch unabhaengige Aenderungen.

6. Fallstricke bei Rector in Magento-Kontexten

Magento nutzt an mehreren Stellen Reflection-basierte Mechanismen, etwa bei der Dependency Injection ueber Konstruktor-Parameter-Namen in di.xml-Virtual-Types oder bei Preferences. Eine Rector-Regel, die Parameter umbenennt oder Konstruktor-Signaturen automatisch aendert, kann in solchen Faellen zu einer stillen Inkompatibilitaet mit der XML-Konfiguration fuehren, die erst zur Laufzeit als Fehler sichtbar wird, nicht bereits bei PHPStan.

Deshalb ist es bei Magento-Projekten wichtig, nach jedem Rector-Lauf, der Konstruktor-Parameter betrifft, gezielt nach zugehoerigen di.xml-Eintraegen zu suchen, die den Parameternamen referenzieren, etwa in argument-name-Attributen. PhpStorm hilft hier durch die projektweite Suche nach dem Parameternamen, aber die Pruefung selbst ersetzt Rector nicht automatisch, sie bleibt ein manueller Nachbereitungsschritt.

<type name="Mironsoft\SeoSuite\Model\MarkupProvider">
    <arguments>
        <argument name="storeManager" xsi:type="object">Magento\Store\Model\StoreManagerInterface</argument>
    </arguments>
</type>

7. Rector und PHPStan als aufeinander abgestimmte Werkzeuge

Rector und PHPStan haben eine natuerliche Reihenfolge: Rector veraendert Code strukturell, PHPStan prueft anschliessend, ob der veraenderte Code weiterhin typkorrekt ist. Nach jedem Rector-Lauf, auch nach einem sorgfaeltig geprueften mit Diff-Vorschau, sollte deshalb bin/analyse app/code/Mironsoft/SeoSuite --level=5 erneut ausgefuehrt werden, um sicherzustellen, dass keine neuen Level-5-Fehler entstanden sind.

In der Praxis zeigt sich, dass viele Rector-Regeln aus dem TypeDeclarationRector-Bereich, etwa AddReturnTypeDeclarationRector, tatsaechlich vorhandene PHPStan-Fehler beheben, weil sie fehlende Typdeklarationen ergaenzen, die PHPStan vorher nur aus PHPDoc oder gar nicht ableiten konnte. Rector kann so aktiv zur PHPStan-Level-5-Konformitaet beitragen, statt nur ein unabhaengiges Modernisierungswerkzeug zu sein.

8. Rector-Laeufe im Team nachvollziehbar dokumentieren

Weil Rector-Commits oft viele Dateien gleichzeitig betreffen, aber inhaltlich mechanisch und risikoarm sind, hat es sich bewaehrt, sie klar von inhaltlichen Aenderungen zu trennen und in der Commit-Message explizit die angewendete Regel oder das Regelset zu nennen. Ein Commit wie 'Rector: ClassPropertyAssignToConstructorPromotionRector auf SeoSuite angewendet' laesst Reviewer sofort einschaetzen, dass es sich um eine mechanische Transformation handelt, nicht um eine funktionale Aenderung.

Fuer den Dual-Vendor-Workflow zwischen Mironsoft- und Abrams-Kopien bedeutet das zusaetzlich, dass ein Rector-Lauf auf beiden Pfaden separat ausgefuehrt werden sollte, da die automatische Transformation nicht wissen kann, dass zwei Verzeichnisse strukturell identischen Code enthalten. Ein Rector-Lauf nur auf der Mironsoft-Kopie ohne den entsprechenden Lauf auf der Abrams-Kopie wuerde die beiden Codebasen sonst schleichend auseinanderlaufen lassen.

9. Praxis-Checkliste fuer einen sicheren Rector-Einsatz

Fuer einen kontrollierten Rector-Einsatz in einem bestehenden Modul hat sich folgende Reihenfolge bewaehrt: rector.php auf das konkrete Modulverzeichnis einschraenken, Dry-Run ausfuehren und den Diff vollstaendig durchgehen, bei Unsicherheit einzelne Regeln statt ganzer Sets anwenden, nach der Anwendung PHPStan erneut laufen lassen, und abschliessend gezielt nach di.xml-Referenzen auf veraenderte Konstruktor-Parameter suchen.

Diese Reihenfolge macht Rector von einem riskanten Batch-Werkzeug zu einem kontrollierten Bestandteil der Modernisierung, bei dem jede Aenderung vor dem tatsaechlichen Schreiben sichtbar war. Der Zeitgewinn gegenueber manueller Modernisierung bleibt dabei erhalten, nur der Kontrollverlust eines unbeaufsichtigten Batch-Laufs entfaellt. Gerade bei einem Modul wie SeoSuite, das ueber Jahre gewachsen ist und viele historisch bedingte Konstruktor-Varianten enthaelt, zahlt sich diese Disziplin unmittelbar aus, weil jede der kleinen Aenderungen einzeln nachvollzogen und im Zweifel auch einzeln zurueckgerollt werden kann, ohne die gesamte Modernisierung zu gefaehrden.

10. Zusammenfassung

11. FAQ: Rector in PhpStorm: Das Wichtigste auf einen Blick