Templates Debuggen unter Twig

Debugging aktivieren

Um Informationen und Variablen bei der Entwicklung von Twig Templates ausgeben zu können, muss in Drupal der Debug Modus aktiviert werden. Dies kann u.a. in der services.yml vorgenommen werden:

# sites/default/services.yml

parameters:
  twig.config:
    debug: true

Hier muss die Zeile debug: false (Zeile 21) in debug: true geändert werden. Nachdem man den Cache geleert hat (Konfiguration → Entwicklung → Leistung), wird Twig im Debug-Modus ausgeführt.

In der services.yml kann auch das Caching von Twig konfiguriert bzw. deaktiviert werden. Dazu einfach die beiden Keys auto_reload (auf TRUE) und cache (auf FALSE) verändern. Das Caching zu deaktivieren ist besondern während der Entwicklung von Themes hilfreich, da ansonsten Dateiänderungen immer erst nach einem manuellen Leeren des Caches angewendet werden würden.

Durch die Aktivierung des Debug-Modus von Twig werden im HTML-Quelltext auch viele zusätzliche und hilfreiche HTML-Kommentare ausgegeben. Dadurch kann man schnell erkennen, welche Template-Datei für eine bestimmte Ausgabe verwendet wurde.

  <!-- THEME DEBUG -->
  <!-- THEME HOOK: 'page' -->
  <!-- FILE NAME SUGGESTIONS:
     * page--front.html.twig
     * page--node.html.twig
     x page.html.twig
  -->
  <!-- BEGIN OUTPUT from 'core/themes/bartik/templates/page.html.twig' -->

Wie man an den sehr aussagekräftigen HTML-Kommentaren erkennen kann, sollte man das Twig Debugging niemals in einer Produktivumgebung (öffentlich erreichbare Website) aktiviert haben.

Debuggen mit Twig "dump()"

Mit der dump() Funktion von Twig (sie ist vergleichbar mit der var_dump() Funktion in PHP), kann der Inhalt von Variablen analysiert werden. Der leere Funktionsaufruf gibt alle in dieser Template-Datei verwendbaren Variablen aus.

{{ dump() }}

Ausgabe aller Template Variables in node.html.twig

Möchte man eine bestimmte Variable analysieren, kann diese als Parameter der Funktion übergeben werden:

{{ dump(view_mode)

Ausgabe der Variable view_mode im node.html.twig Template

Besseres Debugging mit Kint

Die Ausgaben von dump() können sehr umfangreich und wenig übersichtlich werden (z.B. wenn man sich alle Variablen des page.html.twig ausgeben lassen möchte). Eine übersichtlichere Ausgabe produziert „Kint“.

Kint ist nicht im Drupal 8 Core enthalten. Das Tool ist im BROKEN-LINK:Devel bzw. Devel Kint Modul LINK-BROKEN enthalten. Dieses muss erst installiert und aktiviert werden, damit kint() genutzt werden kann.

{{ kint() }}

Auch hier kann der Funktion wieder ein Parameter übergeben werden, um eine Variable genauer und gez ielter analysieren zu können.

Besonderheit: "#" und "-" in Variablen-Namen

Allerdings lassen sich so keine Variablen ausgeben, die ein Raute-Zeichen (#) oder Bindestrich (-) enthalten.

Der Code {{ dump(elements.#theme) }} produziert die Fehlermeldung:

Twig_Error_Syntax: Unexpected character "#" in ... in Twig_Lexer->lexeExpression() ...

Solche Variablen lassen sich wie folgt debuggen:

{{ dump(elements['#theme']) }}

Xdebug Breakpoint

Es ist auch möglich in Twig Templates einen Breakpoint zu definieren, um an dieser die Ausführung des Codes zu pausieren und die vorhanden Variablen und Umgebungsinformationen zu analysieren.

Wenn PHPStorm als Editor genutzt wird, kann ein Twig Template direkt analysiert werden: PHPStorm Dokumentation

Alternativ bringt das Devel Modul eine Unterstützung mit: {{ devel_breakpoint() }}
oder das Twig Xdebug Modul: {{ breakpoint() }}

drupal8, theming, debugging