Symfony UX 3.0: Breaking Changes, die Ihre Projekte jetzt treffen
Wenn Ihr Symfony-Projekt Turbo, LiveComponents, Autocomplete oder das Map-Bundle nutzt, haben Sie seit dem 13. April 2026 ein Problem. Symfony UX 3.0 ist erschienen und entfernt alle im 2.x-Zyklus als deprecated markierten Features. Vier Pakete wurden komplett aus dem Ökosystem entfernt. Die Mindestanforderungen steigen auf PHP 8.4 und Symfony 7.4.
Die gute Nachricht: Parallel wurde UX 2.35 als Maintenance-Release veröffentlicht, für Projekte, die noch nicht migrieren können. Aber "noch nicht" heißt nicht "nie". UX 2.x wird keine neuen Features erhalten. Wer auf der alten Version bleibt, akkumuliert technische Schulden, die mit jedem Monat teurer werden.
Aus meiner Erfahrung mit Symfony-Projekten: Die meisten Agenturen haben mindestens ein Projekt, das Symfony UX nutzt. Oft ist es Turbo für SPA-ähnliches Verhalten, LiveComponents für interaktive Formulare oder Autocomplete für Suchfelder. Diese Pakete sind tief in die Frontend-Logik integriert. Ein Major-Upgrade ist hier kein composer update und fertig. Es erfordert systematische Analyse, welche Deprecations im eigenen Code aktiv sind, und gezieltes Refactoring.
Was viele unterschätzen: Die eigentliche Komplexität liegt nicht in den offensichtlichen Deprecation-Removals. Sie liegt in den subtilen Verhaltensänderungen, die keine Deprecation-Warning erzeugt haben. Die CSRF-Änderung bei LiveComponents ist das prominenteste Beispiel: Wo vorher ein expliziter csrf-Parameter auf dem Attribut stand, greift jetzt automatisch Same-Origin/CORS-Protection. Das funktioniert in den meisten Fällen, aber wenn Ihr Setup Cross-Origin-Requests zwischen Subdomains nutzt, bricht es still.
Für Agenturen, die Symfony UX in mehreren Kundenprojekten einsetzen, multipliziert sich der Aufwand. Jedes Projekt hat eine eigene Kombination aus UX-Paketen, Symfony-Versionen und PHP-Versionen. Eine Migration, die in Projekt A in zwei Stunden erledigt ist, kann in Projekt B (mit Custom Autocomplete Types und Cross-Origin-LiveComponents) mehrere Tage dauern. Die Herausforderung ist die systematische Bestandsaufnahme: Wo stehen Ihre Projekte?
Was sich konkret ändert
Vier Pakete entfernt: Swup, LazyImage, Typed, TogglePassword
Symfony hat vier Pakete aus dem offiziellen UX-Ökosystem entfernt. Das sind keine Deprecations, die irgendwann verschwinden. Sie sind jetzt weg. Die Begründung: Diese Pakete waren dünne Wrapper um Third-Party-JavaScript-Libraries mit minimaler PHP-Integration. Ihre Funktionalität lässt sich in wenigen Zeilen Applikationscode reproduzieren.
Für die Praxis bedeutet das:
Swup (Page-Transition-Library): Direkt via npm oder importmap:require installieren und als eigenständigen Stimulus-Controller einbinden. Der Symfony-Wrapper hat wenig hinzugefügt.
LazyImage: Natives Browser-Lazy-Loading mit loading="lazy" hat dieses Paket überflüssig gemacht. In 2026 unterstützen alle relevanten Browser dieses Attribut.
Typed (Typewriter-Effekt): Typed.js direkt einbinden und einen kleinen Stimulus-Controller schreiben.
TogglePassword: Wird möglicherweise als Komponente ins UX Toolkit migriert.
Ein häufiger Fehler, den ich in Audits sehe: Teams prüfen ihre composer.json, aber nicht die importmap.php oder package.json. Diese Pakete haben JavaScript-Dependencies, die nach dem Entfernen der PHP-Pakete als verwaiste Imports zurückbleiben und Build-Fehler oder Runtime-Warnings erzeugen.
Welche Deprecation-Removals sind am kritischsten?
Die Deprecation-Removals betreffen praktisch jedes UX-Paket. Die wichtigsten für den Agenturalltag:
Autocomplete: ParentEntityAutocompleteType wurde durch BaseEntityAutocompleteType ersetzt. ExtraLazyChoiceLoader ist entfernt zugunsten von Symfony Forms eingebautem LazyChoiceLoader (verfügbar seit Symfony 7.2). Wenn Sie Custom Autocomplete Types haben, die von der alten Klasse erben, müssen diese refactored werden.
LiveComponent: Der csrf-Parameter auf #[AsLiveComponent] ist entfernt. Same-Origin/CORS-Protection ist jetzt der Default. Das ist sicherer, kann aber bei Cross-Origin-Setups brechen.
TwigComponent: Die twig_component.defaults-Konfiguration ist jetzt mandatory. Projekte, die diese Konfiguration implizit über Convention statt explizit definiert haben, werden sofort Fehler werfen. Zusätzlich wurde die cva-Twig-Funktion durch html_cva aus twig/html-extra:^3.12 ersetzt.
Map: render_map() wurde durch ux_map() ersetzt, und die title-Option auf Shapes (Polygon, Polyline, Rectangle, Circle) heißt jetzt infoWindow.
# Autocomplete: Klassenname geändert
# Vorher (UX 2.x):
use Symfony\UX\Autocomplete\Form\ParentEntityAutocompleteType;
# Nachher (UX 3.0):
use Symfony\UX\Autocomplete\Form\BaseEntityAutocompleteType;
# TwigComponent: CVA-Funktion geändert
# Vorher (UX 2.x):
{{ cva('btn', { variants: { color: 'primary' } }) }}
# Nachher (UX 3.0):
{{ html_cva('btn', { variants: { color: 'primary' } }) }}
# Map: Twig-Funktion geändert
# Vorher (UX 2.x):
{{ render_map(map) }}
# Nachher (UX 3.0):
{{ ux_map(map) }}Deep-Dive: Die versteckten Komplexitäten
PHP 8.4 und Symfony 7.4: Die Plattform-Voraussetzung
Was auf den ersten Blick einfach wirkt, hat in Production Implikationen für die gesamte Deployment-Pipeline. UX 3.0 erfordert PHP 8.4 und Symfony 7.4. Wenn Ihr Projekt noch auf Symfony 6.4 LTS oder PHP 8.2 läuft, ist das UX-Upgrade nicht isoliert durchführbar. Sie müssen zuerst die Plattform upgraden.
Wie ich im Upgrade-Guide zu Symfony 7.4 LTS vs. 8.0 beschrieben habe, ist das Symfony-7.4-Upgrade für die meisten Projekte überschaubar, wenn die Deprecation-Warnings aus 6.4 bereits behoben sind. Aber PHP 8.4 bringt eigene Breaking Changes mit: Implizite nullable Types erzeugen jetzt Deprecation Notices, und einige ältere Extensions haben Kompatibilitätsprobleme.
Die entscheidende Frage für Ihr Projekt ist: Auf welcher PHP-Version und welcher Symfony-Version laufen Ihre Projekte aktuell? Wenn die Antwort "PHP 8.2 und Symfony 6.4" ist, stehen Sie vor einem dreistufigen Upgrade: PHP 8.4, dann Symfony 7.4, dann UX 3.0. Das ist kein Wochenend-Projekt.
StimulusBundle: Die stille Breaking Change
Was die Dokumentation nicht explizit hervorhebt: Die Entfernung von ux_controller_link_tags() im StimulusBundle erfordert Symfony AssetMapper 6.4 oder höher. Projekte, die noch Webpack Encore nutzen statt AssetMapper, sind hier nicht direkt betroffen. Aber Projekte, die AssetMapper in einer älteren Version einsetzen, müssen das AssetMapper-Paket ebenfalls upgraden.
In der Praxis scheitert das oft an der Verknüpfung zwischen AssetMapper-Version und Symfony-Version. AssetMapper 6.4 setzt Symfony 6.4 voraus, aber für UX 3.0 brauchen Sie Symfony 7.4. Die Versionsmatrix wird schnell komplex. Hier hilft nur eine systematische Abhängigkeitsanalyse mit composer why-not.
Weitere Breaking Changes: Cropper und Google Maps
Zwei weitere Änderungen fallen leicht unter den Radar, betreffen aber spezifische Projekttypen erheblich:
Cropper: Die Methoden getCroppedImage() und getCroppedThumbnail() wenden Rotation jetzt immer automatisch an. Der $applyRotation-Parameter wurde entfernt. Wenn Sie bisher explizit applyRotation: false gesetzt haben (etwa weil Ihre Bildverarbeitungs-Pipeline die Rotation selbst handelt), funktioniert das nicht mehr. Die Rotation wird immer angewendet, und es gibt keine Möglichkeit, das zu deaktivieren. Für Projekte mit Custom-Bild-Pipelines (ERP-Integration, Headless-CMS-Anbindung) kann das zu doppelter Rotation und damit zu fehlerhaften Bildern führen.
Google Maps: Der Sprung auf @googlemaps/js-api-loader ^2.0 bringt geänderte DSN-Parameter mit. Die version-Option heißt jetzt v, und die Optionen id, nonce, retries, url wurden komplett entfernt. Projekte mit Custom-Maps-Konfiguration (Content Security Policy, custom API-Endpoints) müssen ihre UX_MAP_DSN-Umgebungsvariable anpassen.
# Systematische Migrations-Prüfung
# 1. Deprecation-Warnings identifizieren
$ php bin/console debug:container --deprecations
# 2. Abhängigkeiten prüfen
$ composer why-not symfony/ux-turbo 3.0
$ composer why-not symfony/ux-live-component 3.0
# 3. PHP-Version auf dem Server prüfen
$ php -v
# Muss 8.4+ sein für UX 3.0Die Migration auf Symfony UX 3.0 erfordert individuelle Analyse, abhängig von Ihrer Paket-Kombination und Ihrer Plattform-Version. → Migrations-Beratung anfragen
Praxis-Perspektive: Aufwand und Anti-Patterns
Wie aufwändig ist die Migration realistisch?
Das hängt von zwei Faktoren ab: Wie viele UX-Pakete nutzen Sie? Und wie konsequent haben Sie Deprecation-Warnings in 2.x behoben?
Wenn Ihre Applikation auf UX 2.x läuft und keine Deprecation-Notices wirft, beschreibt Symfony selbst das Upgrade als "straightforward". In der Praxis sehe ich das bestätigt für Projekte, die ausschließlich Turbo und vielleicht Twig Components nutzen. Hier reduziert sich die Migration auf ein paar Konfigurationsanpassungen und das Twig-Function-Renaming.
Komplexer wird es bei Projekten mit LiveComponents, Custom Autocomplete Types, oder dem Map-Bundle. LiveComponent-Projekte müssen die CSRF-Änderung testen, besonders wenn sie AJAX-Requests aus verschiedenen Kontexten senden. Custom Autocomplete Types, die von ParentEntityAutocompleteType erben, brauchen ein Class-Rename plus eventuelles Refactoring der Loader-Logik. Map-Projekte müssen die Google Maps JS API Loader 2.0-Migration mitmachen und ihre DSN-Parameter anpassen.
Ein Anti-Pattern, das ich regelmäßig sehe: Teams machen das Upgrade auf einem Feature-Branch, testen die offensichtlichen Seiten und mergen. Zwei Wochen später tauchen Bugs auf Seiten auf, die niemand manuell getestet hat. Besonders bei LiveComponent-Änderungen kann das passieren, weil die CSRF-Änderung in vielen Fällen funktioniert, aber in Edge-Cases (Cross-Origin, CDN-Setup, Reverse Proxy) stillschweigend versagt.
Ein weiterer Punkt, der die Testbarkeit betrifft: Symfony UX 3.0 nutzt intern PHPUnit 11 statt der Symfony PHPUnit Bridge. Für Ihre Applikation ändert das nichts direkt. Aber wenn Sie die UX-Test-Suites lokal ausführen oder eigene Tests haben, die auf UX-interne Test-Utilities zugreifen, müssen Sie PHPUnit 11 oder höher installieren. In Kombination mit PHP 8.4 kann das bei älteren CI/CD-Pipelines zu Konflikten führen.
Meine Empfehlung: Erstellen Sie vor der Migration eine explizite Test-Checkliste für alle Seiten, die UX-Komponenten nutzen. Nicht nur die offensichtlichen (Formulare, Suchfelder), sondern auch die Edge-Cases: Login-Flows mit CSRF, Autocomplete-Felder mit großen Datasets, Map-Integrationen mit Custom Shapes. Automatisierte Browser-Tests (Panther, Playwright) sind hier Gold wert.
UX 2.35: Die sichere Alternative?
Parallel zu UX 3.0 wurde UX 2.35 veröffentlicht. Das ist ein Maintenance-Release für Projekte, die noch nicht migrieren können oder wollen. Es enthält keine neuen Features, aber Bug-Fixes und Kompatibilitäts-Updates.
Als Symfony-Entwickler mit Fokus auf KMU-Projekte empfehle ich UX 2.35 als bewusste Zwischenstation, nicht als Dauerlösung. Nutzen Sie die Zeit, die 2.35 Ihnen gibt, um Deprecation-Warnings systematisch zu beheben. Jede behobene Deprecation in 2.35 ist ein Problem weniger bei der späteren 3.0-Migration. Wie ich im Artikel zu Symfony UX AI Skills beschrieben habe, entwickelt sich das UX-Ökosystem schnell weiter. Wer zu lange auf 2.x bleibt, verpasst nicht nur Features, sondern auch die Basis für AI-gestützte Entwicklungsworkflows.
Strategische Empfehlungen
Welcher Migrationspfad ist der richtige?
Für Projekte auf Symfony 7.4 LTS + PHP 8.4: Direkt auf UX 3.0 migrieren. Prüfen Sie zuerst die Deprecation-Warnings auf 2.x, beheben Sie diese, dann upgraden Sie. Testen Sie besonders LiveComponent-CSRF und Autocomplete-Types.
Für Projekte auf Symfony 6.4 LTS: Bleiben Sie auf UX 2.35 und planen Sie das Symfony-7.4-Upgrade als separates Projekt. UX 3.0 ohne das Plattform-Upgrade ist nicht möglich. Die Reihenfolge: Symfony 6.4 → 7.4, dann PHP-Upgrade auf 8.4 (falls nötig), dann UX 2.35 → 3.0.
Für neue Projekte: Starten Sie direkt mit Symfony 7.4 LTS + UX 3.0. Es gibt keinen Grund, ein neues Projekt auf UX 2.x aufzubauen.
Für Projekte mit Swup-Dependency: Priorität hat die Swup-Migration, weil das Paket komplett entfernt wurde. Swup direkt als npm-Dependency installieren und den vorhandenen Stimulus-Controller anpassen. Das ist meist in wenigen Stunden erledigt, blockiert aber den gesamten UX-Upgrade-Prozess, wenn es nicht zuerst gelöst wird.
Timing: Wann ist der richtige Zeitpunkt?
Symfony UX 2.x wird Bug-Fixes erhalten, aber keine neuen Features. Das ist ein bekanntes Pattern aus dem Symfony-Ökosystem: Der alte Branch wird gewartet, bis die Adoption des neuen Branch eine kritische Masse erreicht hat. Erfahrungsgemäß sind das 12 bis 18 Monate.
Für Agenturen empfehle ich: Planen Sie die Migration im nächsten regulären Wartungsfenster ein, nicht als separates Notfall-Projekt. Wenn Sie ohnehin ein Symfony-7.4-Upgrade für Q2/Q3 2026 geplant haben, nehmen Sie UX 3.0 in denselben Sprint. Das reduziert den Gesamtaufwand erheblich, weil die Plattform-Voraussetzungen (PHP 8.4, Symfony 7.4) ohnehin geschaffen werden.
Für Projekte, die aktuell keinen akuten Handlungsdruck haben: Fixieren Sie auf UX 2.35, beheben Sie systematisch alle Deprecation-Warnings, und dokumentieren Sie die genutzten UX-Pakete pro Projekt. Diese Bestandsaufnahme spart bei der späteren Migration erheblich Zeit.
Welche Migrations-Strategie für Ihr Projekt optimal ist, hängt von Ihrer Paket-Kombination und Ihrem Plattform-Stand ab. → Lassen Sie uns das gemeinsam evaluieren
Zusammenfassung und Ausblick
Symfony UX 3.0 ist ein typisches Major-Release: Es räumt auf, hebt die Mindestanforderungen an und entfernt technische Altlasten. Die wichtigsten Takeaways:
Vier Pakete entfernt (Swup, LazyImage, Typed, TogglePassword). Direkte Replacements sind in allen Fällen verfügbar, müssen aber manuell integriert werden.
PHP 8.4 und Symfony 7.4 als Plattform-Minimum. Projekte auf älteren Versionen müssen zuerst die Plattform upgraden. Das ist oft der aufwändigere Teil.
Deprecation-Removals in allen Paketen. LiveComponent (CSRF), TwigComponent (mandatory defaults, CVA-Rename), Autocomplete (Class-Rename) und Map (Function-Rename) sind am kritischsten.
UX 2.35 als Übergangs-Release. Sinnvoll als bewusste Zwischenstation, nicht als Dauerlösung. Nutzen Sie die Zeit für systematisches Deprecation-Fixing.
Testen Sie gründlich. Besonders LiveComponent-CSRF-Änderungen und Cross-Origin-Setups können stillschweigend brechen.
Im UX-Ökosystem wird sich in den kommenden Monaten das UX Toolkit als Komponenten-Bibliothek etablieren (TogglePassword wandert möglicherweise dorthin). Und die AI Skills Integration, die ich im letzten Artikel beschrieben habe, wird ab UX 3.x der Standard für AI-gestützte Frontend-Entwicklung in Symfony.
Migrations-Analyse für Ihr Projekt
Welche UX-Pakete nutzen Sie? Auf welcher Symfony- und PHP-Version laufen Ihre Projekte? Wie viele Deprecation-Warnings haben Sie aktuell? In einem kostenlosen Erstgespräch analysiere ich Ihren konkreten Migrationsbedarf und gebe eine realistische Aufwandseinschätzung.
→ UX 3.0 Migrations-Analyse anfragen
Dennis Schwenker-Sanders ist PHP & Symfony-Entwickler mit Fokus auf Frontend-Integration, UX-Komponenten und Migrations-Strategien für deutsche Agenturen und KMU. Er begleitet Teams bei der systematischen Modernisierung ihrer Symfony-Stacks.