Update Contao 3 auf Contao 4

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.

Weitere Details zum Contao 3 Update.

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.

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 verfügbar. Deswegen prüfst du als Nächstes, ob deine genutzten Erweiterungen (Abhängkeiten kannst du igonrieren) für Contao 4 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 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 des Installtools neu erstellt.

Als Beispiel hier der Exportdialog von phpMyAdmin für angepasste Tabellen.

5. Contao 4 installieren und Datenbank aktualisieren

5.1. Datenbank

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

Als Nächstes installierst du Contao 4 über den Contao Manager (alternativ über die Kommandozeile per Composer).

Bei der Installation über den Manager wird dir die Auswahl zwischen der aktuellsten Version von Contao (derzeit Contao 5.1) und der LTS-Version (derzeit Contao 4.13) 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.

5.4. Installtool aufrufen

Nach erfolgreicher Installation verbindest du Contao 4 mit der neuen Datenbank, in der sich die importierten Daten von Contao 3.5 befinden (siehe 5.1.).

Wenn du alles richtig gemacht hast, dann werden dir jetzt vom Installtool bzw. der Contao Datenbankmigration zahlreiche Tabellen und Felder zum Anlegen, Aktualisieren und Löschen angeboten.

Außerdem werden automatisch die entsprechenden Migrations durchgeführt. (siehe Screenshot)

6. Kompatible Erweiterungen installieren

Jetzt installierst du alle kompatiblen Erweiterungen über den Contao Manager (alternativ über die Kommandozeile) und führst danach das Installtool aus. Auch jetzt werden noch keine Löschungen vorgenommen.

Die Erweiterungen, die als Ersatz für nicht kompatible Erweiterungen vorgesehen sind, solltest du ebenfalls installieren.

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, 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 übernommen. 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. 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. In diese übernehmen wir die 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:
Migration und Anpassung der Konfigurationsdateien dcaconfig und langconfig.

Damit die neue Konfiguration in Contao aktiv wird, musst du jetzt per Contao Manager den Anwendungs-Cache neu aufbauen. (Systemwartung > Prod.-Cache erneuern)

Viele Erweiterungen, die in Contao 3 verwendet wurden, funktionieren prinzipiell auch mit Contao 4. Es lohnt es sich also mit jeder einzelnen Erweiterung einen Versuch zu starten, die du nicht über den Contao Manager (alternativ über die Kommandozeile) installieren konntest bzw. für die du keinen adäquaten Ersatz gefunden hast.

Dazu kopierst du die gesicherten Ordner deine_manuell_installierte_erweiterung oder deine_nicht_verfuegbare_erweiterung in den Ordner /system/modules, rufst das Installtool auf (keine Löschungen vornehmen) und leerst danach den Prod.-Cache über den Contao Manager.

Dieses Verfahren kommt allerdings an seine Grenzen, wenn die oben genannten Erweiterungen Abhängigkeiten haben. Diese Abhängigkeiten müssten auch installiert werden, dabei kann es aber zu Unverträglichkeiten mit über den Contao Manager oder Composer installierten Erweiterungen kommen.

Ich empfehle dir jede manuelle Installation einzeln durchzuführen und jeweils Front- und Backend auf Fehlerfreiheit zu überprüfen. Somit bemerkst du gleich, welche der Erweiterungen Probleme bereitet.

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
• 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
• Installtool aufrufen und die verbliebenen Löschungen durchführen (vorher Backup!)
• …

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 /web 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.