Update von Contao 4.9 auf Contao 4.13

Da es sich bei der Aktualisierung um ein Minor-Release handelt und die Versionsbedingung innerhalb des Contao Managers bzw. in der «composer.json» angepasst werden muss, kannst du dieses Update nicht wie gewohnt mit der Update-Funktion von trakked durchführen. Grundsätzlich ist der Update-Vorgang innerhalb der Contao 4 Reihe immer gleich und bereits im Contao Handbuch bestens dokumentiert. Deswegen haben wir unsere Anleitung um zusätzliche Hinweise speziell für Contao 4.13 ergänzt.

Um es möglichst einfach zu halten, erklären wir das Update nur anhand des Contao Managers und lassen die Möglichkeit über die Kommandozeile aussen vor. Ausserdem verwenden wir aktuell noch PHP 7.4 um Probleme mit Erweiterungen zu vermeiden. Mehr zur Umstellung auf PHP 8 am Ende des Beitrags.

Backup anlegen

Wie bei jeder grösseren Änderung, solltest du unbedingt ein Backup erstellen. Besonders wichtig sind dabei die Dateien «composer.json», «composer.lock», sowie ein komplettes Datenbank-Backup.

Contao 4.9 auf den aktuellen Stand bringen

Wenn du Contao 4.9 nicht regelmässig aktualisiert hast, solltest du zuerst ein Update auf die letzte Version von Contao 4.9 durchführen. Dazu öffnest du den Contao Manager und wählst «Pakete aktualisieren» und dann ganz unten noch mal im Dropdown den Eintrag «Alle Pakete aktualisieren».

Wenn du bereits trakked verwendest, kannst du das Update auch über unsere Update-Funktion durchführen.



Jetzt noch einmal das Installtool öffnen und die Datenbank auf den aktuellen Stand bringen. Es sollten keine Datenbankaktualisierungen mehr offen sein.

Kompatibilität der Erweiterungen prüfen

Nicht jede Erweiterung ist bereits mit Contao 4.13 kompatibel. Besuche deswegen vorher die Projektwebsite des Entwicklers und/oder das Repository auf GitHub. Gibt es bereits einen Hinweis oder News zur Kompatibilität? Wann wurde die Erweiterung zuletzt aktualisiert? Sind noch offene Tickets zu Contao 4.13 vorhanden? Zusätzlich kannst du auch noch im Contao-Forum nach aktuellen Beiträgen suchen oder vorab im Slack-Channel fragen.

Nutzt du ein fertiges Contao-Theme?

Solltest du ein fertiges Theme nutzen, dann prüfe beim Anbieter, ob dein Theme mit Contao 4.13 kompatibel ist und ob es ggf. bereits ein Update gibt.

Pakete aktualisieren

Melde dich nun 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 4.13.* 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 das Contao-Installtool aufrufen und die entsprechenden Datenbankaktualisierungen erledigen. 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.

Wenn das Update nicht klappt
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.

Versionsanpassungen bei den Erweiterungen

Dieser Schritt ist nicht zwingend nötig, kann unter Umständen jedoch nötig sein, wenn erst eine neuere Major-Version einer Erweiterung mit Contao 4.13 bzw. PHP 8 kompatibel ist.

Beispiel: terminal42/contao-easy_themes

Damit die neuste Version 3.x von Easy-Themes installiert wird, musst du genau wie bei Contao das Zahnrad klicken und entsprechend die Version anpassen.

Wie kannst du herausfinden, ob es eine neuere Version gibt?
Dazu klickst du im Contao Manager beim jeweiligen Paket auf «Details». Hier wird dir angezeigt, ob eine neue Major-Version verfügbar ist. Bevor du die Umstellung durchführst, lies dir unbedingt die Upgrade-Hinweise beim Entwickler der Erweiterung durch. Es kann sein, dass die neue Version umfassende Nacharbeiten benötigt oder unter Umständen komplett neu eingerichtet werden muss.

Logfile prüfen

Wirf zunächst einen kurzen Blick ins Logfile. Zu finden unter /var/logs/prod-*.log. Gibt es hier neue Fehlermeldungen, die behoben werden müssen?

Templates anpassen

Im Grossen und Ganzen hat sich bei den Templates zwar wenig verändert doch in Summe sind trotzdem 42 Templates betroffen. Ob eine Änderung für dich relevant ist, kannst du im Backend über die Vergleichsfunktion bei deinen angepassten Templates prüfen.

Hier kurz die wichtigsten Änderungen im Überblick

• Das schema.org-Markup wurde in diversen Templates entfernt und um die zentrale JSON+LD-Verwaltung ergänzt.
• Die Funktion «Patchwork\Utf8::substr» wurde durch die PHP-Funktion «mb_substr » ersetzt
• Bei den Templates für die Reader-Module wurde der «Back-Button» angepasst
• Das Insert-Tag für {{request_token}} wurde durch <?= $this->requestToken ?> ersetzt
• Die Download-Templates wurden um die Preview-Funktion ergänzt
• Die Such-Templates wurden angepasst
• Das Template für das Passwort-Feld wurde angepasst.

CSS-Klassen «first» und «last»

Die CSS-Klassen «first» und «last» werden nicht mehr automatisch bei Artikeln und Inhaltselementen hinzugefügt. Solltest du diese CSS-Klassen verwendet haben, musst du dein CSS entsprechend anpassen und solltest diese durch CSS-Selektoren (first-child, last-child, nth-child) ersetzen.

Grundsätzlich solltest du komplett auf die Nutzung der CSS-Klassen «first», «last», «even» und «odd» verzichten, da mit Contao 5 diese Klassen von allen Elementen entfernt werden.

Routing-Modus umstellen

Mit Contao 4.10 wurde ein neuer Routing-Modus eingeführt. Da einige Drittanbieter-Erweiterungen unter Umständen mit dem neuen Routing Probleme haben, ist dieser standardmässig deaktiviert und muss in der App-Konfiguration aktiviert werden. Dazu ist folgender Eintrag in der «config/config.yml» nötig:

contao:
  legacy_routing: false


Damit die Änderung der Konfiguration aktiv wird, muss der Anwendungs-Cache geleert werden.

Dynamische Sitemaps

Die sitemap.xml wird nicht mehr wie bisher als statische Datei auf den Server geschrieben, sondern beim Aufruf der Route /sitemap.xml in Abhängigkeit des jeweiligen Kontexts generiert und im HTTP-Cache abgelegt.

• Vorher: deine-domain.de/share/deine-sitemap.xml
• Nachher: deine-domain.de/sitemap.xml

Wenn du die Google Search-Console nutzt, dann solltest du den neuen Pfad auch bei Google bekannt geben.

Feld im Seitenlayout für Google-Webfonts entfällt

Mit Contao 4.11 wurde im Seitenlayout der Eintrag für die Google Webfonts entfernt. Bei der Migration sollte automatisch ein Eintrag unter «Zusätzliche <head>-Tags» erzeugt worden sein. Bitte prüfe das einmal nach. Aus Datenschutzgründen solltest du allerdings den Eintrag komplett entfernen und die Google Fonts lokal einbinden.

Berechtigungen anpassen

Mit dem Update wurden auch neue Felder in Contao hinzugefügt. Damit die Redakteure diese neuen Felder (z. B. den Seitentitel für FAQ-Einträge) nutzen können, musst du die Benutzergruppen entsprechend anpassen.

public-Ordner nutzen

Dieser Schritt ist nicht zwingend nötig, da Contao und der Contao Manager sowohl den alten als auch den neuen Pfad unterstützen. Falls du jedoch gerne eine einheitliche Installationsumgebung haben möchtest, kannst du den bestehenden «web-Ordner» in «public» umbenennen.

Achtung: Die Pfad-Änderung muss auch bei der Domain-Konfiguration im Hosting durchgeführt werden.

MySQL-Strict-Mode als Standard

Seit Contao 4.13 ist der MySQL-Strict-Mode standardmässig aktiviert. D. h. du kannst aufräumen und den manuellen Eintrag in der «config/config.yml», falls du ihn gesetzt hast, wieder entfernen.

composer.json prüfen

Diese Aufgabe ist nur nötig, wenn du Contao über die Kommandozeile verwaltest. Wenn du den Contao Manager nutzt, werden die nötigen Anpassungen automatisch vorgenommen.

Wenn die Erstinstallation deines Contao-Projekts schon etwas länger zurückliegt und du vielleicht bereits mehrere Versions-Updates durchgeführt hast, kann es vorkommen, dass bestimmte Einträge in der «composer.json» veraltet sind und angepasst werden sollten. Vergleich dazu am besten einmal die «composer.json» einer frischen Contao 4.13 Installation mit deiner eigenen «composer.json».

Sieh dir dazu besonders die folgenden Abschnitte genauer an:

• config
• extra
• scripts

Wie gesagt, dies ist nur relevant, wenn du «composer» über die Kommandozeile nutzt.

Überflüssige Erweiterungen entfernen

Contao wird fortlaufend verbessert und so werden gewisse Funktionen von Erweiterungen direkt in den Contao-Core integriert. So können seit Contao 4.11 die Metadaten für FAQs überschrieben werden und seit Contao 4.13 kanonische URLs konfiguriert werden.

Fazit

Das Update auf Contao 4.13 ist in den meisten Fällen relativ unkompliziert und ohne grössere Probleme machbar. Etwas schwieriger ist derzeit noch die Umstellung auf PHP 8, da es hier häufig an der Kompatibilität scheitert. Viele Entwickler haben bereits begonnen, ihre Erweiterungen anzupassen. Wir gehen davon aus, dass spätestens im Herbst die Umstellung auf PHP 8 ebenfalls problemlos klappt.