Die Einführung von statischer Analyse in Legacy-PHP besteht nicht darin, die strengste Stufe eines Tools zu aktivieren und Tausende von Warnungen zu beheben. In einer Anwendung mit verstreuten Geschäftsregeln, alten Abhängigkeiten und wenigen Tests vermischt dieser Ansatz potenziell schwerwiegende Defekte mit historischer technischer Schuld, bremst das Team und kann unsichere Änderungen begünstigen.
Das anfängliche Ziel ist ein anderes: Jede neue Änderung soll besser überprüfbar werden, die Unsicherheit in wichtigen Abläufen soll sinken, und es soll ein expliziter Weg zur Behandlung bestehender technischer Schuld vorhanden sein. Statische Analyse liefert strukturelle Informationen über den Code; die Modernisierung erfordert darüber hinaus Produktentscheidungen, Tests und Auslieferungskontrollen.
Warum das gleichzeitige Aktivieren aller Regeln die Wartung meist lähmt
Ein Legacy-Projekt kann implizite Typen, nicht dokumentierte Nullwerte, Methoden mit zu vielen Verantwortlichkeiten, direkten Zugriff auf globale Variablen, nicht erreichbaren Code und mehrdeutige Verträge zwischen Schichten ansammeln. Wird das gesamte Repository vom ersten Tag an mit strengen Regeln analysiert, entsteht meist eine zu umfangreiche Liste, um Prioritäten zu setzen.
Das Problem ist nicht nur das Volumen. Jede Warnung erfordert Kontext: Ein scheinbar falscher Aufruf kann durch eine externe Bedingung geschützt sein, eine Abhängigkeit kann unvollständige Annotationen verwenden oder eine lokale Konvention kann im Code nicht abgebildet sein. Eine Korrektur ohne Verständnis dieses Kontexts kann ein Geschäftsverhalten verändern, das niemand dokumentiert hat.
Außerdem sollten zwei Ziele getrennt werden, die häufig verwechselt werden:
- Sichtbarkeit: Risiken und Bereiche mit unsicheren Verträgen kennen.
- Änderungskontrolle: verhindern, dass eine Änderung neue erkennbare Probleme einführt.
- Schuldenabbau: historische Befunde priorisiert beseitigen.
Das zweite Ziel ist der beste Ausgangspunkt. Es ermöglicht eine bessere Auslieferungsqualität, ohne die umfassende Korrektur zur Voraussetzung für die weitere Produktentwicklung zu machen.
Was statische Analyse erkennt und welche Kontrollen sie nicht ersetzt
Ein Analyzer kann Typen ableiten, Aufrufen folgen, inkompatible Argumente, unmögliche Rückgabewerte, nicht definierte Eigenschaften, möglicherweise nullwertige Variablen, nicht erreichbare Zweige und Abweichungen zwischen einer Schnittstelle und ihrer Implementierung erkennen. Er hilft auch dabei, eng gekoppelte Abhängigkeiten, inkonsistent verwendete APIs und verletzte Architekturgrenzen zu lokalisieren, wenn dafür Regeln definiert werden.
Diese Signale sind besonders bei Refactorings wertvoll. Wenn beispielsweise eine Methode so geändert wird, dass sie Customer|null zurückgibt, lassen sich Verbraucher finden, die stets von einer Instanz ausgehen. Die Warnung beweist nicht, dass ein Fehler in Produktion existiert, zwingt jedoch zu der Entscheidung, was geschehen soll, wenn kein Kunde vorhanden ist.
Die Analyse validiert jedoch nicht eigenständig eine Regel wie, dass eine Bestellung nur vor der Rechnungsstellung storniert werden darf, dass ein Rabatt gemäß einer Geschäftspolitik berechnet wird oder dass eine externe Integration innerhalb einer akzeptablen Frist antwortet. Sie beobachtet weder reale Berechtigungen, Datenmigrationen, Parallelität, Performance noch Produktionskonfigurationen.
Ein sicheres Refactoring kombiniert drei Perspektiven:
- Statische Analyse zur Überprüfung von Verträgen und Codepfaden.
- Automatisierte Tests zur Bewahrung bekannter Verhaltensweisen, beginnend mit den kritischen Abläufen.
- Fachliche Überprüfung und Beobachtung zur Validierung von Geschäftsregeln, externen Auswirkungen und Verhalten nach dem Deployment.
Den Pilotversuch vorbereiten, bevor Befunde analysiert werden
Der anfängliche Umfang sollte ein abgegrenztes Geschäftsmodul mit häufigen Änderungen oder relevantem Risiko umfassen, jedoch nicht den undurchsichtigsten Kern der gesamten Anwendung. Ein nützlicher Pilotversuch hat identifizierbare Verantwortliche und zeigt, ob die Regeln verständliche Befunde erzeugen.
Erstellen Sie vor der Ausführung der Analyse ein kurzes Inventar:
- Kritische Pfade: Authentifizierung, Zahlungen, Bestellungen, Rechnungsstellung, personenbezogene Daten oder andere Vorgänge, deren Fehlfunktion erhebliche Auswirkungen hätte.
- Ein- und Ausgaben: Controller, Befehle, Queue-Consumer, APIs, importierte Dateien und geplante Jobs.
- Abhängigkeiten: PHP-Version, aufgegebene Pakete, Erweiterungen, generierter Code und Bibliotheken ohne Typinformationen.
- Aktuelle Konventionen: Verwendung von Value Objects, Exceptions, Collections, Nullwerten, assoziativen Arrays und Datenzugriff.
- Verfügbare Tests: Welche Szenarien sie abdecken, welche Daten sie vorbereiten und wo ihre Vertrauensgrenzen liegen.
Dieses Inventar verhindert, dass jede Warnung isoliert interpretiert wird. Es ermöglicht außerdem zu entscheiden, wo es sinnvoll ist, native Typen hinzuzufügen und wo Adapter um eine alte Abhängigkeit beibehalten werden sollten, damit sich ihre Mehrdeutigkeit nicht in der gesamten Anwendung ausbreitet.
Eine Baseline erstellen, ohne sie in eine dauerhafte Amnestie zu verwandeln
Die Baseline erfasst bereits bestehende Befunde, damit das Team für neuen oder geänderten Code einen höheren Standard verlangen kann. Sie ist ein Übergangswerkzeug, keine Erklärung, dass technische Schuld akzeptabel ist.
Erstellen Sie sie, nachdem Sie eine repräsentative Stichprobe der Befunde geprüft haben. Enthält das Ergebnis Konfigurationsfehler, Pfade, die nicht analysiert werden sollten, oder versehentlich eingebundenen Drittanbietercode, korrigieren Sie dies zuerst. Eine durch Rauschen aufgeblähte Baseline verliert von Anfang an an Wert.
Damit sie nützlich ist, verknüpfen Sie sie mit operativen Regeln:
- Der Baseline werden ohne überprüfbare Begründung keine neuen Einträge hinzugefügt.
- Ein behobener Befund wird in derselben Änderung aus der Baseline entfernt.
- Die Einträge werden überprüft, wenn an der betroffenen Datei bzw. dem Modul gearbeitet wird.
- Ausnahmen haben einen Verantwortlichen, einen technischen Grund und ein Datum oder eine Bedingung für die Überprüfung.
Es ist vorzuziehen, eine sehr gezielte Unterdrückung mit Erklärung zu dokumentieren, statt eine ganze Fehlerkategorie zu verbergen. Kann eine Warnung nicht behoben werden, weil eine externe Bibliothek ihre Verträge nicht ausdrückt, kapseln Sie diese Bibliothek in einem typisierten Adapter und begrenzen Sie die Ausnahme auf diese Grenze.
Befunde nach Risiko und Entscheidungsaufwand klassifizieren
Nicht jede Diagnose sollte eine Auslieferung blockieren. Die Klassifizierung muss die potenziellen Auswirkungen und den Grad der Sicherheit widerspiegeln, nicht nur den Schweregrad, den ein Tool zuweist.
Hohe Priorität: kritische Verträge und Daten
Behandeln Sie zuerst inkompatible Rückgabewerte, falsch typisierte Argumente in Geschäftsoperationen, mögliche Nullzugriffe, nicht validierte Werte an externen Grenzen und Vertragsverletzungen zwischen Modulen. Sie decken häufig Defekte auf, die bei unzureichenden Tests möglicherweise unentdeckt bleiben.
Mittlere Priorität: Unsicherheit, die den Umfang erweitert
Arrays ohne bekannte Form, gemischte Werte, die mehrere Schichten durchlaufen, und Methoden mit zu breiten Rückgabetypen verursachen nicht immer sofort einen Fehler. Dennoch erhöhen sie die Kosten jeder Änderung. Es empfiehlt sich, sie beim Bearbeiten des Ablaufs zu lösen und Datenübertragungsobjekte, Value Objects oder explizite Verträge zu definieren, wenn dies sinnvoll ist.
Niedrige Priorität: Bereinigung ohne nachgewiesene Auswirkung
Stil, redundanter Code oder interne Konventionen können die Lesbarkeit verbessern, sollten jedoch nicht mit Domain-Risiken oder dringenden Auslieferungen konkurrieren. Bündeln Sie sie in separaten Aufgaben oder wenden Sie automatische Regeln nur an, wenn ihre Änderung mechanisch und überprüfbar ist.
Reihenfolge der Eingriffe: neue technische Schuld verhindern und aktive Abläufe schützen
Eine praktische Abfolge beginnt damit, die Analyse in der kontinuierlichen Integration für die vorgeschlagenen Änderungen auszuführen. Das anfängliche Blockierungskriterium kann einfach sein: keine neuen Fehler außerhalb der Baseline einführen und das für eine geänderte Datei geltende Analyselevel nicht verschlechtern.
Verschärfen Sie anschließend Regeln nach Verzeichnis oder Modul. Üblicherweise beginnt man mit neuem Domain-Code, Anwendungsservices und aktuellen Adaptern, während in historischen Infrastrukturschichten tolerantere Kriterien beibehalten werden. Diese Aufteilung ist keine Ausrede, das Legacy-System aufzugeben: Sie macht sichtbar, wo die Grenze liegt, und ermöglicht, sie schrittweise zu verschieben.
Priorisieren Sie bei jeder aktiven Änderung einen kleinen Umfang:
- Fügen Sie Charakterisierungstests für das Verhalten hinzu, das Sie bewahren müssen.
- Deklarieren Sie den relevantesten Ein- und Ausgabevertrag.
- Beheben Sie die Warnungen, die diesen Pfad betreffen.
- Führen Sie Refactorings in kurzen Schritten durch und überprüfen Sie funktionale Unterschiede.
- Aktivieren Sie strengere Regeln, wenn das Modul sie tragen kann.
Typen und Annotationen müssen tatsächliches Wissen beschreiben. Einen Nicht-Null-Typ nur zu deklarieren, um eine Warnung zu unterdrücken, verlagert das Risiko auf den nächsten Verbraucher. Kann ein Wert absichtlich fehlen, stellen Sie ihn entsprechend dar und zwingen Sie den aufrufenden Code dazu, zu entscheiden, wie er damit umgeht.
Kontrollen in die kontinuierliche Auslieferung integrieren, ohne durch Rauschen zu blockieren
Das Ergebnis der Analyse muss für die Person, die eine Änderung einreicht, lesbar sein. Veröffentlichen Sie neue Fehler, die betroffene Datei, die Regel und einen Hinweis darauf, warum sie wichtig ist. Vermeiden Sie umfangreiche Berichte ohne Verantwortlichen und ohne Bezug zur vorgenommenen Änderung.
Definieren Sie angemessene Kriterien: Vertragsdefekte in einem kritischen Ablauf können blockieren; eine kosmetische Verbesserung kann als Follow-up verfolgt werden; eine unsichere Warnung aus einer Abhängigkeit sollte zu einem Adapter, einer dokumentierten Konfiguration oder einer temporären Ausnahme führen. Die Code-Review entscheidet, ob die Korrektur die geschäftliche Absicht respektiert; der Analyzer ersetzt diese Entscheidung nicht.
Messen Sie den Fortschritt mit Kennzahlen, die Entscheidungen leiten: offene relevante Befunde pro Modul, entfernte Baseline-Einträge, Anteil der mit anspruchsvollen Regeln analysierten Änderungen, Anzahl mehrdeutiger Verträge auf kritischen Pfaden und Anteil der durch Charakterisierungstests abgedeckten Refactorings. Das Ziel ist nicht, global null Warnungen zu erreichen, sondern den unsicheren Umfang von Änderungen zu verringern.
Antipatterns, die Bereinigung mit Modernisierung verwechseln
- Warnungen ohne Grund unterdrücken: entfernt Informationen, ohne das Risiko zu senken, das sie verursacht hat.
- Null Befunde verfolgen: kann Kapazität für irrelevante Details aufwenden, während wichtige Prozesse weiterhin unsicher sind.
- Jede nahe gelegene Datei korrigieren: vergrößert den Umfang der Änderung und erschwert die Prüfung von Regressionen.
- Unbekannte Daten als zuverlässig typisieren: verbirgt Unsicherheit, statt sie zu modellieren.
- Jede Auslieferung wegen neuer Regeln blockieren: erzeugt Ablehnung und drängt das Team dazu, nach dauerhaften Ausnahmen zu suchen.
Checkliste für den Start des Pilotversuchs
- Ein Modul mit technischem Verantwortlichen, geschäftlicher Relevanz und abgegrenztem Umfang auswählen.
- Seine Ein- und Ausgaben, Abhängigkeiten und kritischen Szenarien identifizieren.
- Die Analyse ausführen, Konfigurationsfehler beseitigen und eine Stichprobe der Ergebnisse prüfen.
- Eine auf bestehende technische Schuld begrenzte Baseline erstellen und festlegen, wer sie ändern darf.
- Neue Befunde mit hohem Risiko in Änderungen des Pilotversuchs blockieren.
- Vor dem Refactoring sensibler Pfade Charakterisierungstests hinzufügen.
- Wöchentlich wiederkehrende Befunde, Ausnahmen und Regeln überprüfen, die Rauschen erzeugen.
- Den Standard nur verschärfen, wenn die Ergebnisse verständlich und umsetzbar sind.
Mit diesem Ansatz wird die statische Analyse nicht länger zu einem Bericht über übernommene Defekte, sondern zu einem Kontrollmechanismus: Jede Änderung schafft klarere Verträge, weniger Unsicherheit und eine sicherere Grundlage, um PHP schrittweise zu modernisieren.
