Update von Contao 4.13 auf Contao 5.3

Bestehende Installation analysieren

Bitte prüfe nun Schritt für Schritt die einzelnen Punkte. Sollte eine Voraussetzung nicht gegeben sein, dann ist ein Update zum aktuellen Zeitpunkt unter Umständen nicht möglich.

Installierte Erweiterungen prüfen

Prüfe für jede installierte Erweiterungen, ob diese mit Contao 5.3 kompatibel ist. Dazu kannst du im Contao-Manager beim Paket die Details öffnen und zum Reiter «Abhängigkeiten» wechseln. Hier sollte bei «Contao Core» in der Versionsbedingung die Version 5 erlaubt sein. Das kann z. B. so aussehen:

Contao Core: ^4.13 || ^5.0

Mehr zum Thema «Contao Versionsbedingungen» erfährst du in unserem Blogbeitrag «composer.json - Versionsbedingungen und Abhängigkeiten verstehen».

Falls eine Erweiterung nicht für Contao 5 freigegeben ist, dann prüfe im nächsten Schritt, ob es eine neue (Major-)Version der Erweiterung gibt und diese für Contao 5 freigegeben ist.

Dazu klickst du bei den Paket-Details auf «mehr → Paketdetails». Es öffnet sich die Website von Packagist; dort wählst du den letzten verfügbaren Release und prüft den Eintrag «contao/core-bundle».

Sollte es keine neuere Version geben die mit Contao 5 kompatibel ist, dann kannst du diese Erweiterung leider nicht unter Contao 5 installieren.
Du hast nun mehrere Möglichkeiten:

• Erweiterung entfernen, falls diese nicht mehr benötigt wird
• Die nötigen Anpassungen selbst programmieren und einen Pull Request bereitstellen
• Entwickler:in kontaktieren und nötige Anpassungen kostenpflichtig beauftragen
• Ein gleichwertigen Ersatz für die Erweiterung finden

Wenn keine der genannten Optionen für dich eine Lösung darstellen sollte, ist derzeit kein Update auf Contao 5 möglich. In diesem Fall bleibt nur, vorerst bei Contao 4.13 zu bleiben.

Da wir selber natürlich auch gerne Erweiterungen einsetzen, haben wir dir in diesem Blogpost auch bereits die nötigen Informationen zu einigen populären Erweiterungen zusammengefasst. Du findest sie am Ende dieses Blogposts.

Theme prüfen (falls genutzt)

Solltest du ein vorgefertigtes Theme nutzen, prüfe unbedingt beim Hersteller, ob es für Contao 5.3 eine Freigabe gibt und inwieweit auch hier ein Update nötig ist.

Viele Anbieter haben bereits ihre Themes für Contao 5 freigegeben. Bei manchen Themes endet allerdings der Support bei Contao 4.13. Genauere Informationen dazu erhältst du direkt beim jeweiligen Theme-Anbieter.

Zusätzlich solltest du vor dem Update auf Contao 5.3 die offizielle Dokumentation bei deinem Theme-Anbieter prüfen. Oft gibt es hier ebenfalls themespezifische Hinweise, die es zu beachten gilt.

Individuelle Anpassungen und Programmierungen

Falls bei deiner Installation individuelle Programmierungen wie z. B. Hooks ergänzt worden sind (src-Verzeichnis), sind auch hier höchstwahrscheinlich Anpassungen nötigt. Wenn du diese Anpassungen nicht selbst gemacht hast, dann bitte deine:n Entwickler:in vorher einen Blick darauf zu werfen, damit die entsprechenden Anpassungen vorgenommen werden können.

Hosting prüfen

Sind alle nötigen Systemvoraussetzungen für Contao 5 gegeben? Besonders wichtig ist dabei, dass dein Server mindestens PHP-Version 8.1 oder aktueller anbietet.

Weitere Anforderungen findest du im Contao Handbuch.

Über die neuen Funktionen von Contao 5 informieren

Bei einem Update von Contao 4.13 auf 5.3 sind natürlich auch alle Änderungen der Versionen 5.0, 5.1 und 5.2 enthalten. Dies bedeutet, dass nach dem Update zahlreiche neue Funktionen und Anpassungen auf dich zukommen. Es ist daher sehr empfehlenswert, sich vorab einen Überblick zu verschaffen.

Im Speziellen möchte ich hier auf die folgenden Quellen hinweisen:

• Contao 5.0 Ankündigung, Veröffentlichung, Video & Changelog
• Contao 5.1 Ankündigung, Veröffentlichung, Video & Changelog
• Contao 5.2 Ankündigung, Veröffentlichung, Video & Changelog
• Contao 5.3 Ankündigung, Veröffentlichung, Video & Changelog
• Keynote Leo Konferenz 2023
• Was du über Contao 5.3 wissen musst
• Die Backend-Breite in Contao 5 begrenzen

Alle Voraussetzungen erfüllt?

Wenn alle der oben genannten Voraussetzungen erfüllt sind, dann kommen wir zur Praxis.

Backup erstellen

Wie bei jedem grösseren Update solltest du unbedingt eine Sicherung erstellen. Besonders wichtig sind dabei die Dateien «composer.json», «composer.lock», sowie ein vollständiges Datenbank-Backup. Eine Anleitung, welche Verzeichnisse du für ein vollständiges Backup zusätzlich sichern solltest, findest du in unserem Blogbeitrag «Das 1x1 für Contao Backups».

Parallelinstallation erstellen (empfohlen)

Damit du stets eine lauffähige Installation hast und nach der Aktualisierung einfach prüfen kannst, wie die Website unter Contao 4.13 ausgesehen hat, empfehle ich dir, das Update in einer Parallelinstallation durchzuführen. Dies ist zwar keine zwingende Voraussetzung, wird dir jedoch den Prozess erheblich erleichtern und unnötigen Stress ersparen.

Erstelle eine vollständige Kopie der Live-Website unter einer neuen Subdomain oder Lokal und spiele dort das Backup ein.

Contao 4 für das Update vorbereiten

Je nachdem, wie regelmässig und gewissenhaft du Updates für Contao 4 durchgeführt hast, können die nächsten Schritte mehr oder weniger Zeit erfordern. Bevor du das Update auf Contao 5.3 durchführst, sind die folgenden Aufgaben unter Contao 4 zu erledigen.

Update auf Contao 4.13

Aktualisiere zunächst auf die letzte verfügbare Contao 4.13. Das ist essenziell, damit das Update auf Contao 5 fehlerfrei durchläuft, da Contao 5 die Datenbank im Zustand der jüngsten Version 4.13 erwartet. Wenn du noch Contao 4.9 nutzt, dann kannst du als Hilfe die folgende Anleitung verwenden.

Verfügbare Datenbank-Migrationen durchführen

Öffne dazu den Contao-Manager, wechsele unter «Systemwartung» und klicke auf «Datenbank überprüfen». Führe alle offenen Datenbankmigrationen durch.

Inkompatible Erweiterungen vor dem Update entfernen

Solltest du in der Analysephase veraltete und inkompatible Erweiterungen festgestellt haben, dann entferne diese nun oder führe ein Update auf eine komplatible Version durch.

Internes CSS exportieren und als externes CSS im Layout einbinden

In Contao 5 wurde der interne CSS-Editor entfernt. D. h. du musst alle internen Styles exportieren und als externes CSS beim Layout hinzufügen.

Gehe dazu ins Backend von Contao unter «Themes → CSS». Zum Exportieren klicke nun bei jedem Stylesheet auf «exportieren».

Anschliessend kannst du die CSS-Dateien wieder dem Layout als externes CSS hinzufügen. Dazu lädst du dir zunächst die CSS-Dateien über die Dateiverwaltung in einen entsprechenden Ordner auf deine Installation und öffnest dann jedes Layout und ergänzt die entsprechenden CSS-Dateien als externes CSS. Gleichzeitig entfernst du die Haken bei den internen Stylesheets (siehe Screenshot).

Teste anschließend kurz, ob das Design wieder korrekt angezeigt wird. Entsprechende Korrekturen und Feintuning kannst du nach dem Update auf Contao 5.3 durchführen.

Mobile Layouts entfernen

Ebenso wie der interne CSS-Editor wurden auch die mobilen Layouts entfernt. Solltest du diese Funktion nutzen, dann musst die Responsivität für mobile Endgeräte über entsprechende MediaQueries direkt im CSS umsetzen.

PHP-Version anpassen

Stelle dein Hosting mindestens auf PHP-Version 8.1 um. Besser wäre allerdings PHP 8.3 oder neuer. Nach der Umstellung solltest du noch einmal «Alle Pakete» über den Contao Manager aktualisieren.

Website-Root auf public umstellen

In der Regel hast du das bereits mit dem Update auf Contao 4.13 erledigt. Sollte das noch offen sein, dann hole diesen Schritt am besten jetzt nach.

Benenne auf deinen Server den Ordner «web» in «public» um.

Anschliessend öffnest du die «composer.json» und entfernst unter «extra» den Eintrag "public-dir": "web".

Nach dieser Änderung musst du noch mal im Contao Manager ein Update aller Pakete durchführen.

Pakete aktualisieren

Melde dich beim Contao Manager an und passe die entsprechende Contao-Version an. Dazu klickst du auf das Zahnrad neben der Contao-Version und trägst hier 5.3.* ein.

Anschliessend ganz unten auf Änderungen anwenden und im Dropdown den Eintrag «Alle Pakete aktualisieren» wählen.

Wenn der Update-Prozess erfolgreich war, kannst du direkt über den Contao Manager die entsprechenden Datenbankaktualisierungen erledigen. (Anmerkung: Das Contao-Installtool gibt es unter Contao 5 nicht mehr). Solltest du Löschungen sehen, dann bitte genau prüfen, ob diese gerechtfertigt sind. Im Zweifel zunächst keine Löschungen durchführen und später erledigen.

Hilfe, mein Update schlägt fehl!

Sollte es beim Update zu einem Fehler kommen, dann prüfe einmal genau die Ausgabe des Contao Managers. Häufig ist hier schon zu erkennen, wodurch das Problem ausgelöst wird.

Unserer Erfahrung nach verhindern meist inkompatible Erweiterungen das Update auf Contao 5. Das sollte dir in der Regel schon bei der Analysephase aufgefallen sein. Je nach Lösungsansatz musst du beim Update-Prozess die Erweiterung entfernen oder die Versionsbedingung anpassen.

Beispiel: Notification Center 2.0 & Easy Themes entfernen

Nehmen wir an du hast beide Erweiterungen unter Contao 4.13 genutzt. In dem Fall änderst du die Contao-Version auf 5.3.*. Das allein reicht jedoch nicht. Du musst gleichzeitig das Notification-Center auf ^2.0 anpasen und Easy Themes entfernen, da es nicht mit Contao 5 kompatibel ist. Erst dann klickst du auf «Alle Pakete aktualisieren».

Twig- oder HTML-Templates nutzen

Mit der Veröffentlichung von Contao 5 wurden sämtliche Core-Inhaltselemente auf Twig-Templates umgestellt. Dies führt dazu, dass sich das Markup verändert hat und die entsprechenden CSS-Klassen der Elemente umbenannt wurden.

Wenn du derzeit nicht auf Twig umsteigen möchtest, besteht die Möglichkeit, weiterhin die HTML-Vorlagen (Legacy-Templates) zu verwenden. Beachte jedoch, dass du in einem der kommenden Updates diese Umstellung nachholen musst, da die Unterstützung für die alten Vorlagen nicht für immer fortgesetzt wird.

Als Faustregel empfehle ich, die Entscheidung anhand der Anzahl der angepassten Templates zu treffen. Bei einer geringen Anzahl empfehle ich definitiv Twig zu nutzen, während bei einer grösseren Anzahl die Verwendung von HTML-Templates aufgrund des Aufwands sinnvoller erscheint.

Triff nun deine Entscheidung – Twig oder HTML.

A) Legacy Templates aktivieren

Wenn du dich hierfür entschieden hast, dann kannst du über die contao/config/config.php die Konfiguration für die gewünschten Inhaltselemente ergänzen. Wie du siehst, ist eine Mischung von Twig und HTML-Elementen möglich, da du die Entscheidung pro Element teffen kannst.

// Restore legacy content elements
$GLOBALS['TL_CTE']['texts']['code'] = \Contao\ContentCode::class;
$GLOBALS['TL_CTE']['texts']['headline'] = \Contao\ContentHeadline::class;
$GLOBALS['TL_CTE']['texts']['html'] = \Contao\ContentHtml::class;
$GLOBALS['TL_CTE']['texts']['list'] = \Contao\ContentList::class;
$GLOBALS['TL_CTE']['texts']['text'] = \Contao\ContentText::class;
$GLOBALS['TL_CTE']['texts']['table'] = \Contao\ContentTable::class;
$GLOBALS['TL_CTE']['links']['hyperlink'] = \Contao\ContentHyperlink::class;
$GLOBALS['TL_CTE']['links']['toplink'] = \Contao\ContentToplink::class;
$GLOBALS['TL_CTE']['media']['image'] = \Contao\ContentImage::class;
$GLOBALS['TL_CTE']['media']['gallery'] = \Contao\ContentGallery::class;
$GLOBALS['TL_CTE']['media']['player'] = \Contao\ContentPlayer::class;
$GLOBALS['TL_CTE']['media']['youtube'] = \Contao\ContentYouTube::class;
$GLOBALS['TL_CTE']['media']['vimeo'] = \Contao\ContentVimeo::class;
$GLOBALS['TL_CTE']['files']['downloads'] = \Contao\ContentDownloads::class;
$GLOBALS['TL_CTE']['files']['download'] = \Contao\ContentDownload::class;
$GLOBALS['TL_CTE']['includes']['teaser'] = \Contao\ContentTeaser::class;

Nach der Änderung musst du einmalig den Anwendungscache über den Contao Manager neu erstellen. Anschliessend verwendet Contao weiterhin die alten HTML-Templates und du musst sehr wenig an deinen alten CSS-Anweisungen anpassen. Eine Kontrolle ist dennoch wichtig.

B) Twig-Templates nutzen (empfohlen)

Langfristig ist es wesentlich sinnvoller, wenn du auf Twig wechselst, da dieser Schritt früher oder später unumgänglich ist. Wenn du dich dafür entscheidest, dann musst du allerdings deine bestehenden Templateanpassungen bei Twig neu durchführen.

Da dieses Thema sehr komplex ist, kann ich in diesem Beitrag nicht darauf eingehen. Solltest du noch keine Kenntnisse in Twig haben, dann hier ein paar Quellen:

• Contao Handbuch
• Vortrag Maren Lange (YouTube)
• Twig for Template Designers (Symfony)

Wenn du bisher keine Templates angepasst hast, sondern nur die Core-Templates nutzen, dann musst du nur dein CSS entsprechend anpassen.

Neue Content-Elemente für Slider und Akkordeon

Um die Migration und den Übergang zu Contao 5 zu erleichern, werden auch hier noch die alten Slider und Akkordeon-Elemente unterstützt. Im Backend erkennst du diese an dem Zusatz (legacy). Du kannst auch hier wieder entscheiden, ob du weiter die alten Elemente nutzt oder entsprechend auf die neuen Elemente wechselst.

Entscheidest du dich für einen Wechsel, musst du die Elemente neu anlegen und auch das CSS entsprechend erweitern.

Logfile prüfen

Wirf einen kurzen Blick ins Logfile. Zu finden unter /var/logs/prod-*.log oder im «Contao Manager» über «Tools und System-Log». Gibt es hier neue Fehlermeldungen, die behoben werden müssen?

Weitere Nacharbeiten

• Logout-Modul durch Logout-Page ersetzen
• Die Funktion «nur für Gäste anzeigen» wurde entfernt und wird im Migrations-Script bei einer Aktualisierung umgeschrieben. Verwende in Zukunft stattdessen die Funktion «Seite schützen».
• Der {{post::}}-Inserttag wurde entfernt. Um auf übermittelte Formulardaten auf Weiterleitungsseiten zuzugreifen, kannst du stattdessen den neuen {{form_session_data::}}-Inserttag verwenden.
• Der RSS-Feed ist jetzt nicht mehr bei den Newsarchiven zu finden, sondern es gibt eine eigene Seite vom Typ News-feed (ggf. im Menü verstecken)
• Bei den News lassen sich die Meta-Felder (Datum, Autor und Kommentar) nicht mehr über das Modul konfigurieren. In Zukunft wird im Template news_full, news_latest, news_short immer die Info-Zeile mit Datum um Autor ausgegeben. Alles andere muss direkt im Template erfolgen.
• Im Frontend-Modul des Login-Formulars hast du die Möglichkeit, einen Link zur Passwort-Reset-Seite einzufügen.
• Die Funktion Bildabstand (margin) ist nicht mehr vorhanden. Bei Bedarf müssen gesetzte Abstände über das zentrale CSS ergänzt werden.

Wie kann dich trakked nach dem Update auf Contao 5 unterstützen?

Ursprünglich haben wir trakked entwickelt, um uns von der lästigen Pflege von Excel-Listen zu befreien. Im Laufe der Zeit hat sich trakked zu einer umfassenden Toolbox für die Wartung von Contao entwickelt. Besonders mit der integrierten Update-Funktion ist es ein Leichtes, deine Contao 5.3 Installationen mit Bugfix-Updates zu versorgen und auf dem neuesten Stand zu halten. Dadurch lässt sich der Update-Aufwand um geschätzt zwei Drittel reduzieren. Eine komplette Liste der Features von trakked findest du hier.

Für uns und viele unserer Kunden ist trakked ein unverzichtbares Tool für die Verwaltung der Contao-Installationen und Einhaltung der Wartungsverträge.

Jetzt unverbindlich testen!

Am besten testest du trakked für 30 Tage unverbindlich und überzeugst dich selbst von unserem Tool.

trakked testen

Du bist unsicher, ob sich trakked für dich rechnet? Dann hilft dir vielleicht unser Kalkulator weiter.

Update-Hinweise zu bekannten Erweiterungen

In diesem Abschnitt sammeln wir Nacharbeiten, die wir bei unseren Updates im Zusammenhang mit bekannten Contao-Erweiterungen festgestellt haben.

Contao Cookiebar [oveleon/contao-cookiebar]

Die Contao Cookiebar ist ab der Version 2.0 mit Contao 5 komaptibel. Die Dokumentation zur Erweiterung findest du auf GitHub.

Easy Themes [terminal42/contao-easy_themes]

Die Erweiterung wird nicht mehr weiterentwickelt und steht unter Contao 5 nicht mehr zur Verfügung. Du musst jedoch auch in Contao 5 nicht auf die Vortreile von Easy Themes verzichten. Verwende dazu den «Stern (Favorit speichern)».

Isotope eCommerce [isotope/isotope-core]

Derzeit ist Isotope nicht mit Contao 5 kompatibel. Weitere Infos findest du auf GitHub.

MetaModels [metamodels/core und weitere]

Bei MetaModels wird an der Version 2.4 für Contao 5.3 gearbeitet. Sobald eine erste Version zur Verfügung steht, kann diese über das «early adopter Programm» bezogen werden.

mmenu - Mobile Navigation für Contao [dklemmt/contao_dk_mmenu]

Die Erweiterung ist ab Version 4.1 mit Contao 5 kompatibel.

Notification Center [terminal42/notification_center]

Das Notification Center ist ab der Version 2.0 mit Contao 5 kompatibel. Du musst also hier die Versionsbedingung ändern. Da es sich um einen kompletten Rewrite der Erweiterung handelt, sind gewisse Funktionen angepasst worden und teilweise auch weggefallen. Mehr dazu in der UPGRADE.MD.

RockSolid Custom Elements [madeyourday/contao-rocksolid-custom-elements]

Hier sind bei der Konfiguration der einzelnen Elemente folgende Anpassungen nötig:

Alt:

'image' => array(
    'inputType' => 'fileTree',
    'eval' => array(
        'extensions' => \Config::get('validImageTypes'),
    ),
),

Neu:

'image' => array(
    'inputType' => 'fileTree',
    'eval' => array(
        'extensions' => '%contao.image.valid_extensions%',
    ),
),

Alt:

'imageSize' => array(
    'inputType' => 'imageSize',
    'options' => \System::getImageSizes(),
),

Neu:

'imageSize' => array(
    'inputType' => 'imageSize',
    'options' => \Contao\System::getContainer()->get('contao.image.sizes')->getAllOptions(),
),

Wenn dein Kunde in einem Textfeld lieber Basic Entities verwendet (z. B. [ - ] anstelle von ­), musst du im DCA die Feld-Definition aktivieren.

'eval' => array('basicEntities'=>true,)

Testen

Wie nach jedem grösseren Update solltest du die Website entsprechend prüfen. Vergiss dabei auch nicht den Versand der Formulare zu testen.

Fazit

Glücklicherweise sind bereits sehr viele Erweiterungen mit Contao 5 kompatibel. Ein Update ist somit bei vielen Installationen bereits heute möglich. Du solltest allerdings das Update auf Contao 5.3 nicht unterschätzen und genug Zeit einplanen. Insbeondere wenn du zahlreiche Templates angepasst hast und hier komplett auf Twig umstellen möchtest.

Schreib uns gerne deine Erfahrungen mit bekannten Erweiterungen und wir ergänzen deine Lösungsvorschläge in unserem Beitrag.