Deprecated-Funktionen im PHP-Code finden – so geht es

Ein PHP-Update scheitert selten an der Fachlogik. Es scheitert an Funktionen, die eine neue PHP-Version als veraltet markiert oder ganz entfernt hat. Der Warenkorb rechnet weiter korrekt, die Rechnungsnummern stimmen, die Kundenlogik läuft wie seit Jahren. Aber irgendwo tief im Code steht ein Aufruf, den PHP 8.3 nur noch als E_DEPRECATED durchgehen lässt und den PHP 9 mit einem Fatal Error quittiert. Genau diese Stellen müssen Sie vor dem Update kennen, nicht danach.

Dieser Artikel zeigt Ihnen konkret, wie Sie PHP deprecated Funktionen in einer bestehenden Codebasis systematisch aufspüren, welche Werkzeuge dabei zuverlässig sind und wo die typischen Fallstricke liegen.

Was bedeutet "deprecated" in PHP eigentlich?

"Deprecated" heißt: Eine Funktion existiert noch und funktioniert noch, ist aber offiziell als veraltet markiert und wird in einer künftigen Version entfernt. PHP gibt bei der Nutzung eine E_DEPRECATED-Warnung aus, bricht aber nicht ab.

Das ist der entscheidende Punkt: Deprecation ist eine Vorwarnung, kein Fehler. Ihr System läuft heute weiter, obwohl es intern längst auf entfernte Funktionen zusteuert. Wer diese Warnungen ignoriert, verwandelt ein planbares Update in einen Notfall. Beispiele aus den letzten Versionssprüngen sind utf8_encode() und utf8_decode() (deprecated in 8.2), die dynamische Erzeugung von Klassen-Eigenschaften (deprecated in 8.2) oder das seit PHP 7 entfernte mysql_*-API, das in Altsystemen erstaunlich oft noch existiert.

Warum reicht "es läuft doch" als Prüfung nicht aus?

Weil deprecated Funktionen sich still verhalten, bis sie es nicht mehr tun. Ein Aufruf, der heute nur eine Log-Zeile erzeugt, wird nach dem nächsten Major-Update zum Absturz. Das Problem ist fast nie die Geschäftslogik Ihrer Anwendung, sondern der technische Code drumherum, der mit der Sprache gealtert ist.

Ein System, das seit acht Jahren korrekt Rechnungen schreibt, ist kein Sanierungsfall. Es ist der Beweis, dass die Fachlogik trägt. Deprecated Funktionen zu finden bedeutet, genau diese funktionierende Logik zu erhalten und nur die veraltete Hülle darum auszutauschen. Das ist der Grund, warum ein Deprecation-Scan fast immer die günstigere und sicherere Alternative zur Neuentwicklung ist.

Wie finde ich PHP deprecated Funktionen mit statischer Analyse?

Statische Analyse liest Ihren Code, ohne ihn auszuführen, und meldet veraltete Aufrufe. Das ist die erste und wichtigste Methode, weil sie auch Code-Pfade findet, die im Alltag selten durchlaufen werden.

Zwei Werkzeuge haben sich in der Praxis bewährt:

• PHPStan mit der Erweiterung phpstan/phpstan-deprecation-rules: meldet die Nutzung von als @deprecated markierten Funktionen, Methoden und Klassen. Ideal, um veralteten Framework- und Library-Code aufzuspüren.
• Rector mit dem passenden PHP-Level-Set (z. B. LevelSetList::UP_TO_PHP_83): findet nicht nur deprecated Aufrufe, sondern kann sie im Trockenlauf sogar automatisch umschreiben.

Ein pragmatischer Einstieg mit Rector im reinen Analyse-Modus, der nichts verändert:

vendor/bin/rector process src --dry-run

Der --dry-run-Schalter ist hier entscheidend. Sie sehen jede geplante Änderung als Diff, ohne dass eine einzige Datei angefasst wird. So bekommen Sie eine belastbare Liste, bevor Sie über Änderungen entscheiden.

Wie finde ich Deprecations zur Laufzeit?

Zur Laufzeit finden Sie deprecated Funktionen, indem Sie PHP anweisen, alle E_DEPRECATED-Meldungen zu protokollieren, und dann Ihre Testsuite oder die Anwendung durchlaufen. Statische Analyse und Laufzeit-Analyse ergänzen sich, sie ersetzen sich nicht.

Setzen Sie in einer Test- oder Staging-Umgebung die Fehlerberichterstattung explizit auf alle Meldungen:

error_reporting(E_ALL);
ini_set('log_errors', '1');
ini_set('error_log', '/pfad/zu/deprecation.log');

Wenn Sie danach Ihre PHPUnit-Tests laufen lassen, sammeln sich alle real ausgelösten Deprecations im Log. In Symfony hilft zusätzlich der symfony/deprecation-contracts-Mechanismus, der Deprecations gebündelt im Profiler und in der Test-Ausgabe anzeigt. In Laravel greifen Sie dieselben Meldungen über den Log-Channel ab. Der große Vorteil dieser Methode: Sie sehen, welche Deprecations tatsächlich in echten Abläufen auftreten und welche nur in totem Code schlummern.

Statisch oder zur Laufzeit prüfen — was zuerst?

Beginnen Sie mit der statischen Analyse und ergänzen Sie sie durch die Laufzeit-Protokollierung. Der statische Scan liefert Vollständigkeit, die Laufzeit-Analyse liefert Priorität.

• Statische Analyse findet alles, auch Code, der selten oder nie ausgeführt wird. Sie kann aber Aufrufe melden, die praktisch tot sind.
• Laufzeit-Analyse findet das Relevante, also was im echten Betrieb wirklich passiert. Sie übersieht aber Pfade, die Ihre Tests nicht abdecken.

Wer nur eine der beiden Methoden nutzt, bekommt ein schiefes Bild. Erst die Kombination zeigt Ihnen, was dringend ist und was warten kann.

Wie priorisiere ich die gefundenen Deprecations?

Priorisieren Sie nach dem Zeitpunkt der Entfernung und nach der Häufigkeit im produktiven Betrieb. Nicht jede Deprecation ist gleich dringend.

1. Bereits entfernte Funktionen zuerst: Alles, was in Ihrer Ziel-PHP-Version nicht mehr existiert (etwa each() oder das alte mysql_*-API), führt sofort zum Fatal Error und hat oberste Priorität.
2. Häufig genutzte Deprecations als Nächstes: Ein veralteter Aufruf, der bei jedem Request durchläuft, wiegt schwerer als einer in einem jährlichen Export-Skript.
3. Selten genutzte Deprecations zuletzt: Sie bleiben auf der Liste, blockieren aber selten das Update.

Diese Reihenfolge sorgt dafür, dass Sie mit überschaubarem Aufwand zuerst die Risiken abräumen, die das Update tatsächlich verhindern würden.

Praxis-Tipp zum Abschluss

Führen Sie den Deprecation-Scan nicht einmalig aus, sondern binden Sie ihn in Ihre CI-Pipeline ein. Wenn PHPStan mit Deprecation-Regeln bei jedem Merge-Request läuft, entsteht kein neuer veralteter Code mehr, und der nächste Versionssprung wird zur Routine statt zum Projekt. Ehrlich gesagt ist das die einzige Methode, die dauerhaft funktioniert. Ein Scan, den Sie einmal pro Jahr manuell starten, wird irgendwann vergessen.

Und ein realistischer Hinweis: Der Scan findet die Stellen, das Ersetzen bleibt Handarbeit, weil viele Deprecations kein Eins-zu-eins-Äquivalent haben. utf8_decode() etwa lässt sich nicht blind durch eine Zeile ersetzen, sondern verlangt eine bewusste Entscheidung über das Encoding. Genau bei solchen Migrationen von Legacy-PHP-Anwendungen unterstützt LegacyWerk, wenn intern die Zeit oder die Erfahrung mit den Grenzfällen fehlt.