Reihe 5: Sulu für Entwickler Kapitel 16 von 16

Von Sulu 2 auf Sulu 3

Entwicklung
Gilt für: jede Sulu-Website Stand: Sulu 3.0

Kurz zusammengefasst

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.

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:

  1. Die neuesten 2.x-Versionen von Sulu und seiner Bundles installieren und alle PHPCR-Migrationen ausführen: php bin/adminconsole phpcr:migrations:migrate.
  2. 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.
  3. Wer das sulu/article-bundle hat, aktualisiert es zuerst auf die neueste Version und stellt sicher, dass die Migration Version202407111600 gelaufen ist; danach wird das Bundle mit composer remove sulu/article-bundle --no-scripts entfernt. Flex kann dabei config/templates/articles/* löschen, die Dateien lassen sich aus der Versionsverwaltung zurückholen.
  4. Das PHPCR-Repository aufräumen: php bin/adminconsole sulu:document:phpcr-cleanup.

Sulu 3 einspielen

Dann folgen die neuen Pakete und die Datenmigration:

Aus UPGRADE-3.x.md, in der Reihenfolge der Anleitung bash
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_locator und route heißen jetzt immer route und tragen den Namen url. Der Titel braucht das Tag sulu.rlp.part, damit der Admin die Adresse vorschlägt, und das Adressfeld das Tag sulu.rlp. Machen Sie es zum Pflichtfeld.
  • Artikeltypen werden Gruppen. Was in sulu_article.types stand, steht jetzt im Element <group> des Templates (siehe „Artikel in Sulu 3“).
  • Twig-Funktionen. sulu_content_load ist in sulu_page_load und sulu_article_load geteilt, der Parameter properties ist Pflicht. Die Navigation heißt sulu_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“).
Adressfeld einer Vorlage, nach UPGRADE-3.x.md html
<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 DatePropertyResolver akzeptiert für den Feldtyp date nur das Format Y-m-d. Stand im Wert ein Zeitstempel wie 2022-10-24T00:00:00+00:00, lieferte er null. 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 idUsersCreator und idUsersChanger, das Bundle erwartete creator_id und changer_id. Der Admin zeigte den Fehler „Unknown column 't0.creator_id'“. Gelöst hat es eine gezielte Doctrine-Migration, kein schema:update.
  • Leere Alt-Blöcke. Eine Seite mit leeren Blöcken aus dem alten Typ heading-and-text warf im BlockPropertyResolver eine Exception. Entfernt wurden nur die leeren Blöcke, nach einer Sicherung.
  • Altes Composer-Skript. Das Skript massive:search:init stand noch in den auto-scripts der composer.json. Es gehört entfernt, weil das MassiveSearchBundle nicht mehr existiert.
  • Schema-Unterschiede. doctrine:schema:update --dump-sql nannte nach dem Umstieg 83 Anweisungen. Viele betrafen bewusst behaltene Alt-Tabellen und Löschvorschläge. Pauschal mit --force ausführen lässt sich das nicht; jede Anweisung wird einsortiert: gefährliche Aufräumarbeit, harmlose Namensabweichung oder nötige Migration.

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.

Mehr dazu

Offizielle Dokumentation