Von PHP 5.6 auf PHP 8 migrieren: Legacy-Migrationsstrategie

1. Warum PHP 5.6 heute noch existiert und warum das riskant ist

PHP 5.6 erreichte sein offizielles End of Life bereits Ende 2018, dennoch laufen bis heute produktive Systeme auf dieser Version, meist weil eine Migration jahrelang als zu riskant oder zu teuer galt. Das eigentliche Risiko liegt aber nicht im Verbleib auf PHP 5.6 selbst, sondern in der wachsenden Distanz: Jedes Jahr ohne Migration erhöht die Zahl der zu überspringenden Breaking Changes und verringert gleichzeitig die Zahl der Entwickler, die noch mit den Eigenheiten dieser alten Version vertraut sind.

Der Weg von PHP 5.6 direkt zu PHP 8 bedeutet, vier Major-Versionssprünge auf einmal zu bewältigen: PHP 7.0 mit dem neuen Fehlerbehandlungssystem und Return-Type-Deklarationen, PHP 7.1 bis 7.4 mit schrittweise verschärften Typregeln, und schließlich PHP 8.0 bis 8.4 mit union Types, Attributes und einer nochmals veränderten Fehlerbehandlung bei internen Funktionen. Jede dieser Versionen entfernte Funktionen, veränderte Standardverhalten oder verschärfte implizite Typkonvertierungen, die in PHP-5.6-Code oft unbewusst genutzt wurden.

Die Kernaussage dieses Artikels: Eine Migration von PHP 5.6 auf PHP 8 gelingt nicht als ein einziger Schritt, sondern als eine Kette kleinerer, jeweils überschaubarer Sprünge über Zwischenversionen, jeweils abgesichert durch Tests und automatisierte Refactoring-Werkzeuge. Diese Strategie steht im Zentrum der folgenden Abschnitte.

2. Warum Zwischenversionen den direkten Sprung schlagen

Ein direkter Sprung von PHP 5.6 auf PHP 8 bedeutet, dass jeder Fehler, der während der Migration auftritt, einer von potenziell Dutzenden Breaking Changes aus vier Major-Versionen zugeordnet werden muss. Diese Fehlersuche ist extrem zeitaufwendig, weil die Fehlermeldung selten auf die eigentliche Ursache hinweist, etwa wenn ein stillschweigend in PHP 7 verändertes Sortierverhalten erst in PHP 8 zu einem sichtbaren, aber schwer nachvollziehbaren Symptom führt.

Der bewährte Ansatz ist, das System zunächst auf PHP 7.4 zu heben, die letzte 7er-Version mit langem Support-Zeitraum, dort alle auftretenden Probleme zu beheben und eine stabile Zwischenversion zu erreichen, bevor der nächste Sprung auf PHP 8.x beginnt. Diese Zwischenstation reduziert die Anzahl gleichzeitig zu bewältigender Breaking Changes drastisch, weil PHP 7.4 bereits viele der PHP-8-Vorboten wie Deprecation-Warnungen für später entfernte Features enthält, die in der Konsole sichtbar werden, bevor sie zu echten Fehlern werden.

Wichtig ist, jede Zwischenversion tatsächlich in Produktion zu betreiben, statt sie nur als Durchgangsstadium in der CI-Pipeline zu behandeln. Erst der reale Produktionsbetrieb auf PHP 7.4 deckt Randfälle auf, die synthetische Tests übersehen, etwa ungewöhnliche Zeichenkodierungen aus alten Datenbankeinträgen oder seltene, aber reale Nutzereingaben.

3. mysql_*-Funktionen: der häufigste Blocker

Die mit Abstand häufigste Blockade bei einer PHP-5.6-Migration sind die mysql_*-Funktionen, die bereits in PHP 5.5 als deprecated markiert und in PHP 7.0 vollständig entfernt wurden. Systeme, die noch auf PHP 5.6 laufen, nutzen diese Funktionen fast immer noch aktiv, weil ihre Ablösung eine der aufwendigsten Einzelaufgaben der gesamten Migration ist. Der Umstieg auf mysqli oder PDO ist unumgänglich, bevor überhaupt ein Sprung auf PHP 7.0 möglich wird.

Ein pragmatischer Zwischenschritt ist eine Kompatibilitätsschicht, die die alte mysql_*-API auf mysqli abbildet, sodass der Rest des Codes zunächst unverändert bleiben kann, während intern bereits die moderne Erweiterung arbeitet. Diese Schicht ist keine Zielarchitektur, sondern ein Werkzeug, um den ersten Versionssprung zu ermöglichen, bevor Aufrufer schrittweise auf direkte PDO-Nutzung migriert werden.

<?php

declare(strict_types=1);

// Compatibility shim: maps legacy mysql_* calls onto mysqli
// Transitional only — replace call sites with PDO over time
final class MysqlCompat
{
    private static ?\mysqli $connection = null;

    public static function connect(string $host, string $user, string $password): void
    {
        self::$connection = new \mysqli($host, $user, $password);
        if (self::$connection->connect_errno) {
            throw new \RuntimeException(
                'Connection failed: ' . self::$connection->connect_error
            );
        }
    }

    public static function query(string $sql): \mysqli_result|bool
    {
        if (self::$connection === null) {
            throw new \RuntimeException('MysqlCompat::connect() was not called');
        }
        return self::$connection->query($sql);
    }
}

// Legacy call site — signature stays familiar, implementation is modern
function mysql_query_compat(string $sql): \mysqli_result|bool
{
    return MysqlCompat::query($sql);
}

Diese Übergangslösung erlaubt, die dringendste Blockade zu lösen, ohne sofort jede einzelne Datenbankabfrage im Projekt anzufassen. Nach dem erfolgreichen Sprung auf PHP 7.0 wird die Kompatibilitätsschicht schrittweise durch direkte, parametrisierte PDO-Aufrufe ersetzt, idealerweise kombiniert mit der Einführung von Prepared Statements, die zugleich SQL-Injection-Risiken reduzieren.

4. Veränderte Fehlerbehandlung: von Warnings zu Throwables

Einer der grundlegendsten Unterschiede zwischen PHP 5.6 und PHP 8 betrifft die Fehlerbehandlung. In PHP 5.6 erzeugten viele fatale Fehler, etwa der Aufruf einer Methode auf null, einen nicht abfangbaren E_ERROR, der das Skript sofort beendete. Ab PHP 7 wurden solche Fehler in Error-Objekte umgewandelt, die über catch (\Error $e) abgefangen werden können, ein fundamentaler struktureller Wandel, der Code, der sich bisher auf das sofortige Skriptende verlassen hat, subtil verändert.

Für die Migration bedeutet das: Jede Stelle im Code, die implizit davon ausging, dass ein bestimmter Fehler das Skript beendet, etwa um eine nachfolgende Bereinigung zu überspringen, muss überprüft werden. Mit PHP 8 erreicht diese Entwicklung eine weitere Stufe, weil deutlich mehr interne Funktionen bei ungültigen Argumenttypen jetzt TypeError werfen, statt eine Warnung auszugeben und mit null fortzufahren, wie es in PHP 5.6 üblich war.

<?php
// PHP 5.6: calling a method on null was an uncatchable fatal error,
// the script simply stopped, no cleanup ran afterward
$user = find_user($id); // returns null if not found
$user->getName();       // Fatal error: Call to a member function on null

declare(strict_types=1);

// PHP 8: the same mistake throws a catchable Error object
function processUser(?User $user): string
{
    try {
        return $user->getName();
    } catch (\Error $e) {
        // Code that relied on immediate script termination
        // must now explicitly handle this case
        return 'Unknown user: ' . $e->getMessage();
    }
}

5. Typjonglage und veränderte Vergleichsregeln

Ein besonders tückischer Unterschied zwischen PHP 5.6 und PHP 8 betrifft die Vergleichsregeln zwischen Strings und Zahlen. In PHP 5.6 wurde bei einem Vergleich wie 0 == "abc" der String zunächst in eine Zahl umgewandelt, was 0 == 0 und damit true ergab, ein Verhalten, das in der Praxis regelmäßig zu subtilen Sicherheitslücken führte, etwa wenn ein Passwort-Hash mit einem numerischen String verglichen wurde. Seit PHP 8 wird stattdessen die Zahl in einen String umgewandelt, sodass 0 == "abc" nun false ergibt, eine deutlich intuitivere, aber verhaltensändernde Anpassung.

Diese Änderung betrifft besonders Code, der lose Vergleiche (==) statt strikter Vergleiche (===) verwendet, ein in PHP 5.6-Projekten sehr verbreitetes Muster. Der pragmatische Migrationsschritt ist, vor dem Sprung auf PHP 8 systematisch nach losen Vergleichen mit gemischten Typen zu suchen, etwa per PHPStan-Regel oder Rector-Regel, und diese gezielt auf strikte Vergleiche umzustellen, statt sich auf das neue Verhalten zu verlassen, ohne es zu verstehen.

<?php
// PHP 5.6 behavior: "abc" is cast to 0, so 0 == "abc" was true —
// a classic source of authentication bypass bugs
if ($storedHash == $userInput) { // DANGEROUS on PHP 5.6 with mixed types
    grantAccess();
}

declare(strict_types=1);

// PHP 8 behavior: 0 is cast to "0", so 0 == "abc" is now false —
// but the safe fix is still an explicit strict comparison
function verifyHash(string $storedHash, string $userInput): bool
{
    return hash_equals($storedHash, $userInput); // strict, timing-safe
}

6. Rector als automatisiertes Werkzeug pro Versionssprung

Manuelles Durchsuchen des Codes nach jeder einzelnen Breaking Change ist bei größeren Projekten nicht praktikabel. Rector automatisiert einen erheblichen Teil dieser Arbeit, indem es vordefinierte Regelsets pro Ziel-PHP-Version bereitstellt, die den Code automatisch anpassen, etwa veraltete Funktionsaufrufe durch moderne Äquivalente ersetzen oder implizite Typumwandlungen explizit machen.

<?php

declare(strict_types=1);

use Rector\Config\RectorConfig;
use Rector\Set\ValueObject\LevelSetList;

// rector.php — apply one version step at a time, never skip levels
return static function (RectorConfig $rectorConfig): void {
    $rectorConfig->paths([
        __DIR__ . '/src',
    ]);

    // Step 1: PHP 5.6 codebase targeting PHP 7.4 first
    $rectorConfig->sets([
        LevelSetList::UP_TO_PHP_74,
    ]);

    // Run 'vendor/bin/rector process --dry-run' first to review the diff,
    // then 'vendor/bin/rector process' to apply. Repeat for UP_TO_PHP_80,
    // UP_TO_PHP_81, and so on — one level set per migration stage.
};

Entscheidend ist, Rector schrittweise pro Zielversion anzuwenden, nicht in einem einzigen Durchlauf direkt auf PHP 8.4. Jeder Durchlauf sollte zunächst im Dry-Run-Modus geprüft, das Diff manuell überflogen und erst nach einer Testrunde tatsächlich angewendet werden. Rector ersetzt keine menschliche Prüfung, reduziert aber die Menge an manuell zu bearbeitenden Fundstellen drastisch, insbesondere bei mechanischen Änderungen wie der Anpassung von Funktionssignaturen.

7. Abhängigkeiten und Composer-Pakete aktualisieren

Ein oft unterschätzter Teil der Migration ist die Aktualisierung von Drittanbieter-Paketen. Viele Bibliotheken, die auf PHP 5.6 liefen, haben seither mehrere Major-Versionen mit eigenen Breaking Changes durchlaufen oder wurden komplett aufgegeben und finden keinen aktiven Support mehr. Der Composer-Befehl composer outdated --direct liefert einen ersten Überblick, ersetzt aber nicht die Prüfung, ob ein Paket überhaupt noch aktiv gepflegt wird.

#!/usr/bin/env bash
# audit-composer-packages.sh — flag direct dependencies with no PHP 8 support
set -euo pipefail

composer outdated --direct --format=json | \
  jq -r '.installed[] | select(.latest != .version) | "\(.name): \(.version) -> \(.latest)"'

# Check platform requirement declared by each package
composer show --direct --format=json | \
  jq -r '.installed[] | "\(.name): requires \(.requires.php // "no PHP constraint")"'

Für aufgegebene Pakete ohne Nachfolger bleiben meist drei Optionen: das Paket forken und selbst pflegen, die Funktionalität durch eine aktiv gepflegte Alternative ersetzen, oder in seltenen Fällen die genutzte Funktionalität selbst neu implementieren, wenn sie klein genug ist. Diese Entscheidung sollte früh im Migrationsprozess getroffen werden, weil sie oft mehr Aufwand verursacht als die Anpassung des eigenen Codes an neue PHP-Versionen.

8. Ein Testnetz aufbauen, bevor der Sprung beginnt

Die riskanteste Situation bei einer Migration von PHP 5.6 ist ein Projekt ohne jegliche automatisierte Tests, was bei Systemen dieses Alters die Regel statt die Ausnahme ist. Bevor der erste Versionssprung überhaupt beginnt, sollte ein Mindestmaß an Absicherung existieren, typischerweise in Form von End-to-End-Tests, die die wichtigsten Geschäftsabläufe über die Oberfläche prüfen, selbst wenn keine granularen Unit-Tests vorhanden sind.

Diese Tests müssen nicht elegant oder vollständig sein, sie müssen nur die kritischen Pfade abdecken: Login, Bestellprozess, Zahlungsabwicklung, je nach Anwendung. Ein solches Testnetz, selbst wenn es nur zehn oder zwanzig Szenarien abdeckt, verwandelt jeden Versionssprung von einer Vertrauensfrage in eine überprüfbare Tatsache: Entweder die Tests laufen nach dem Sprung auf PHP 7.4 noch grün, oder sie zeigen konkret, wo ein Problem liegt, lange bevor Kunden es in Produktion bemerken.

9. Direktsprung vs. gestufte Migration im Vergleich

Die folgende Tabelle vergleicht den riskanten direkten Sprung von PHP 5.6 auf PHP 8 mit der empfohlenen gestuften Migration über Zwischenversionen.

Die scheinbar kürzere Gesamtdauer eines Direktsprungs relativiert sich meist schnell, sobald die ersten unklaren Produktionsfehler auftreten, deren Ursache sich über vier Major-Versionen erstrecken kann. Die gestufte Migration benötigt zwar mehr einzelne Deployments, liefert aber in jeder Phase eine überprüfbare, stabile Zwischenversion.

10. Zusammenfassung

Eine Migration von PHP 5.6 auf PHP 8 unterscheidet sich fundamental von einem gewöhnlichen Versionsupgrade, weil sie vier Major-Versionen mit jeweils eigenen Breaking Changes überspringt: entfernte mysql_*-Funktionen, veränderte Fehlerbehandlung von Warnings zu Throwables, verschärfte Vergleichsregeln zwischen Strings und Zahlen, und deutlich strengere Typprüfungen bei internen Funktionen. Ein direkter Sprung macht die Fehlerdiagnose praktisch unmöglich, weil jeder auftretende Fehler einer von potenziell Dutzenden Ursachen aus vier Versionen zugeordnet werden muss.

Die belastbare Strategie führt über PHP 7.4 als Zwischenstation, mit Rector als automatisiertem Werkzeug pro Versionsstufe, einer Kompatibilitätsschicht für mysql_*-Aufrufe während der ersten Phase, und einem Mindestmaß an End-to-End-Tests, bevor der erste Sprung überhaupt beginnt. Wer diese Reihenfolge einhält, verwandelt ein monatelanges Risikoprojekt in eine Abfolge überschaubarer, einzeln validierbarer Migrationsschritte.

11. FAQ: Von PHP 5.6 auf PHP 8 migrieren