Symfony 6 auf 7 Upgrade: Die Schritt-fur-Schritt-Checkliste

1. Warum der Symfony 7 Upgrade kein Nebenprojekt ist

Ein Symfony 7 Upgrade wird in vielen Teams unterschaetzt, weil die Major-Version-Nummer allein wenig ueber den tatsaechlichen Aufwand aussagt. Anders als bei einem Minor-Release innerhalb von Symfony 6 werden bei einem Major-Upgrade alle als deprecated markierten APIs endgueltig entfernt. Wer beim letzten Minor-Release Deprecation-Warnungen ignoriert hat, steht beim Symfony 7 Upgrade ploetzlich vor einer Liste von Breaking Changes, die sich nicht mehr mit einem einzeiligen Composer-Befehl loesen laesst.

Der zweite Grund, warum ein Symfony 7 Upgrade Planung braucht, liegt in der Bundle-Landschaft. Ein Projekt nutzt selten nur Symfony-Kernkomponenten, sondern zusaetzlich Drittanbieter-Bundles fuer Admin-Oberflaechen, PDF-Erzeugung, Zahlungsanbindung oder Suche. Jedes dieser Bundles muss selbst mit Symfony 7 kompatibel sein, bevor das eigentliche Projekt aktualisiert werden kann. Ein sorgfaeltig geplanter Symfony 7 Upgrade beginnt deshalb nicht beim eigenen Code, sondern bei einer Bestandsaufnahme aller Abhaengigkeiten.

Der dritte Aspekt ist organisatorisch: Ein Symfony 7 Upgrade betrifft nicht nur Entwickler, sondern auch Deployment-Pipelines, Monitoring und im schlimmsten Fall Produktionsdaten. Wer das Upgrade als reines Composer-Kommando behandelt, unterschaetzt die Tragweite. Die folgenden Abschnitte zeigen eine Checkliste, die sich in echten Projekten bewaehrt hat, vom ersten Deprecation-Scan bis zum kontrollierten Rollout.

2. Voraussetzungen pruefen: PHP-Version und Constraints

Bevor der eigentliche Symfony 7 Upgrade beginnt, muss die PHP-Version stimmen. Symfony 7 setzt mindestens PHP 8.2 voraus, in der Praxis empfiehlt sich aber PHP 8.3 oder 8.4, um von Performance-Verbesserungen und neuen Sprachfeatures zu profitieren. Ein Projekt, das noch auf PHP 8.1 laeuft, muss zunaechst die PHP-Version anheben, inklusive aller PHP-Extensions und der Server-Konfiguration, bevor an den Symfony 7 Upgrade selbst gedacht werden kann.

Parallel dazu lohnt sich ein Blick in composer.json: Jede direkte und indirekte Abhaengigkeit mit einer Versions-Constraint, die Symfony 7 ausschliesst, muss vor dem Upgrade aktualisiert werden. Der Befehl composer outdated --direct zeigt veraltete direkte Pakete, waehrend composer why-not symfony/symfony 7.0 aufdeckt, welches Paket ein Upgrade konkret blockiert. Diese Analyse gehoert an den Anfang jeder Symfony 7 Upgrade-Checkliste, weil sie den realistischen Aufwand sichtbar macht, bevor man sich in Detailarbeit verliert.

# Check current PHP version and required extensions
php -v
php -m | grep -E 'intl|opcache|apcu|redis'

# List direct dependencies that are outdated
composer outdated --direct

# Find out which package blocks the Symfony 7 upgrade
composer why-not symfony/framework-bundle 7.0

# Dry-run: see what composer would change without applying it
composer update symfony/* --dry-run --with-all-dependencies

Ein haeufiger Fehler an dieser Stelle: Teams fuehren composer update ohne --dry-run direkt in einem geteilten Branch aus und wundern sich ueber ein halb aktualisiertes Lockfile. Der Symfony 7 Upgrade-Prozess sollte immer in einem eigenen Feature-Branch stattfinden, mit einem klaren Ausgangspunkt, zu dem man bei Problemen zurueckkehren kann.

3. Deprecations mit der Symfony Deprecation Bridge finden

Der zuverlaessigste Weg, Breaking Changes vor einem Symfony 7 Upgrade zu finden, ist die Symfony Deprecation Bridge, ein Bestandteil von symfony/phpunit-bridge. Diese Bridge faengt jede Deprecation-Warnung waehrend der Testausfuehrung ab und listet sie am Ende des Testlaufs gruppiert nach Nachricht und Haeufigkeit auf. Statt Deprecations in einem riesigen Error-Log zu suchen, bekommt man eine sortierte Uebersicht, welche veralteten APIs im eigenen Code tatsaechlich verwendet werden.

Wichtig fuer den Symfony 7 Upgrade: Die Umgebungsvariable SYMFONY_DEPRECATIONS_HELPER steuert, wie die Bridge mit gefundenen Deprecations umgeht. Der Wert weak lasst Tests trotz Deprecations gruen bleiben, protokolliert die Warnungen aber vollstaendig. Das ist der richtige Modus fuer eine erste Bestandsaufnahme, weil er die Testsuite nicht sofort rot faerbt, sondern erst einmal Transparenz schafft. Erst wenn die meisten Deprecations behoben sind, schaltet man auf einen strikteren Modus um, der neue Deprecations aktiv verhindert.

# Run the full test suite in "weak" mode: tests stay green,
# but all deprecation warnings are collected and reported
SYMFONY_DEPRECATIONS_HELPER=weak php bin/phpunit

# Once most deprecations are fixed, fail the build on NEW deprecations only
SYMFONY_DEPRECATIONS_HELPER='max[self]=0' php bin/phpunit

# Export the full deprecation report to a file for tracking
SYMFONY_DEPRECATIONS_HELPER=weak php bin/phpunit --log-junit=var/deprecations.xml

Neben der Test-Suite hilft der Symfony Profiler im Dev-Modus: Jede Deprecation, die im Browser-Request ausgeloest wird, erscheint im Profiler-Panel mit Stacktrace. Fuer Legacy-Codepfade ohne Testabdeckung ist das oft der einzige praktikable Weg, Deprecations vor dem Symfony 7 Upgrade ueberhaupt sichtbar zu machen. Wer beides kombiniert, Testsuite und manuelles Durchklicken kritischer Seiten im Dev-Modus, erreicht eine realistische Abdeckung.

4. Composer-Update in kontrollierten Schritten

Statt beim Symfony 7 Upgrade alle Pakete in einem einzigen composer update auf einmal zu aktualisieren, empfiehlt sich ein gestufter Ansatz. Zuerst werden alle Nicht-Symfony-Pakete auf ihre neueste kompatible Version gebracht, waehrend die Symfony-Constraint noch auf 6.4.* steht. Das trennt zwei Fehlerquellen: Probleme durch Drittanbieter-Updates lassen sich so unabhaengig von Problemen durch den eigentlichen Symfony-Versionssprung diagnostizieren.

Erst danach wird die Symfony-Constraint in composer.json auf 7.0.* geaendert und ein gezielter composer update symfony/* ausgefuehrt. Der Symfony 7 Upgrade-Schritt selbst sollte in einem Zug fuer alle Symfony-Komponenten erfolgen, nicht komponentenweise, weil Symfony-Pakete untereinander eng versionsgebunden sind und ein gemischter Versionsstand zu schwer nachvollziehbaren Fehlern fuehrt.

# Step 1: update all non-Symfony packages first, Symfony constraint unchanged
composer update --with-all-dependencies \
  --no-plugins $(composer show -N | grep -v '^symfony/')

# Step 2: bump the Symfony constraint in composer.json to ^7.0
composer require symfony/symfony:^7.0 --no-update

# Step 3: update all Symfony packages together, in one atomic step
composer update "symfony/*" --with-all-dependencies

# Step 4: verify the lock file matches composer.json
composer validate --strict

Ein Detail, das beim Symfony 7 Upgrade oft uebersehen wird: symfony/flex selbst muss auf eine Version aktualisiert werden, die Symfony-7-Recipes kennt. Ohne aktuelles Flex kann es passieren, dass neue Recipes nicht automatisch angewendet werden und Konfigurationsdateien manuell nachgezogen werden muessen. Ein Blick in symfony.lock nach dem Update zeigt, welche Recipes tatsaechlich aktualisiert wurden.

5. Config-Aenderungen in Symfony 7 anpassen

Nach dem Composer-Update ist der Symfony 7 Upgrade noch nicht abgeschlossen, denn mehrere Konfigurationsschluessel aendern sich mit dem Major-Release. Ein typisches Beispiel ist die Umstellung veralteter Sicherheits-Firewall-Optionen, die in Symfony 6 noch mit Deprecation-Warnung funktionierten und in Symfony 7 vollstaendig entfernt wurden. Der Kernel wirft bei einer nicht angepassten Konfiguration einen klaren Fehler beim Cache-Warmup, nicht erst zur Laufzeit, was die Fehlersuche erleichtert.

Ein zweiter Bereich betrifft Umgebungsvariablen-Handling und Secrets: Symfony 7 verschaerft einige Defaults rund um Environment-Variablen-Prozessoren. Wer %env(resolve:...)%-Konstrukte im alten Stil verwendet hat, sollte die aktualisierte Dokumentation der jeweiligen Bundle-Version pruefen. Am effizientesten arbeitet man diese Aenderungen anhand der offiziellen UPGRADE-7.0.md-Datei ab, die Symfony fuer jede Major-Version im Kern-Repository pflegt und die jede Breaking Change explizit auflistet.

# config/packages/security.yaml
# BEFORE (Symfony 6, deprecated pattern removed in Symfony 7)
security:
    encoders:
        App\Entity\User: bcrypt

# AFTER (Symfony 7): password hashers replace encoders entirely
security:
    password_hashers:
        App\Entity\User:
            algorithm: auto
            cost: 12

6. Automatisierte Code-Migration mit Rector

Fuer groessere Codebasen ist manuelle Anpassung jeder Deprecation beim Symfony 7 Upgrade unrealistisch. Rector ist ein statisches Analyse- und Refactoring-Tool, das mit vorgefertigten Rule-Sets fuer Symfony-Upgrades automatisiert Code-Transformationen durchfuehrt. Statt jede der oft hunderten Fundstellen einzeln zu bearbeiten, wendet Rector die Regel projektweit an und erzeugt einen ueberpruefbaren Diff, den man vor dem Commit durchsieht.

Der praktische Ablauf: Rector wird als Dev-Dependency installiert, eine rector.php-Konfiguration mit dem passenden Symfony-Level-Set aktiviert und zunaechst im Dry-Run-Modus ausgefuehrt. Rector ersetzt fuer den Symfony 7 Upgrade zum Beispiel veraltete Annotation-basierte Routen durch PHP-Attribute oder passt Konstruktor-Signaturen an geaenderte Service-Interfaces an. Wichtig bleibt: Rector ersetzt keine Tests, sondern beschleunigt die mechanische Anpassung, waehrend Tests weiterhin die fachliche Korrektheit absichern muessen.

<?php

declare(strict_types=1);

use Rector\Config\RectorConfig;
use Rector\Symfony\Set\SymfonySetList;
use Rector\Symfony\Set\SymfonyLevelSetList;

return static function (RectorConfig $rectorConfig): void {
    $rectorConfig->paths([__DIR__ . '/src', __DIR__ . '/tests']);

    // Upgrade path: apply all rule sets up to Symfony 7.0
    $rectorConfig->sets([
        SymfonyLevelSetList::UP_TO_SYMFONY_70,
        SymfonySetList::SYMFONY_CODE_QUALITY,
    ]);

    $rectorConfig->skip([
        __DIR__ . '/src/Legacy',
    ]);
};

Ein Hinweis aus der Praxis: Nach jedem Rector-Lauf im Rahmen des Symfony 7 Upgrade sollte die volle Testsuite laufen, bevor der Diff committet wird. Rector arbeitet rein syntaktisch und kennt keine Laufzeit-Semantik, weshalb einzelne automatisierte Aenderungen in Randfaellen fehlerhaft sein koennen, gerade bei stark angepasstem Legacy-Code.

7. Tests als Sicherheitsnetz vor dem Upgrade

Ohne eine belastbare Testsuite ist jeder Symfony 7 Upgrade ein Blindflug. Funktionale Tests, die zentrale HTTP-Endpunkte, Formular-Workflows und kritische Business-Logik abdecken, zeigen sofort, wenn eine Konfigurationsaenderung oder ein Bundle-Update unerwartetes Verhalten ausloest. Projekte ohne ausreichende Testabdeckung sollten vor dem eigentlichen Upgrade zunaechst die wichtigsten Pfade mit funktionalen Tests nachruesten, statt das Risiko in die Produktionsumgebung zu verschieben.

Ein bewaehrtes Muster fuer den Symfony 7 Upgrade: Die komplette Testsuite laeuft zunaechst unveraendert auf Symfony 6.4 als Referenzlauf, dessen Ergebnis dokumentiert wird. Nach dem Composer-Update auf Symfony 7 laeuft dieselbe Suite erneut, und jede neue Abweichung wird gezielt untersucht. Diese Vorher-Nachher-Methode trennt echte Regressionen durch den Upgrade von bereits vorher bestehenden, aber bislang unbemerkten Testluecken.

8. Deployment-Strategie: Staging, Canary, Rollback

Ein Symfony 7 Upgrade gehoert nicht direkt in die Produktionsumgebung, sondern zunaechst auf ein Staging-System mit realistischen Daten und Last. Erst wenn Staging ueber mehrere Tage stabil laeuft und alle kritischen User-Journeys manuell verifiziert wurden, folgt der Produktions-Rollout. Fuer Projekte mit hoher Kritikalitaet empfiehlt sich zusaetzlich ein Canary-Deployment: Ein kleiner Teil des Produktionstraffics wird testweise auf die neue Symfony-7-Instanz geleitet, waehrend die Mehrheit weiterhin auf der alten Version laeuft.

Unabhaengig von der gewaehlten Strategie braucht jeder Symfony 7 Upgrade einen dokumentierten Rollback-Plan. Da sich das Lockfile und teilweise auch das Datenbankschema aendern koennen, reicht ein einfaches Git-Revert oft nicht aus. Ein vollstaendiger Rollback-Plan haelt fest, welcher Composer-Lockfile-Stand, welcher Datenbank-Migrationsstand und welche Konfigurationsdateien zusammen einen konsistenten Vor-Upgrade-Zustand ergeben, sodass im Ernstfall in Minuten statt Stunden zurueckgeschaltet werden kann.

# Tag the exact pre-upgrade state before touching anything
git tag pre-symfony7-upgrade
cp composer.lock composer.lock.pre-symfony7.bak

# After deployment: smoke test critical endpoints
curl -fsS https://staging.example.com/health || echo "FAIL: health check"
curl -fsS https://staging.example.com/api/v1/status || echo "FAIL: api status"

# Rollback path if something breaks
git checkout pre-symfony7-upgrade -- composer.lock composer.json
composer install --no-dev --optimize-autoloader

9. Upgrade-Schritte im direkten Vergleich

Die folgende Tabelle ordnet die einzelnen Schritte des Symfony 7 Upgrade nach Risiko und typischem Zeitaufwand ein. Sie hilft dabei, den Aufwand realistisch einzuschaetzen, bevor ein Termin fuer den Rollout festgelegt wird.

Aus dieser Uebersicht folgt eine klare Reihenfolge: Der risikoreichste Einzelschritt, das Anheben der Symfony-Constraint selbst, sollte immer der am besten vorbereitete sein, mit vorab behobenen Deprecations und einer gruenen Testsuite. Ein Symfony 7 Upgrade, das diese Reihenfolge einhaelt, reduziert das Risiko eines Produktionsausfalls erheblich.

10. Zusammenfassung

Ein sicherer Symfony 7 Upgrade folgt einer festen Reihenfolge: PHP-Version und Composer-Constraints pruefen, Deprecations mit der phpunit-bridge systematisch aufspueren, Nicht-Symfony-Pakete getrennt vom eigentlichen Symfony-Update aktualisieren und Config-Aenderungen anhand der offiziellen UPGRADE-Datei nachziehen. Rector beschleunigt die mechanische Code-Anpassung, ersetzt aber keine manuelle Ueberpruefung und keine Tests.

Der zweite Erfolgsfaktor ist Disziplin bei Tests und Deployment: Ein Vorher-Nachher-Testlauf zeigt echte Regressionen, ein Staging-System mit realistischer Last deckt Probleme vor der Produktion auf, und ein dokumentierter Rollback-Plan macht das Vorhaben planbar statt riskant. Wer diese Checkliste konsequent abarbeitet, macht den Symfony 7 Upgrade zu einem kontrollierten Projekt statt zu einem Wochenend-Notfall.

11. FAQ: Symfony 6 auf 7 Upgrade