Update Contao 3 auf Contao 4
- 3.5
Wichtige Hinweise vor dem Update!
- Lies dir einmal den kompletten Beitrag von Anfang bis Ende durch und starte erst dann mit der Umsetzung!
- Erstelle auf JEDEN FALL ein komplettes Backup der Datenbank und Dateien.
1. Contao 3 für das Update vorbereiten
Du hast noch eine Installation mit Contao 2?
Du solltest nicht direkt auf Contao 4 aktualisieren. Führe zunächst ein Update auf die letzte Version von Contao 2, das ist die Version 2.11.17, durch. Danach aktualisierst du auf Contao 3.5.40 und erst anschließend kannst du auf Contao 4 upgraden. Die wichtigsten Schritte sind die Datenbankupdates. Layout- und Templateanpassungen solltest du erst nach der Aktualisierung auf Contao 4 vornehmen.
1.1. Contao 3 auf den aktuellen Stand bringen
Für ein Upgrade von Contao 3 auf Contao 4 muss deine Contao 3 Installation aktuell sein. Du musst deshalb ein Update deiner Installation auf die letzte Version von Contao 3.5 (3.5.40) durchführen. Da der Support für Contao 3.5 komplett eingestellt wurde, kannst du das Update aktuell nur noch manuell per FTP bzw. direkt auf der Konsole durchführen.
1.2. Alte Dateistruktur vorhanden?
Solltest du eine alte Installation haben, die bereits von Contao 2 auf Contao 3 aktualisiert worden ist, dann prüfe vorher, ob du schon auf die files-Ordnerstruktur migriert hast.
In Contao 2 wurden die Uploads standardmäßig unter /tl_files abgelegt. Seit Contao 3 werden die Benutzerdateien unter /files abgelegt. Contao 3 konnte jedoch noch mit dem Pfad /tl_files umgehen. Seit Contao 4 funktioniert das nicht mehr. Kontrolliere deshalb vor dem Update von Contao 3 auf Contao 4 deine Ordnerstruktur. Sind deine eigenen Dateien noch unter /tl_files abgelegt, dann muss das umgestellt werden.
Wie du hier vorgehst, erfährst du in folgendem Beitrag:
Unter Contao 3 den Ordner tl_files nach files umstellen
2. Erweiterungen unter Contao 3.5 prüfen
Im Laufe der Jahre haben sich in einigen Installationen viele Erweiterungen angesammelt. Die Liste mit den installierten Erweiterungen findest du in der Erweiterungsverwaltung bzw. in der Paketverwaltung.
Contao 3 Extension-Repository Ende Mai 2022 abgeschaltet
Der Erweiterungskatalog wurde abgeschaltet und kann nicht mehr aufgerufen werden. Es ist somit auch kein Update der Erweiterungen mehr direkt in Contao 3 möglich.
Um dennoch die Erweiterungsverwaltung im Backend aufzurufen, lösche die komplette URL unter Einstellungen > Erweiterungsverwaltung > Extension Repository-URL.
Alternativ prüfe die Erweiterung direkt im Ordner /system/modules über dein FTP-Programm.
Denke bitte auch daran, dass sich in einer Installation manuell installierte Erweiterungen befinden können, die nicht in der Erweiterungsverwaltung bzw. in der Paketverwaltung zu sehen sind. Dazu musst du dir den Inhalt des Ordners /system/modules per FTP oder anderen Tools ansehen.
Prüfe, welche Erweiterungen tatsächlich im Einsatz sind. Nicht genutzte Erweiterungen löschst du am besten noch vor dem Update auf Contao 4. Im Anschluss immer daran denken, dass du das Installtool aufrufst, um die Datenbank zu aktualisieren.
3. Sind die Erweiterungen für Contao 4 freigegeben?
Leider sind nicht alle Erweiterungen von Contao 3.5 auch unter Contao 4 bzw. Contao 5 verfügbar. Deswegen prüfst du als Nächstes, ob deine genutzten Erweiterungen (Abhängigkeiten kannst du ignorieren) für Contao 4.13 verfügbar sind. (https://extensions.contao.org).
Es kann auch vorkommen, dass eine Erweiterung unter einem anderen, neuen Namen verfügbar ist. Zum Beispiel lautet die Erweiterung [calendar_extended] unter Contao 4 [kmielke/calendar-extended-bundle]. Um die Installation aller nötigen Abhängigkeiten kümmert sich der Contao Manager bzw. der Composer automatisch.
Falls deine verwendete Erweiterung nicht für Contao 4.13 verfügbar ist, dann musst du eine entsprechende Alternative suchen.
4. Backup von Contao 3.5 erstellen
Nachdem Contao 3 jetzt für das Update auf Contao 4 vorbereitet ist, sicherst du folgende Dateien und Ordner:
- /files
- /templates
- /system/config/localconfig.php
- /system/config/langconfig.php
- /system/config/dcaconfig.php
Außerdem solltest du alle Erweiterungen sichern, die manuell installiert wurden
(/system/modules/deine_manuell_installierte_erweiterung).
Als Letztes muss noch die Datenbank gesichert werden. Um zu vermeiden, dass die gesicherte Datenbank unnötig groß ist, solltest du zuvor im Backend die Systemwartung aufrufen und die Daten bereinigen. Alternativ können beim Datenbank-Export auch folgende Tabellen ausgeschlossen werden:tl_lock, tl_log, tl_search, tl_search_index, tl_session, tl_undo tl_version
Diese Tabellen enthalten keine Informationen, die für Update oder Wiederherstellung einer Installation benötigt werden. Die Tabellen werden beim Aufruf der Datenbankmigration neu erstellt.
Als Beispiel hier der Exportdialog von phpMyAdmin für angepasste Tabellen.
Hinweis zu Contao 5
Inzwischen steht auch Contao 5 in der LTS-Version 5.3 zur Verfügung. Bitte beachte, dass du zuerst ein Update auf Contao 4.13 durchführen musst, damit alle erforderlichen Datenbankmigrationen abgeschlossen werden.
Wie du ein Update auf Contao 5 durchführen kannst, erfährst du in meinem Onlinekurs: Update auf Contao 5.
5. Contao 4 installieren und Datenbank aktualisieren
Das Update kann nicht direkt durchgeführt werden. Der Aufbau von Contao 4 unterscheidet sich grundlegend von der Vorgängerversion, weshalb du zwingend eine Parallelinstallation erstellen musst.
5.1. Zusätzliche Datenbank anlegen
Für Contao 4 benötigst du eine eigene Datenbank. Lege diese an und importiere die in Schritt 4 exportierten SQL-Daten von Contao 3.5.
5.2. Eigene Subdomain oder Lokale Umgebung
Für die Installation von Contao 4 konfigurierst du dir am besten eine neue Subdomain. D. h. deine Website unter Contao 3.5 läuft während es kompletten Vorgangs parallel weiter. Denk bitte daran, dass der Document-Root der Subdomain zwingend auf den Ordner /public zeigen muss.
Statt der Subdomain-Variante kannst du das ganze Upgrade auch lokal per XMAPP oder MAMP durchführen und später auf den Live-Server übertragen.
5.3. Installation von Contao 4 durchführen
Nun kannst du Contao per Contao Manager installieren. Bei der Installation wird dir die Auswahl zwischen der aktuellsten Version von Contao und der LTS-Version (derzeit Contao 4.13 und Contao 5.3) angeboten. Bitte wähle hier Contao 4.13 aus. Solltest du auf Contao 5 aktualisieren möchten, dann musst du trotzdem den Zwischenschritt über Contao 4 machen, da sonst nicht alle Änderungen in der Datenbank enthalten sind. Beachte die Besonderheit zur Datenbankverbindung im nächsten Punkt (5.4).
5.4. Datenbankmigration ausführen
Während der Installation mit dem Contao Manager richtest du eine Datenbankverbindung ein. Dieser Schritt ist extrem wichtig, da du hier Contao 4 mit der neuen Datenbank, in der sich die importierten Daten von Contao 3.5 befinden, verbindest (siehe 5.1.).
Wenn du alles richtig gemacht hast, werden zunächst die nötigen Migrationen durchgeführt (siehe Screenshot). Anschließend werden zahlreiche Tabellen und Felder zum Anlegen, Aktualisieren und Löschen angeboten. Achte darauf, dass du noch keine Löschungen durchführst. Führe die Datenbank-Änderungen so lange durch, bis nur noch Löschungen angeboten werden. Der Vorgang kann durchaus 4- bis 5 Mal nötig sein. Wenn nur noch Löschungen angezeigt werden, klicke auf «Abbrechen»
WICHTIG: Keine Löschungen!
Du führst zunächst KEINE Löschungen durch. D. h. die Checkbox bei Alle Änderungen inklusive Löschungen anwenden darf nicht ausgewählt werden. Das ist notwendig, da derzeit noch keine Erweiterungen installiert sind und sonst die Tabellen und Daten der Erweiterungen gelöscht würden.
6. Kompatible Erweiterungen installieren
Jetzt installierst du alle kompatiblen Erweiterungen über den Contao Manager (alternativ über die Kommandozeile) und führst danach die Datenbank-Migrationen aus. Auch jetzt werden noch keine Löschungen vorgenommen.
Die Erweiterungen, die als Ersatz für inkompatible Erweiterungen vorgesehen sind, solltest du ebenfalls installieren.
7. Alte Daten übertragen
7.1. Dateien übertragen
In diesem Schritt arbeiten wir überwiegend direkt im Filesystem deiner Installation.
Übertrage jetzt folgende gesicherte Ordner per FTP/SFTP in deine neue Installation
/files/templates
Dateien öffentlich erreichbar machen
Im Ordner unter /files müssen jetzt noch auf öffentlich gestellt werden, damit die Ressourcen auch im Web angezeigt werden können. Dazu meldest du dich im Backend an und navigierst zur Dateiverwaltung. Bitte beachte dabei, dass alle Dateien in Unterordnern von /files liegen müssen. Dateien, die direkt im Ordner /files liegen, können nicht öffentlich verfügbar gemacht werden.
Zur Sicherheit solltest du jetzt einmal unter Systemwartung > Symlinks neu erstellen ausführen.
7.2. Einstellungen übertragen
Danach solltest du die gesicherte localconfig.php anschauen und alle Einstellungen, die weiterhin benötigt werden, manuell übertragen. Dazu gehören unter anderem die Einstellungen für das Datumsformat, den Systemadmin oder die Uploadgröße.
In Contao 4 werden die Einstellungen für die verwendete Datenbank nicht mehr in der localconfig.php gespeichert. Diese Eintragungen werden also nicht in die neue localconfig.php übernommen. Auch einige Einträge, die von Erweiterungen stammen, die du nun nicht mehr verwendest, werden nicht in die neue localconfig.php übertragen. Die localconfig.php findest du in Contao 4 wie bisher im Ordner /system/config/.
Wenn du dir unsicher bist, welche Einstellungen du übernehmen solltest, kannst du die Einstellungen auch im Backend von Contao 4 neu setzen.
7.3. Anpassungen dcaconfig und langconfig
Wenn du keine Anpassungen an diesen beiden Dateien vorgenommen hast, dann kannst du diesen Schritt überspringen.
Die Eintragungen aus der dcaconfig.php und langconfig.php könnten zwar noch unter /system/config verwendet werden, das ist allerdings veraltet und muss spätestens mit Contao 5 geändert werden. Verwende deshalb den "neuen Weg". Dazu legst du einen neuen Ordner /contao an und darin die Unterordner dca und languages.
Unter /contao/dca benötigst du für jede Tabellenanpassung eine eigene Datei. Hier übernimmst du jeweils die passenden Einstellungen aus der dcaconfig.php.
Unter /contao/languages gibt es für jede Sprache einen Ordner. In diesen Ordner werden die Dateien für die Sprachkonfiguration abgelegt. Für die deutsche Sprache ist das dann der Ordner /de. Hier würde z. B. die Anpassung für den More-Link in der Datei default.php erfolgen.
Auf weitere Details gehen wir hier nicht ein, da das den Rahmen sprengen würde. Weitere Infos findest du hier:
DCA-Konfiguration und Sprachdateien in Contao anpassen.
7.4 Individuelle Module unter /system/modules
Unter Umständen gibt es neben den Erweiterungen aus dem Erweiterungskatalog (siehe Punkt 6) auch individuell programmierte Module und Anpassungen. Grundsätzlich unterstützt Contao diese alten Module noch. In den meisten Fällen sind jedoch zahlreiche Anpassungen für Contao 4 und PHP 8 erforderlich.
Solltest du individuelle Module für deine Installation haben, empfiehlt es sich, diese auf das neue Contao Framework zu migrieren oder als Bundle zu programmieren.
Da diese Anpassungen Programmierkenntnisse voraussetzen, gehen wir hierauf nicht näher ein.
Wichtiger Hinweis
Bitte übertrage die vorhandenen Module im Ordner /system/modules nur manuell, wenn du weißt, was du tust und wie du auftretende Probleme beheben kannst.
7.5. Anwendungs-Cache leeren
Damit die neue Konfiguration in Contao aktiv wird, musst du jetzt per Contao Manager den Anwendungs-Cache neu aufbauen. (Systemwartung > Prod.-Cache erneuern)
8. Datenbank-Migration: Löschung vornehmen
Nun ist es so weit und du kannst noch einmal die Datenbank-Migrationen starten und die Checkbox Alle Änderungen inklusive Löschungen auswählen und die Löschungen durchführen.
9. Weitere Nacharbeiten unter Contao 4
Wenn Contao 4 fehlerfrei funktioniert kommen je nach Umfang der Installation noch zahlreiche weitere Arbeiten auf dich zu. Dazu gehören unter anderem:
- Systemeinstellungen prüfen
- Layouteinstellungen prüfen
- CSS-Anpassungen durchführen
- Templates prüfen und anpassen
- Veraltete Javascript-Templates im Layout entfernen (z. B. j_slider)
- Formulare prüfen
- SMTP-Versand einrichten
- relevante Einträge aus der alten
.htaccessübernehmen (nicht 1:1 kopieren!) - Berechtigungen prüfen und anpassen
- URL-Suffix konfigurieren
- Caching neu einstellen
- …
10. Website Live schalten
Da wir das Upgrade auf einer Subdomain (siehe Schritt 5) durchgeführt haben, läuft auf unserer Hauptdomain immer noch das alte Contao 3.5. Das wollen wir nun ändern.
Wir schalten nun unserer Contao 4 Version live. Dazu ändern wir den Document-Root der Hauptdomain auf den Ordner /public der Contao 4 Installation.
Ich empfehle dir die alte Contao 3 Installation noch für eine Weile über eine Subdomain erreichbar zu halten. Das erleichtert die nachträgliche Fehlersuche bei Problemen, die du in deiner neuen Contao 4 Installation vielleicht zunächst übersehen hast.
Viel Spaß beim Update von Contao 3 auf Contao 4.
Empfehlung Videokurs
Eine ausführliche Schritt-für-Schritt-Anleitung findest du im Videokurs
"Umstieg auf Contao 4".
Möchtest du über neue Artikel informiert werden?
Dann trage hier deine E-Mailadresse ein und klicke auf „Abonnieren". Du erhältst regelmäßig aktuelle Infos über Contao und die Contao-Academy.
Über den Autor
Christian Feneberg ist der Initiator und Dozent der Contao Academy. Er bringt über 15 Jahre Praxiswissen in der professionellen Umsetzung von Contao-Websites mit. Zudem ist er Teil des Teams von trakked.io. Er liebt es, sich neues Wissen anzueignen und es weiterzugeben. Abseits des Bildschirms verbringt er am liebsten Zeit mit seiner Familie und in der Natur.
Folge Christian jetzt bei LinkedIn.
7 Kommentare
Roland
Hallo Christian! Vielen Dank für deine tolle Doku. Ich habe damit von 3.5 auf 4.13 aktualisieren können. Zum Schluss bin ich aber noch über das veraltete jQuery Template "j_slider" gestolpert. Hier wäre evtl. der Tipp hilfreich, das entsprechende Häkchen im Seitenlayout wegzunehmen.
Hallo Roland, danke für dein Feedback. Ich habe deinen Tipp unter Punkt 9 ergänzt.
Daniela
Ich weiß ich bin spät dran...
Ich habe heute den ganzen Tag versucht, von 3.5 auf 4.13 zu kommen, aber der Import der zuvor gesicherten SQL Datenbank ist schier unmöglich. Kaum sind die Daten drin, meckert der Contao Manager, Unknown database type enum requested, Doctrine\DBAL\Platforms\MySQL80Platform may not support it. Ich hab keine Ahnung, was ich anders machen soll.
Ohne den Import funktioniert alles, aber das ist ja nicht der Sinn der Sache. Meine alte Seite war ziemlich aufwändig, ich wäre wirklich dankbar für eine Hinweis.
Ich vermute, es gibt in deiner Datenbank ein oder mehrere Felder, die den Typ "enum" haben. Nach meiner Recherche wird das allerdings nicht mehr von Doctrine unterstützt. D. h. du müsstest die entsprechenden Spalten vom Typ Enums und TinyInts suchen und dann umwandeln oder entfernen.
Dazu müsstest du zunächst prüfen, welche Erweiterung diese Spalten angelegen haben. Evtl. benötigst du diese Erweiterung unter Contao 4 nicht mehr.
Mehr Support kann ich dir über diesen Weg nicht anbieten. Wenn du damit nicht zum Ziel kommst, bitte einmal im Contao-Forum dein Problem posten. Alternativ kannst du dich auch an unseren Support wenden und wir versuchen dir im Rahmen eines bezahlten Support-Auftrags zu helfen.
Micha
Vielen Dank für diese hilfreiche Anleitung.
Im Kapitel 5.4 steht:
"nur die SQL-Anweisungen unter "Tabellen anlegen" und "Spalten ändern""
ich nehme an "Tabellen ändern" sollte hier auch mit durchgeführt werden (habe ich jedenfalls beim Upgrade so gemacht) - nur eben nicht "Tabellen löschen" und "Spalten löschen".
Hallo Micha, danke für den Hinweis. Ich werde das im Text entsprechend anpassen.
Gert W.
Hallo, unter Punkt 5.2. wird, wie bisher bekannt, vom Rootverzeichnis /web geschrieben. Im Handbuch wird aber auch vom Ordner /public geschrieben:
https://docs.contao.org/manual/de/installation/systemvoraussetzungen/#hosting-konfiguration
Wie ist der aktuelle Stand, wenn man eine 4.13 installieren will? Wie soll die Ordnerstruktur aussehen? Vielen Dank im Voraus.
Hallo Gert, ab Contao 4.13 kannst du beides verwenden. Ich empfehle allerdings bereits den Ordner /public zu verwenden, da es ab Contao 5 kein /web mehr gibt.
Manuel von Heugel
Tolle Anleitung, vielen Dank!
Ladina Gisep
Dankeschön, Christian
Sehr hilfreiche Doku!
Sehr gerne!
Maik
Hallo und danke für die Anleitung! Ich kann mich irren, aber meinst Du nicht, dass ein Hinweis auf tl_files für die, die von Contao 2 auf 3 migriert haben und noch nicht auf Files umgestellt haben, Sinn machen könnte? Contao 3 kann ja noch problemlos mit dem tl_files Ordner fahren. Sollte man vielleicht im Zuge der Vorbereitung unter Punkt 1 einfügen. Sonst geht das wohl in die Contao Hose. :-)
Einen Kommentar schreiben