Update von Contao 5.3 auf Contao 5.7

Contao 5.3 auf den aktuellen Stand bringen

Bevor du das Update startest, bringst du deine bestehende Installation auf den neuesten Contao 5.3-Stand. Öffne dazu den Contao Manager, führe «Pakete aktualisieren» aus und erledige alle offenen Migrationen und Datenbankänderungen.

Kompatibilität der Erweiterungen prüfen

Sehr viele Erweiterungen, die mit Contao 5.3 kompatibel sind, laufen auch unter Contao 5.7. Trotzdem lohnt sich ein kurzer Check: Prüfe auf Packagist oder GitHub, ob deine Erweiterungen Contao 5.7 unterstützen. Ein Blick auf offene GitHub-Issues oder das Datum des letzten Updates gibt dir einen guten Hinweis. Im Zweifelsfall hilft nur ausprobieren.

Fertiges Contao-Theme im Einsatz?

Nutzt du ein gekauftes Theme, prüfe beim Anbieter, ob es mit Contao 5.7 kompatibel ist und ob bereits ein Update vorliegt. Kläre offene Fragen am besten vorab mit dem Support des Herstellers, bevor du das Update startest.

PHP-Version prüfen

Für Contao 5.7 benötigst du mindestens PHP 8.3. Prüfe im Hosting-Panel, welche PHP-Version aktiv ist, und ändere sie falls nötig. Wir empfehlen dir, dass du jeweils die neuste PHP-Version auf deinem Hosting nutzt.

Backup erstellen

Sobald alle Voraussetzungen erfüllt sind, erstellst du ein vollständiges Backup. Besonders wichtig sind dabei die Dateien composer.json und composer.lock sowie ein komplettes Datenbank-Backup.

Mehr zum Thema Backup findest du im Beitrag: Das 1x1 für Contao-Backups.

Paket-Version anpassen und Update durchführen

Passe im Contao Manager oder direkt in der composer.json die Contao-Version von 5.3.* auf 5.7.* an:

"contao/manager-bundle": "5.7.*"

Prüfe ausserdem, ob einzelne Erweiterungen eine Versionsanpassung benötigen. Das ist zum Beispiel dann der Fall, wenn eine neue Major-Version einer Erweiterung vorliegt. Starte danach das Update über den Contao Manager («Pakete aktualisieren») oder direkt über Composer.

Schlägt das Update fehl, prüfe die Ausgabe des Contao Managers genau. In den meisten Fällen sind inkompatible Erweiterungen die Ursache.

Falls du mehr über Versionsbedingungen und Abhängigkeiten verstehen möchtest, empfehlen wir dir unseren Beitrag.

Datenbankmigrationen durchführen

Nach erfolgreichem Update führst du alle Datenbankmigrationen durch. Prüfe dabei alle vorgeschlagenen Löschungen sorgfältig, bevor du sie bestätigst.

Ist das Update erfolgreich abgeschlossen und ist zumindest das Backend wieder erreichbar? Dann geht es weiter mit den Nacharbeiten.

Twig oder HTML5?

Kommen wir zum Spannendsten und zeitlich aufwändigsten Teil: den Template-Anpassungen.

Die Zukunft von Contao heisst Twig. Contao 5.7 ist die letzte Version, bei der noch die alten HTML5-Templates unterstützt werden. Ab Contao 6 entfällt dieser Support vollständig.

Es ist verständlich, dass du beim Update auf 5.7 Zeit sparen möchtest, indem du vorerst bei den HTML5-Templates bleibst. Diese Arbeit kommt dann aber spätestens beim Update auf Contao 6 auf dich zu.

Unsere klare Empfehlung: Migriere jetzt zu Twig und nutze ab sofort ausschliesslich Twig-Templates.

Kurz zusammengefasst:

• HTML5-Templates beibehalten: Du bist mit dem Update fast fertig. Prüfe kurz, ob bei den Templates Anpassungen nötig sind und mache weiter mit dem Abschnitt Weitere Nacharbeiten.
• Zu Twig migrieren (empfohlen): Lies weiter, wir geben dir Tipps für die Migration an die Hand.

Migration nach Twig

Seit Contao 5.7 gibt es für alle Templates eine Twig-Version. Es ist die erste Contao-Version, die vom Core aus zu 100% mit Twig-Templates arbeitet.

Die Vorgehensweise ist klar: Nimm dir jedes Template einzeln vor und erstelle dafür die entsprechende Twig-Variante.

Beispiel: Du hast das Template news_full.html5 angepasst. Dann ersetzt du es durch news_full.html.twig und überträgst deine Anpassungen in die Twig-Syntax.

Wenn möglich, überschreibe nur einzelne Blöcke statt das komplette Template. Das news_full-Template gehört allerdings zu den älteren Templates, die nur den Block info kennen und muss daher häufig vollständig überschrieben werden.

Konkretes Beispiel: Du hast in news_full.html5 den Autor entfernt und das Datum individuell formatiert. Bisher sah das so aus:

<?php $this->extend('news_full'); ?>

  <?php $this->block('info'); ?>
    <p class="info"><time datetime="<?= $this->datetime ?>"><?= \Contao\Date::parse("d. F Y", $this->timestamp); ?></time></p>
  <?php $this->endblock(); ?>

Das entsprechende Twig-Template news_full.html.twig sieht dann so aus:

{% extends "@Contao/news_full.html.twig" %}

{% block info %}
    <p class="info"><time datetime="{{ datetime }}">{{ timestamp|date("d. F Y") }}</time></p>
{% endblock %}

Deutlich übersichtlicher, und der Aufwand hält sich in Grenzen.

Wichtig: Das alte HTML5-Template musst du löschen oder umbenennen, damit das neue Twig-Template erkannt wird. Arbeite in der Entwicklungsphase im Debug-Modus, damit Template-Änderungen sofort wirksam werden, ohne den Cache jedes Mal manuell zu leeren.

Ob du dabei lieber das Template Studio oder deine IDE (z. B. PhpStorm oder Visual Studio Code) nutzt, ist dir überlassen.

Praktische Tipps zur Twig-Migration

Eine All-in-One-Lösung gibt es nicht, da die Anpassungen von Projekt zu Projekt sehr individuell sind. Manche Templates enthalten eigenen PHP-Code, der in Twig nicht mehr direkt möglich ist und in Filter oder Funktionen ausgelagert werden muss. Die offizielle Dokumentation hilft dir dabei weiter:

• Custom Code in Twig-Templates

KI-Tools können bei der Konvertierung von HTML5-Templates nach Twig eine nützliche Unterstützung sein. Wichtig ist dabei: Nutze sie als Hilfsmittel, nicht als vollautomatische Lösung. Wer nicht versteht, wie Contao mit Twig arbeitet, erkennt Fehler in der generierten Ausgabe nicht. Lies dich daher zuerst in die Grundlagen ein, bevor du Templates konvertieren lässt.

Im Folgenden findest du die häufigsten Anpassungen, auf die du beim Migrieren stösst.

Insert-Tags in Templates

Hast du Insert-Tags in deinen Templates verwendet, nutzt du dafür jetzt die entsprechenden Twig-Funktionen oder Filter.

• Insert-Tag als Funktion: Geeignet für Inhalte, die auch HTML-Tags enthalten können.
• Insert-Tag als Filter: Geeignet für Texte, in denen kein HTML erwartet wird.

Beispiel Funktion: {{link_url::42}} wird zu:

{{ insert_tag('link_url::42') }}

Beispiel Filter: {{date::Y}} wird zu:

{{ '{{date::Y}}'|insert_tag }}

Datum in News oder Events formatieren

Das hatten wir im Beispiel oben bereits. Zur Vollständigkeit:

PHP:

<?= \Contao\Date::parse("d. F Y", $this->timestamp); ?>

Twig:

{{ timestamp|date("d. F Y") }}

Zugriff auf globale Variablen

Auch für den Zugriff auf globale Variablen wie $objPage hat das Contao-Team eine Lösung bereitgestellt:

• Twig-Globals: contao

Beispiel: Bisher hast du vielleicht so auf die CSS-Klasse einer Seite zugegriffen:

global $objPage;
$cssClass = $objPage->cssClass;

if (str_contains($cssClass, 'style1')) {
    // Dein Code
}

In Twig funktioniert das so:

{% set cssClass = contao.page.cssClass|default('') %}

{% if 'style1' in cssClass %}
    {# Dein Code #}
{% endif %}

Beispiel: Du hast eine mehrsprachige Website und möchtest den passenden Text direkt im Template ausgeben.

PHP:

<?php if($GLOBALS['TL_LANGUAGE'] == 'de'): ?>
	Hier steht ein deutscher Text.
<?php else: ?>
	Here is a text in English.
<?php endif; ?>

Twig:

{% if app.request.locale == 'de' %}
	Hier steht ein deutscher Text.
{% else %}
	Here is a text in English.
{% endif %}

TinyMCE-Template anpassen

In Contao 5.7 kommt TinyMCE 8 zum Einsatz. Nutzt du ein angepasstes TinyMCE-Template be_tinyMCE, musst du veraltete Bezeichnungen in der Toolbar ersetzen. Die wichtigsten Änderungen:

formatselect → blocks

styleselect → styles

fontselect → fontfamily

fontsizeselect → fontsize

Eine vollständige Liste findest du in der TinyMCE-Dokumentation:
Migration von TinyMCE 4 auf 8.

base-Tag prüfen

Der <base>-Tag wird in Contao 6 nicht mehr ausgegeben. Alle Pfade in Templates und CSS müssen daher absolut sein, also mit einem / beginnen.

Aus:

files/layout/css/style.css

Wird:

/files/layout/css/style.css

Prüfe alle deine Templates, CSS-Dateien auf relative Pfade und passe sie entsprechend an. Damit bist du auch für den Wechsel auf Contao 6 gut vorbereitet.

Formulare: Session-Speicherung prüfen

Bisher hat Contao Formulardaten immer kurzzeitig in der Session gespeichert, auch wenn kein {{form_session_data::*}}-Insert-Tag genutzt wurde. Das erzeugte ein Cookie und deaktivierte den HTTP-Cache für eine Minute.

In Contao 5.7 gibt es bei jedem Formular eine neue Einstellung, die die Session-Speicherung nur noch aktiviert, wenn sie wirklich benötigt wird. So lässt sich in vielen Fällen auf Session und Cookie im Frontend komplett verzichten, was die Caching-Performance verbessert.

Für alle bestehenden Formulare wird die Option automatisch aktiviert, um die Rückwärtskompatibilität zu gewährleisten. Prüfe deine Formulare und deaktiviere die Option überall dort, wo du keinen Zugriff auf die Formulardaten per Insert-Tag benötigst.

Eigene Programmierungen prüfen

Hast du eigene Anpassungen im src-Verzeichnis vorgenommen, prüfe diese ebenfalls und bringe den Code auf den Stand von Contao 5.7.

Weitere Punkte

• Berechtigungen anpassen: Schalte neue Features für Redakteure und Redakteurinnen in den Benutzergruppen-Einstellungen frei.
• Logfile prüfen: Schaue in /var/logs/prod-*.log, im Contao Manager unter «Tools und System-Log» oder in trakked nach neuen Fehlermeldungen.