Twig in Contao 5: Fünf Learnings aus der Praxis

Twig ist die Template-Engine, die in Contao nach und nach die bisherigen PHP-Templates ersetzt. Hier sind fünf Dinge, die wir bei der intensiven Arbeit damit gelernt haben.

Wenn du noch nicht mit Twig gearbeitet hast, empfehlen wir dir das Video von Maren von der Contao-Konferenz. Sie geht auf die Basics von Twig ein und zeigt anhand einfacher Beispiele, wie Twig in Contao zum Einsatz kommt. Alternativ kannst du dir die Doku Twig-Templates für Contao 5 ansehen.

1. Twig-Templates für Frontend-Module

Alle Inhaltselemente sind mittlerweile als Twig-Templates verfügbar, sodass du sie relativ einfach an deine Bedürfnisse anpassen kannst.

Anders sieht es bei den Frontend-Modulen aus, zum Beispiel Navigationen oder Newslisten und -lesern: Die sind (Stand: Contao 5.3) noch nicht in die Twig-Syntax überführt. Du kannst aber auch für diese Bereiche eigene Twig-Templates anlegen. Dafür musst du zunächst die korrekte Benennung beachten (aus .html5 wird .html.twig) und dann alles, was PHP war, in Twig übersetzen.

Beim Übersetzen der alten Template-Struktur in Twig helfen KI-Tools: zum Beispiel Codeium, eine Alternative zu GitHubs Copilot, oder ChatGPT (teilweise sogar mit besseren Ergebnissen). Ein Befehl wie „Übersetze das in Twig" reicht normalerweise aus. Das klappt zwar nicht zu 100 % — oft musst du händisch ein paar Variablen ändern — erspart dir aber eine Menge Schreibarbeit.

2. Tschüss, Vergleichsansicht

Bei Updates von einer LTS-Version auf die nächste war die Vergleichsansicht oft ein erster Anhaltspunkt, um herauszufinden, was sich an einem Template geändert hat. Für Twig-Templates gibt es diese Vergleichsansicht nicht mehr.

Stattdessen lohnt es sich, ein Lesezeichen auf die Twig-Templates im Contao-Git-Repository zu setzen und Änderungen dort nachzuvollziehen. Da die Twig-Templates immer mal wieder optimiert werden, achte unbedingt darauf, den Branch deiner installierten Version auszuwählen (z. B. 5.3): Der 5.x-Branch enthält bereits Neuerungen, die erst in neueren Contao-Versionen zur Verfügung stehen.

3. Parameter-Dumping

Wenn du Templates erstellst oder bestehende anpasst, wirst du früher oder später die Template-Parameter ausgeben wollen. Das geht in Twig mit {{ dump() }} — aber zwei Dinge solltest du wissen:

1. Die Parameter werden nur ausgegeben, wenn du dich im DEV-Mode befindest.
2. Die Dump-Funktion erzeugt einen kritischen Fehler, wenn du dich nicht im DEV-Mode befindest.

Und das ist auch gut so: Die Dump-Funktion gibt auch sensible Daten aus, die besser nicht öffentlich sein sollten. Und der Fehler sorgt dafür, dass du eine vergessene Dump-Anweisung nicht versehentlich mit live nimmst.

4. Eigene Varianten anlegen

Was an Twig besonders gefällt: Einzelne Blöcke lassen sich überschreiben, während der Rest vererbt wird. In Contao wurden für alle möglichen Fälle Blöcke angelegt, sodass sich Texte oder Attribute relativ leicht ergänzen lassen.

Es wird aber immer Fälle geben, die sich mit der vorhandenen Block-Struktur nicht abdecken lassen. Ein Beispiel aus einem Projekt: Die Überschrift des Text-Elements sollte in einem gemeinsamen Container mit dem Text stehen — nur hat die Überschrift einen festen Platz im _base.html.twig-Element.

Der erste Lösungsversuch: den Inhalt von _base ins eigene Text-Template kopieren und die Ausgabe der Headline dort neu bestimmen. Es geht aber besser: In einer neuen Variante _base/no_headline.html.twig fällt die Überschrift weg, sodass sie sich im eigenen Text-Template frei platzieren lässt. Und sollte sich irgendwann etwas in der _base.html.twig ändern, lassen sich die Änderungen leichter erkennen und im eigenen Template nachziehen.

5. Die Grenzen von Twig

„Das Schöne" an der alten Template-Struktur war, dass sich PHP beliebig mit HTML mischen ließ — was gleichzeitig ein potentielles Sicherheitsproblem war. Mit Twig ist es nicht mehr so leicht möglich, sich Code aus Foren, Slack usw. zusammenzusuchen und Templates nach Belieben anzupassen. Eigentlich gut.

Wenn du an die Grenzen von Twig stößt, weil du die Ausgabe mit Twig-Filtern und -Funktionen nicht weiter angepasst bekommst, wird es unter Umständen Zeit, eigene Inhaltselemente zu erstellen oder Twig durch eigene Funktionen zu erweitern. Ein Beispiel: Um für ein Akkordeon bei Bedarf JSON-LD-Daten zu erzeugen, kommt entweder ein neues Inhaltselement oder eine eigene Twig-Extension infrage.