Hier wird beschrieben, wie der Umstieg von Sulu 2.6 auf Sulu 3 abläuft: Zuerst werden unter Sulu 2 PHPCR-Migrationen ausgeführt, Schlüssel geprüft, das Artikel-Bundle entfernt und PHPCR aufgeräumt. Dann folgen sulu/sulu:3.0.*, die neuen Tabellen und sulu:phpcr-migration:migrate, danach die Anpassung von Templates und Twig. Die meiste Zeit kosten Datumsformat, Caches, Bundle-Spalten und Altlasten.
Reihe 5: Sulu für Entwickler Kapitel 16 von 16
Von Sulu 2 auf Sulu 3
Kurz zusammengefasst
Der Umstieg von Sulu 2.6 auf Sulu 3 ist ein Major-Upgrade mit eigenem Werkzeug für die Daten; die Anleitung steht in UPGRADE-3.x.md und in der offiziellen Dokumentation. Die Website bertrams-media lief vorher auf Sulu 2.6.7 und ist seit dem 14./15. Oktober 2026 auf Sulu 3.0.9 live.
Vorher hilfreich: 5.1 Sulu 3 im Überblick
Vor dem Upgrade
Das Upgrade beginnt noch unter Sulu 2:
- Die neuesten 2.x-Versionen von Sulu und seiner Bundles installieren und alle PHPCR-Migrationen ausführen:
php bin/adminconsole phpcr:migrations:migrate. - Die Schlüssel prüfen: Webspace-, Template- und Navigationsschlüssel werden strikt geprüft (nur
[a-z0-9_-]+, höchstens 31 Zeichen), was nicht passt, wird vorher per PHPCR-Migration oder in der Datenbank geändert. - Wer das
sulu/article-bundlehat, aktualisiert es zuerst auf die neueste Version und stellt sicher, dass die MigrationVersion202407111600gelaufen ist; danach wird das Bundle mitcomposer remove sulu/article-bundle --no-scriptsentfernt. Flex kann dabeiconfig/templates/articles/*löschen, die Dateien lassen sich aus der Versionsverwaltung zurückholen. - Das PHPCR-Repository aufräumen:
php bin/adminconsole sulu:document:phpcr-cleanup.
Sulu 3 einspielen
Dann folgen die neuen Pakete und die Datenmigration:
composer require sulu/sulu:"3.0.*" --no-scripts
# config/bundles.php und die Routen anpassen (siehe UPGRADE-3.x.md)
composer require sulu/phpcr-migration-bundle
php bin/adminconsole sulu:phpcr-migration:migrate
Vor dem Befehl müssen die neuen Tabellen da sein: Dafür werden die Doctrine-Migrationen von Sulu 3 ausgeführt, Beispiel-SQL steht in UPGRADE-3.x.md im Abschnitt „Add new Content storage tables“. Das Migrations-Bundle wird in config/bundles.php eingetragen und in config/packages/sulu_phpcr_migration.yaml auf das PHPCR-Repository gerichtet, in der Beispiel-Website mit DSN: "dbal://default?workspace=default" und dem Ziel dbal (Verbindung default); wer Jackrabbit benutzt hat, nimmt einen jackrabbit://-DSN. Der Befehl lässt sich wiederholen, denn schon migrierte Inhalte werden überschrieben, nicht verdoppelt. Danach setzen Sie im Admin die Rechte für Artikel und Schnipsel und prüfen, ob alles funktioniert.
Templates und Twig
Diese Änderungen betreffen den Code des Projekts:
- Adresse.
resource_locatorundrouteheißen jetzt immerrouteund tragen den Namenurl. Der Titel braucht das Tagsulu.rlp.part, damit der Admin die Adresse vorschlägt, und das Adressfeld das Tagsulu.rlp. Machen Sie es zum Pflichtfeld. - Artikeltypen werden Gruppen. Was in
sulu_article.typesstand, steht jetzt im Element<group>des Templates (siehe „Artikel in Sulu 3“). - Twig-Funktionen.
sulu_content_loadist insulu_page_loadundsulu_article_loadgeteilt, der Parameterpropertiesist Pflicht. Die Navigation heißtsulu_page_navigation_*(siehe „Seiten-Templates“). - Suche. Das MassiveSearchBundle ist weg, die Suche läuft über SEAL (siehe „Suche in Sulu 3“).
- Dokumentenmanager. Es gibt ihn nicht mehr. Inhalte ändern Sie per Message (siehe „Sulu 3 im Überblick“).
<property name="title" type="text_line" mandatory="true">
<tag name="sulu.rlp.part"/>
</property>
<property name="url" type="route" mandatory="true">
<tag name="sulu.rlp"/>
</property>
Stolpersteine nach der Datenmigration
Die Daten sind migriert, die Seite läuft, und trotzdem stimmt manches nicht. Beim Umstieg ist Folgendes aufgefallen:
- Datumsfelder leer. Der
DatePropertyResolverakzeptiert für den Feldtypdatenur das FormatY-m-d. Stand im Wert ein Zeitstempel wie2022-10-24T00:00:00+00:00, lieferte ernull. Der Wert muss in den Daten selbst korrigiert werden (hier in 24 Zeilen). - Alter Template-Cache. Ein veralteter, kompilierter Cache forderte noch das alte Feld. Leeren Sie nach dem Umstieg beide Caches, und bei Apache den OPcache.
- Spalten von Bundles. Die Tabelle der Testimonial-Einstellungen hatte noch
idUsersCreatorundidUsersChanger, das Bundle erwartetecreator_idundchanger_id. Der Admin zeigte den Fehler „Unknown column 't0.creator_id'“. Gelöst hat es eine gezielte Doctrine-Migration, keinschema:update. - Leere Alt-Blöcke. Eine Seite mit leeren Blöcken aus dem alten Typ
heading-and-textwarf imBlockPropertyResolvereine Exception. Entfernt wurden nur die leeren Blöcke, nach einer Sicherung. - Altes Composer-Skript. Das Skript
massive:search:initstand noch in denauto-scriptsdercomposer.json. Es gehört entfernt, weil das MassiveSearchBundle nicht mehr existiert. - Schema-Unterschiede.
doctrine:schema:update --dump-sqlnannte nach dem Umstieg 83 Anweisungen. Viele betrafen bewusst behaltene Alt-Tabellen und Löschvorschläge. Pauschal mit--forceausführen lässt sich das nicht; jede Anweisung wird einsortiert: gefährliche Aufräumarbeit, harmlose Namensabweichung oder nötige Migration.
Die Beispiel-Website führt doctrine_migrations_versions erst seit Anfang Oktober 2026. Bei der Vorbereitung des Livegangs galten 19 Migrationen als „not migrated“, obwohl ihre Wirkung schon in der Datenbank steckte. Sie wurden mit doctrine:migrations:version --add eingetragen, migrate lief nie, denn eine davon ist nicht umkehrbar.
Auf den Server
Die Migrationen im Projekt bilden die Datenübernahme aus Sulu 2 nicht vollständig ab. Beim Livegang wurde deshalb ein geprüfter Datenbank-Dump übernommen, ohne die phpcr_*-Tabellen, und der Server bekam eine neue Datenbank in einem neuen Ordner. So blieb der Rückweg über das Domain-Ziel offen. Den Ablauf für Folge-Deploys beschreibt „Ausliefern und aktualisieren“. Prüfen Sie nach dem Umschalten, was live läuft: Der Header X-Generator der Antwort nennt die Sulu-Version.