Contao 6.0.0 veröffentlicht

Bisher hat Contao Eingaben bereits beim Speichern encodiert, so wurde beispielsweise ein < als < in die Datenbank geschrieben. Ab Contao 6.0 verbleiben alle Daten roh in der Datenbank und werden erst bei der Ausgabe encodiert und maskiert.

Für die tägliche Arbeit im Backend ändert sich dadurch erst einmal nichts. Für die Entwicklung und bei der Ausgabe in den Templates sehr wohl. Ab sofort entscheidet der Kontext, in dem die Daten verarbeitet werden, ob sie 1:1 (raw) ausgegeben werden dürfen oder nicht. Was zum Beispiel in einem HTML-Template als unsicher eingestuft wird, kann bei der Übergabe an eine externe Schnittstelle unproblematisch und sogar gewünscht sein. Gerade bei extern angebundenen Systemen ist es erwünscht, dass Daten roh ankommen und nicht erst mühsam konvertiert werden müssen.

In Twig schützen Encoding (Codierung) und Escaping (Maskierung) die Daten bei der Ausgabe in Templates. Twig nutzt standardmässig UTF-8 und maskiert HTML-Ausgaben, um Cross-Site Scripting (XSS) zu verhindern. Wird aber der Filter |raw verwendet, musst du unbedingt prüfen, welche Daten dort ankommen, denn dort greift der Schutz nicht mehr und es dürfen keine ungeprüften Daten ausgegeben werden. Empfehlenswert ist, raw wo immer es geht zu vermeiden und besser sanitize_html('contao') zu nutzen, damit nur sichere HTML-Tags durchgelassen werden.

Moritz hat das Thema in seinem Vortrag zum Output-Encoding an einem Beispiel wunderbar erklärt. Ausserdem beschreibt Yanick in seinem Rückblick auf das erste Core-Entwicklertreffen 2026 ausführlich, warum Input-Encoding ein Problem ist. Beides lohnt sich zu lesen, wenn du tiefer einsteigen willst.

Logische Konsequenz ist nun auch, dass aufgrund der Umstellung auf Output-Encoding die Unterstützung von HTML5-Templates entfällt. Deswegen noch mal ganz deutlich: Das alte Template-System ist vollständig entfernt, Contao 6.0 arbeitet ausschliesslich mit Twig. Alle Templates mit der Endung .html5 funktionieren nicht mehr. Das betrifft nicht nur den Core, sondern auch jegliche Erweiterung.

Mehrere Backend-Themes sind in Contao 6.0 nicht mehr möglich. Das bisherige Theme «flexible» wird zum Standard und der Ordner system/themes entfällt. Wenn du das Backend individualisieren und anpassen möchtest, dann nutzt du dein angepasstes CSS und fügst dieses über einen Eintrag in der config/config.yaml ein.

# config/config.yaml
contao:
    backend:
        custom_css:
            - files/backend/custom.css
        custom_js:
            - files/backend/custom.js

In deinem Custom-CSS hinterlegst du zum Beispiel eigene Farben oder ein Logo. Siehe auch docs.contao.org.

Das Comments-Bundle unterstützt kein BBCode mehr. Damit konnte man z. B. den Kommentartext formatieren. Bestehende Kommentare migriert Contao beim Update automatisch auf Plaintext, du musst also nichts von Hand nacharbeiten.

Contao 6.0 entfernt im Wesentlichen den Code, der mit der alten HTML5-Template-Engine samt Templates zusammenhängt. So verschwinden über 30.000 Zeilen Altcode aus dem Core. Das zeigt auch, was für einen Koloss das Core-Team da bisher selbst gepflegt hat. Mit Twig setzt Contao jetzt stattdessen auf einen Industriestandard.

Andere Funktionen, die in Contao 5 als «deprecated» markiert sind, bleiben in Contao 6 überwiegend erhalten, sofern sie nicht mit dem Input-Encoding zusammenhängen. Entfernt wird dieser Code erst mit Contao 7. Diese Entscheidung gibt den Entwicklern und Entwicklerinnen von Erweiterungen mehr Zeit für die nötigen Anpassungen.

Der Twig-Filter insert_tag_raw heisst jetzt insert_tag_html. Der alte Name funktioniert weiterhin, ist aber deprecated.

Contao berechnet die Datei-Hashes jetzt mit xxh128 statt mit md5. Das ist spürbar schneller, gerade bei grossen Dateibeständen. Für das Update bedeutet das: Synchronisiere das Dateisystem vorher einmal komplett, damit die Migration die Hashes sauber neu aufbauen kann.

Das Insert-Tag {{file::*}} arbeitet jetzt mit dem virtuellen Dateisystem. Damit greift es auf dieselbe Abstraktionsebene zu wie der Rest von Contao und profitiert von den zusätzlichen Möglichkeiten.

In diesem Zusammenhang wurde das gesamte File-Handling auf das VFS umgebaut. Nutzt du den File-Insert-Tag oder das Download- bzw. Video-Element für eine Datei im files-Verzeichnis, die nicht öffentlich ist, generiert Contao jetzt temporäre URLs zu den geschützten Dateien. Dadurch lassen sich geschützte Dateien für eingeloggte Mitglieder direkt einbinden statt nur als Download anzubieten. Ein Video aus einem geschützten Verzeichnis kannst du damit zum Beispiel jetzt streamen, statt es nur herunterladbar zu machen.

Eigene CSS-Klassen für Formularfelder setzt Contao jetzt nur noch am umschliessenden Wrapper und nicht mehr zusätzlich an jedem einzelnen Feld darin. Prüfe dein CSS an dieser Stelle, falls du dich bisher auf die Klasse direkt am Feld verlassen hast.

Fehlt ein Wert, liefert das Model jetzt den Default aus der Spaltendefinition statt null. Ausserdem castet Contao die Werte auf den Spaltentyp der Datenbank. Das sorgt für verlässlichere Rückgabewerte und weniger Sonderbehandlungen im eigenen Code.

Neben den echten Datenbankfeldern kennt Contao seit Version 5.7 auch virtuelle Felder. Der Hintergrund ist ein praktischer: MySQL begrenzt die Zeilengrösse pro Tabelle. Wer viele Erweiterungen einsetzt, ist bisher an diese Grenze gestossen (Stichwort: «Row size too large») und konnte keine weiteren Felder mehr anlegen. Mit virtuellen Feldern passiert das nicht mehr.

In Contao 6.0 nutzt der Core nun selbst erstmals virtuelle Felder für das Video-Player-Element. Für die Entwicklung bringt der Core ausserdem neu eine AbstractColumnToVirtualMigration mit, die genutzt werden kann, um eigene Felder in virtuelle Felder umzuwandeln.

Wenn du genauer wissen willst, wie virtuelle Felder funktionieren, dann lies dir diesen Beitrag im Handbuch durch: docs.contao.org.

Pro Newsarchiv legst du jetzt fest, welchen JSON-LD-Typ die Beiträge erhalten, zum Beispiel NewsArticle. Die Einstellung findest du in den Experteneinstellungen des Newsarchivs. Zur Verfügung stehen derzeit: NewsArticle, BlogPosting, Article. Damit ordnen Suchmaschinen deine Inhalte präziser ein, was sich positiv auf die Darstellung in den Suchergebnissen auswirken kann.

In den Seiteneinstellungen kannst du neu ein Seitenbild festlegen. Contao schreibt dieses Bild als primaryImageOfPage in die JSON-LD-Daten der Seite. So bestimmst du selbst, welches Bild Suchmaschinen der Seite zuordnen. Das Bild kann zudem nun auch bei der Contao-Suche genauso wie das Bild der News ausgegeben werden.

Übrigens lässt sich das Bild auch bei Bedarf im Frontend nutzen, etwa als Header-Bild. Dafür erweiterst du dein Twig-Template um die entsprechende Ausgabe. Zugreifen kannst du über contao.page.primaryImage. Damit kannst du dann das Bild im Template generieren:

{% set myimage = figure(contao.page.primaryImage|default, [1200, 500, 'crop']) %}

{% if myimage %}
    <div class="primary-image">
        {% with {figure: myimage} %}{{ block('figure_component') }}{% endwith %}
    </div>
{% endif %}

Inhaltselemente fügst du jetzt direkt in verschachtelte Elemente ein, ohne vorher die Kindansicht des Elements zu öffnen. So sparst du dir wieder ein paar Klicks im Backend.

Mit den neuen Twig-Filtern simple_token und simple_token_html werden Simple-Tokens nun korrekt in Twig-Templates ersetzt. Du kannst Simple-Tokens zum Beispiel beim Newsletter verwenden. Mehr dazu auch im Handbuch.

Bevor du updatest, wirf noch einen Blick auf die technischen Voraussetzungen von Contao 6.0:

• PHP: 8.4+
• Symfony: 7.4 und 8
• Monolog: 3
• Doctrine DBAL: 4.4+
• Doctrine ORM: 3.6

Wenn du jetzt direkt auf Contao 6.0 aktualisieren willst, dann solltest du ein paar wichtige Punkte beachten. Ein paar Hinweise habe ich bereits im Artikel erwähnt, hier noch einmal eine Zusammenfassung dessen, worauf du unbedingt achten musst.

1. Update von der letzten Contao 5.7.x aus. Die Migrationen der Datenbank bauen darauf auf. Aktualisiere also zuerst auf die aktuellste 5.7er-Version und wechsle erst danach auf 6.0.
2. Vorher contao:filesync ausführen. Der Filehash wechselt auf xxh128. Unter Contao 5.7 also unbedingt das Dateisystem synchronisieren. Nach dem Update dann direkt noch mal eine Synchronisierung durchführen.
3. Alle Templates auf Twig umstellen. Die HTML5-Templates funktionieren nach dem Update nicht mehr. Eine Umstellung auf Twig ist also Pflicht. Am besten erledigst du die Arbeit bereits in Ruhe noch unter Contao 5.7.
4. Die UPGRADE.md lesen. Sie listet alle Änderungen verbindlich auf und ist bei einer Major-Version Pflichtlektüre.

Wie immer gilt ausserdem: Erstelle vor dem Update ein vollständiges Backup und arbeite am besten in einer Kopie!

Eine vollständige, detaillierte Schritt-für-Schritt-Anleitung für das Update von Contao 5 auf Contao 6 veröffentlichen wir wieder mit der nächsten LTS-Version Contao 6.3.

Für die meisten Installationen empfehlen wir, noch zu warten. Besser ist es, zuerst deine Installationen sauber auf Contao 5.7 zu bringen und alle Templates auf Twig umzustellen. Damit erledigst du den grössten Teil der Vorarbeit und bleibst gleichzeitig auf einer LTS-Version mit Support bis 2030.

Dazu kommt: Bisher sind kaum Erweiterungen für Contao 6 freigegeben. Auch die Entwickler und Entwicklerinnen der Erweiterungen müssen ihre Pakete erst an das neue Encoding und an Twig anpassen. Wie immer kannst du mithelfen, indem du ggf. PRs erstellst oder das Ganze finanziell unterstützt.

Ebenfalls lesenswert ist auch der offizielle Release-Beitrag auf contao.org und sehenswert ist das YouTube-Video der Contao Academy.