Contao Update von 4.13 auf 5.3

Das Update von Contao 4.13 auf Version 5.3 ist mit Sicherheit eines der wichtigsten Updates zum aktuellen Zeitpunkt (2024/2025). Es ist ein Wechsel von einer LTS Version (Long Term Version) zu anderen, bei der eine möglichst lange Minorupdate- und Patchunterstützung zu erwarten ist.

Was aus meiner Sicht zu beachten ist, habe ich in diesem Artikel einmal zusammen getragen.

I.) Zunächst sind die Zusatzmodule wichtig. Dies sollte man vor dem Update unbedingt gewissenhaft im Detail überprüfen. Für Contao 5.3 sind aktuell (noch) nicht alle Zusatzmodule verfügbar. Der Isotope Shop z.B. steht noch nicht zur Verfügung. Aber auch andere Module lassen noch auf sich warten, oder kommen vielleicht sogar überhaupt nicht für Contao 5.3.

Es gilt also zu entscheiden, ob man nun auf das betroffene Modul verzichten kann oder ob es eine Alternative dafür gibt, die dann in Contao 5.3 installiert werden kann. Kommt keine der beiden Entscheidungen in Frage, muss man wohl leider erst einmal bei der alten Version 4.13. bleiben und hoffen das es bald eine Lösung gibt.

II.) Update ohne Installationstool. Dieses Modul gibt es in Contao schon ewig (aus den ersten Tagen) und hat immer mehr an Bedeutung verloren, seit es den Contao-Manager gibt. Nun hat man es komplett entfernt. Soweit so gut, es gibt ja den Contao-Manager und der macht ja eigentlich das Gleiche wie das Install-Tool, also die Datenbank auf den aktuellen Stand bringen, mit allem was dazu gehört. In der Vergangenheit hat dies meistens, aber eben nicht immer so gut geklappt. Manchmal wollte der Manager die Datenbank einfach nicht komplett anpassen, egal wie oft man ihn bemühte. Der Wechsel in das Install-Tool brachte dann meist den Erfolg und alles war gut. Diese Option gibt es nun nicht mehr. Es kann also sein, das man Probleme bekommt und die sind dann schwerer zu lösen. Klar, ein Wechsel in die Konsole wird dann in den Foren empfohlen, aber nach meiner Erfahrung haben die wenigsten ein Hostingpaket das einen Konsolenzugriff zulässt. Diesen möglichen Fallstrick muss man einfach wissen. Vorab prüfen kann man dies nicht, es zeigt sich dann beim Ablauf der Installation.

III.) Keine interne CSS-Unterstützung mehr. Seit Contao 5 ist das interne CSS Modul weg gefallen. Eine Entscheidung der Entwickler, die schon lange festgelegt wurde und auch bereits in Contao 4 als Warnung dort angezeigt wurde. Da aber in sehr viele Webseiten die CSS Anweisungen genau mit diesem Tool von den Webmastern umgesetzt wurden, muss man dies nun beim Update beachten. Auch die zukünftige Pflege der Webseite in Sachen CSS ist nun einfach anders (mittels FTP Client wird die CSS Datei getauscht). Der Pflegende, der vielleicht einmal selbst in die CSS Datei(en) eingegriffen hat (soll es ja geben), kann dies nun nicht mehr im Backend von Contao erledigen.

Update auf Contao 5.3 - Step by Step Anleitung.

Erste Schritte - Alle Backups anfertigen:

1.) Ein Datenbank Backup machen. Einfach den MySQL-Dump erstellen und in die neue, leere Datenbank importieren (meist mit PHPMyAdmin).

2.) Via FTP ein Backup der Datei composer.json und composer.lock machen, auch von der Datei parameters.yml im Ordner /config. Ebenso muss man die Datei localconfig.php im Ordner /system/config/ sichern (ggf. auch andere Dateien die man hier hinterlegt hat).

Weitere Backups macht man vom Ordner /files und /templates. auch vom Ordner /assets/css ein Backup um ggf. die CSS Dateien aus dem internen CSS Modul zu sichern.

Von manuell installierten Modulen sollte man auch ein Backup machen (/system/modules/), hat man den Manager für die Modulinstallation genutzt ist dies nicht notwendig.

Ich mache meist auch noch einen Screenshot aller installierter Module, einfach um einen schnellen Überblick zu haben, was alles auf der alten Verison installiert ist. Man kann es sich aber auch notieren.

Nächste Schritte - Ziel einrichten, Dateien ändern, Backups rückspielen:

3.) Jetzt einen neuen, leeren FTP Zugang im Ziel-Hosting anlegen und dort Contao 5.3 einfach wie üblich im Ordner /web mittels der Datei contao-manager.phar.php installieren. Wichtig ist zum Abschluss der Installation nicht die Datenbankeinrichtung aufrufen! Diesen Schritt einfach überspringen und direkt in den contao-manager gehen.

4.) Die zuvor gesicherten Dateien aus Schritt 2 werden nun an die passenden Stellen in die korrekten Ordner zurück kopiert (Ordnerstruktur muss erhalten bleiben). Ich empfehle an dieser Stelle nur einmal en Ordner /templates (sofern notwendig) und ganz wichtigen dern Ordner /files zu kopieren. Hier ist es enorm wichtig die Daten an die korrekten Stellen zurück zu kopieren, also nicht in den /web Ordner sondern eine Ebene darüber. Die meisten Ordner sind schon angelegt. Gibt es einen Ordner nicht, einfach anlegen um die Daten dort abzulegen. Die Dateien aus config und system würde ich nicht kopieren, das würde ich dann manuell anlegen.

5.) Es ist wichtig, dass nun alle Zusatzmodule installiert werden. Welche Module dies sind kann man in der alten Installtion (oder im oben erwähnten Screenshot) nachsehen. Man kann die composer.json in den Rootordner legen dann werden die Module in den Contao Manger direkt eingetragen, aber ich würde empfehlen die Module Stück für Stück und manuell zu installieren. Das hat einfach den Vorteil das man besser prüfen kann ob auch alle Module für Contao 5.3 untersützt werden und die Installtion korrekt abläuft.
Nun die Installation der angezeigten Zusatzmodule vornehmen und abschließen. Prüfe nun ob alle Zusatzmodule korrekt installiert wurden und keines fehlt.

6.) Hat man alle Module installiert (auch die manuellen), sollte man nun erst die neue Datenbank einrichten (Zugangsdaten notieren), und z.B. mittels PHPMyAdmin das unter 1.) gemachte Backup (SQL Dump) importieren.

7.) Nun das Datenbank-Update durchführen. Dazu den Contao-Manager starten, oder wenn man bereits im Manger ist die Systemprüfung neu auslösen. Alles wird geprüft und am Ende weißt einem das System auf die fehlende Datenbank hin. Dort klicken und die Datenbankdaten der neuen Datenbank eingeben. Bestätigen und die Datenbank wird angepasst. Man muss ggf. ein paar mal auf weiter klicken. Löschungen ggf. noch nicht ausführen, falls noch ein Modul fehlt, das man erst noch nachinstallieren möchte. Sollte es hier nun wie bei II.) beschreiben Probleme geben, kann es helfen ggf. abzubrechen und den Contao-Manger neu zu starten. Dann erneut auf Systemwartung und auf Datenbank prüfen. Dann sollten sich die meisten Probleme beheben.
Zum Schluss bleiebn oft die überflüssigen Ordner übrig, die noch gelöscht werden müssen. Dazu bei der Datenbank Änderung dann den Halen bei "Alle Änderungen inklusive Löschungen anwenden."

8.) Zum Abschluss meldet man sich im Contao-Backend (Wichtig im Backend, nicht im Contao-Manager an (dies sollte nun klappen) und wählt in der der Systemwartung die Option 'Symlinks neu erstellen'. Außerdem an dieser Stelle noch den 'Bilderchache leeren' und den 'Skriptcache leeren' damit Bilder und CSS Dateien und Scripte korrekt geladen werden. Prüfen ob die Dateiordner unter Dateien öffentlich sind, damit die Bilddaten geladen werden können.

9.) Nun fehlen noch die CSS Dateien, da es ja das interne CSS Modul nicht mehr gibt. Diese CSS Dateien in einen Ordner in die Dateiverwaltung hochladen (via FTP oder Dateiverwaltung...) und dann die CSS Dateien in den Templates jeweils einbinden (mit einem Link in den head-Tags oder mit "externe Stylesheet" auswählen.

Nun sollte die Webseite eigentlich funktionieren. Klappt etwas nicht sollte man die Schritte alle nochmal durchgehen. Gerade beim ersten Mal kann es etwas kniffelig sein.

Nacharbeiten sind meist ohnehin notwendig. Gerade bzgl. der CSS Datei. Einige viele der zuvor bekannten Standardklassen wurden verändert oder entfernt, so das eine Anpassung im CSS Code eigentlich unumgänglich sein wird.

Nachträge bzgl. Fehlerbehebung:

1.) Die URL Struktur wurde mit Contao 5 etwas verändert. Hatte man vorher einen Aufruf z.B. mit domain.de/startseite.html wird nach dem Update auf Contao 5.3 nun der Standardaufruf mit domain.de/startseite erfolgen. Das verursacht nun, dass eine User der z.B. über eine Suchmaschine kommt, oder aus seinen Favouriten einen Aurfuf von domain.de/startseite.html vornimmt einen Fehler 404 erhält. Das Suffix fehlt also nun und das kann problematisch sein. Möchte man das .html am Ende beibehalten, ergänzt man in der Seitenübersicht (bei "Seiten" und dort "Startpunkt einer Seite") im Feld "URL-Suffix" einfach den Wert .html

2.) Templates aus den alten Contao Versionen (auf HTML5 Basis) könne oft weiter verwendet werden. Aber nicht ohne Anpassungen. Es ist daher ratsam Template neu aufzubauen (auf Twig Basis).