Symfony Flex: Altprojekte auf die neue Struktur heben

Ihre Symfony-Anwendung läuft seit Jahren stabil, aber sie steckt in der alten Standard-Edition fest: die riesige AppBundle-Struktur, Konfiguration verteilt über parameters.yml, config.yml und ein handgepflegtes AppKernel.php. Jedes Composer-Update ist ein Nervenkrimi, und neue Entwickler brauchen Tage, bis sie sich zurechtfinden. Das ist kein Grund, das System wegzuwerfen. Dass es seit Jahren funktioniert, ist der Beweis, dass die Fachlogik stimmt. Das Problem ist fast immer nur der Code drumherum - und genau den räumt eine Symfony Flex Migration auf.

Was ändert sich bei einer Symfony Flex Migration konkret?

Symfony Flex ersetzt die alte Verzeichnisstruktur durch eine schlanke, konventionsbasierte Anordnung und automatisiert die Konfiguration über sogenannte Recipes. Statt Bundles manuell in AppKernel.php zu registrieren, übernimmt das die config/bundles.php, und jedes Paket bringt seine Standardkonfiguration selbst mit.

Die wichtigsten strukturellen Verschiebungen im Überblick:

• Kernel: Aus app/AppKernel.php wird src/Kernel.php mit dem MicroKernelTrait.
• Konfiguration: Die monolithische app/config/ wird zu config/packages/ mit einer Datei pro Bundle.
• Umgebungsvariablen: parameters.yml weicht einer .env-Datei und echten Umgebungsvariablen.
• Public-Verzeichnis: Aus web/ wird public/, der Front Controller heißt nur noch index.php.
• Code: Das monolithische src/AppBundle/ löst sich zugunsten von direktem src/-Code ohne Bundle-Overhead auf.

Wichtig zur Einordnung: Flex ist kein Framework-Upgrade. Sie können Flex bereits unter Symfony 3.4 einführen, denn 3.4 und 4.0 teilen dieselbe Struktur. Genau deshalb ist 3.4 der ideale Sprungbrett-Punkt.

Warum lohnt sich die Migration statt einer Neuentwicklung?

Eine Neuentwicklung ist in aller Regel die teuerste und riskanteste Option, weil Sie dabei jahrelang gewachsenes Fachwissen wegwerfen und neu erraten müssen. Die Migration behält Ihre erprobte Geschäftslogik und tauscht nur das Gerüst darum herum aus.

Der konkrete Gewinn ist nicht kosmetisch:

• Composer-Updates werden berechenbar, weil Recipes die Konfiguration mitliefern statt sie Ihnen zu überlassen.
• Neue Symfony-Features werden nutzbar - Autowiring, Autoconfiguration und der Flex-Server für composer require.
• Onboarding wird schneller, weil die Struktur der offiziellen Dokumentation entspricht und nicht Ihrer historischen Sonderlösung.

Ehrlich bleibt aber: Die Migration ist Arbeit, und sie liefert kurzfristig kein einziges neues Feature für Ihre Nutzer. Sie zahlt sich über die nächsten Jahre in Wartbarkeit aus, nicht in der nächsten Sprint-Demo. Wer das intern nicht vertreten kann, sollte sie eher als Vorbereitung für ein anstehendes 4.x- oder 5.x-Upgrade begründen.

Wie gehen Sie eine Symfony Flex Migration Schritt für Schritt an?

Der bewährte Weg führt nicht direkt zur neuen Struktur, sondern zuerst auf Symfony 3.4 LTS als stabile Zwischenstufe. Von dort aus ist der Strukturwechsel deutlich beherrschbarer.

1. Erst auf 3.4 LTS bringen. Beheben Sie alle Deprecations unter der alten Struktur, solange die App noch läuft. Der Deprecation-Layer im Profiler und in den Logs ist hier Ihr wichtigstes Werkzeug.
2. Ein frisches Skeleton daneben aufsetzen. Erzeugen Sie mit composer create-project symfony/skeleton ein leeres Flex-Projekt und nutzen Sie es als Referenz für die neue Verzeichnisstruktur.
3. Struktur umziehen. Verschieben Sie web/ nach public/, app/config/ nach config/ und legen Sie src/Kernel.php mit dem MicroKernelTrait an. Splitten Sie config.yml in einzelne Dateien unter config/packages/.
4. Konfiguration in .env überführen. Übersetzen Sie Secrets und Verbindungsdaten aus parameters.yml in .env-Variablen. Achten Sie darauf, dass echte Produktions-Secrets niemals ins Repository gelangen.
5. AppBundle auflösen. Ziehen Sie den Code aus src/AppBundle/ nach src/, passen Sie die Namespaces von AppBundle\ auf App\ an und aktualisieren Sie Service- und Routing-Referenzen.
6. Services auf Autowiring umstellen. Ersetzen Sie die manuell gepflegte services.yml schrittweise durch das autowire: true-Standardmuster.

Ein häufiger Stolperstein: Template- und Service-Referenzen, die noch auf AppBundle zeigen, etwa @App/default/index.html.twig oder AppBundle:Default:index. Diese müssen Sie auf die Pfad-Notation umstellen, sonst brechen Rendering und Routing still weg.

Welche Fallstricke tauchen bei der Symfony Flex Migration am häufigsten auf?

Die meisten Probleme entstehen nicht am Code, sondern an der Konfiguration und an Referenzen, die niemand mehr auf dem Schirm hat. Ein paar Bereiche verdienen besondere Vorsicht.

Umgebungsvariablen und Secrets

In der alten Welt standen Passwörter oft im Klartext in parameters.yml und wurden über die Deployment-Pipeline eingespielt. Beim Umzug auf .env müssen Sie sauber zwischen Default-Werten im Repository und echten Secrets trennen. Für Produktion gehören Secrets in echte Umgebungsvariablen oder den Symfony Secrets Vault, nicht in eine committete Datei.

Bundle-Konfiguration, die verschwindet

Wenn Sie ein Bundle neu über Flex installieren, bringt sein Recipe eine Default-Konfiguration mit - die aber Ihre historisch gewachsenen Anpassungen nicht kennt. Vergleichen Sie nach jedem composer require die neu erzeugte Datei unter config/packages/ mit Ihrer alten Konfiguration und übertragen Sie bewusste Abweichungen manuell.

Deprecations, die zu Fehlern werden

Was unter 3.4 nur eine Deprecation-Warnung war, wird unter 4.0 zum harten Fehler. Deshalb ist die Reihenfolge entscheidend: erst unter 3.4 alle Warnungen abräumen, dann die Version anheben. Wer die Reihenfolge dreht, debuggt Struktur- und Deprecation-Probleme gleichzeitig - und verliert den Überblick.

Wie sichern Sie ab, dass nach der Migration nichts kaputt ist?

Die einzige verlässliche Absicherung ist ein Test, der das Verhalten der Anwendung von außen prüft, unabhängig von der inneren Struktur. Wenn Ihr Altprojekt kaum Tests hat - was oft der Fall ist -, schreiben Sie vor der Migration zumindest ein paar Smoke-Tests, die die wichtigsten Routen aufrufen und den HTTP-Status prüfen.

Konkret bewährt sich diese Reihenfolge: erst charakterisierende Tests auf die bestehende Anwendung, dann die Migration in kleinen, einzeln deploybaren Schritten, und nach jedem Schritt ein Durchlauf gegen dieselben Tests. So merken Sie sofort, welcher Schritt ein Verhalten verändert hat, statt am Ende vor einer Blackbox zu stehen.

Praxis-Tipp zum Schluss

Migrieren Sie nicht in einem einzigen großen Sprung. Der teuerste Fehler ist der monatelange Feature-Freeze, in dem parallel entwickelt wird und der Migrationszweig immer weiter vom Produktivstand abdriftet. Zerlegen Sie den Umzug in kleine Schritte, von denen jeder einzeln in Produktion gehen kann - Struktur zuerst, dann Konfiguration, dann Autowiring. Ein System, das seit Jahren läuft, hat sich seinen Respekt verdient; behandeln Sie es beim Umbau entsprechend vorsichtig. Genau bei solchen kontrollierten Umzügen alter Symfony-Projekte unterstützt LegacyWerk, wenn intern die Zeit oder die Sicherheit für den ersten Schnitt fehlt.