Debugging kompilierter Twig-Templates

Wie Twig normalerweise funktioniert

Standardmäßig kompiliert die Twig-Theme-Engine Templates in PHP-Code und speichert den kompilierten Code im Speicher. Der kompilierte Code ist für die Entwicklung ungeeignet, da Änderungen an Twig-Templates nicht sofort auf Ihrer Drupal-Seite sichtbar werden.

Nachdem Twig ein Markup erzeugt hat, gibt es im Render-API eine weitere Caching-Ebene. Diese nimmt das von Twig erstellte Markup und cached es so, dass Twig bei folgenden Seitenaufrufen gar nicht mehr beteiligt ist. Daher werden Twig-Debug-Optionen letztlich ignoriert.

Caches können über die Cache-Leerungs-Oberfläche in Drupal gelöscht werden, aber für die weitere Entwicklung ist es einfacher, Drupal so zu konfigurieren, dass weder Twig noch das Render-API überhaupt etwas cachen.

Twig- und Render-API-Einstellungen für Debugging konfigurieren

Die zwei Ebenen Twig und Render-API müssen separat für Debugging-Zwecke konfiguriert werden:

1. Die Twig-Engine bietet Optionen für Debugging, automatische Neuladung (Re-Kompilierung) der Templates und Caching des kompilierten Codes im Dateisystem. Dies wird in der services.yml Ihrer Seite eingestellt.
2. Das Caching des Render-API kann in der settings.php Ihrer Seite konfiguriert werden.

Diese beiden Schritte werden im Folgenden näher erläutert.

1. Twig für Debugging konfigurieren

Sie können die Drupal-Konsole dafür nutzen oder die Änderungen manuell vornehmen.

Debugging mit Drupal Console aktivieren

Zuerst Drupal Console installieren. Dann ausführen:

drupal site:mode dev 

Beachten Sie, dass dies viele Einstellungen ändert, aber unter anderem den Wert in sites/default/services.yml wie folgt setzt:

twig.config: { debug: true } 

Sie sollten eine Ausgabe ähnlich der folgenden sehen:

Debugging manuell aktivieren

1. Suchen Sie die services.yml-Datei Ihrer Seite, vermutlich unter sites/default/services.yml
2. Falls services.yml noch nicht existiert, kopieren Sie default.services.yml und benennen sie in services.yml um.
3. Bearbeiten Sie die services.yml und aktivieren Sie einen oder mehrere der folgenden Debug-Parameter:
           - Twig Debug-Optionen
           - Twig mit automatischer Neuladung
           - Twig Cache
4. Cache leeren.

Suchen Sie den Abschnitt twig.config in Ihrer services.yml und nehmen Sie folgende Änderung vor. Beispiel:

parameters:
  twig.config:
    debug: true 

Debug-Optionen im Detail

Hinweis: Nicht in Produktionsumgebungen aktivieren! Diese drei Parameter sollten in produktiven Umgebungen nicht gesetzt sein (Standard).

- debug (Standard: false)

Wenn debug: true gesetzt ist:

• Wird das Markup jedes Twig-Templates mit HTML-Kommentaren umgeben, die Informationen zu den Themes und z. B. Template-Dateinamen-Hinweise enthalten.
• Diese Debug-Markups können automatisierte Tests stören, die direkt den gerenderten HTML-Code prüfen. Beim Ausführen automatisierter Tests sollte twig_debug auf FALSE gesetzt sein.
• Die Funktion dump() kann in Twig-Templates verwendet werden, um Informationen über Template-Variablen auszugeben.
• Twig-Templates werden automatisch neu kompiliert, wenn sich der Quellcode ändert (siehe auto_reload unten).

- auto_reload (Standard: null, abhängig von debug)

Wenn auto_reload: true gesetzt ist:

• Werden Twig-Templates bei jeder Quellcode-Änderung automatisch neu kompiliert. Wenn kein eigener Wert für twig_auto_reload gesetzt ist, wird der Wert von twig_debug übernommen.
• Wenn Sie keine automatische Neuladung wollen und kein Debugging, brauchen Sie diesen Parameter nicht zu ändern. Aktivieren Sie einfach debug oben.

- cache (Standard: true, wird durch Debugging überschrieben)

Wenn cache: false gesetzt ist:

• Deaktivieren Sie den Twig-Cache nur bei konkretem Bedarf. Wenn Sie Twig-Debugging (oder nur auto_reload) aktivieren, behindert der Cache Sie nicht. Das Deaktivieren des Twig-Caches verlangsamt die Entwicklung, da jedes Template bei jedem Aufruf kompiliert werden muss, egal ob es geändert wurde oder nicht. Zudem können Sie kompilierten Twig-Code (PHP-Klassen, standardmäßig in sites/default/files/php/twig) nicht leicht ansehen oder debuggen, wenn dieser nicht auf der Festplatte gespeichert wird.
• Standardmäßig werden Twig-Templates kompiliert und zur Performance-Steigerung im Dateisystem gespeichert. Wird der Cache deaktiviert, kompiliert Twig Templates bei jeder Nutzung neu. In den meisten Fällen sollte twig_auto_reload aktiviert und der Twig-Cache nicht deaktiviert werden.

2. Render-API Cache für Debugging konfigurieren

Standardmäßig cached Drupal jegliches Rendering von Blöcken und Entities, um das Nachladen von Seiten zu beschleunigen. Änderungen an Twig-Templates werden so nicht sofort wirksam. Die Render-Cache-Konfiguration auf Null-Cache zu setzen, deaktiviert dies effektiv.

Um das Render-Caching zu deaktivieren, fügen Sie folgende Zeilen hinzu:

• in settings.php (achten Sie darauf, dies nicht auf Produktionsseiten zu tun)
• oder in settings.local.php, nachdem Sie die entsprechenden Zeilen in settings.php auskommentiert haben.

Diese Zeilen:

$settings['container_yamls'][] = DRUPAL_ROOT . '/sites/development.services.yml';
$settings['cache']['bins']['render'] = 'cache.backend.null';
$settings['cache']['bins']['dynamic_page_cache'] = 'cache.backend.null'; 

Eventuell sind diese Zeilen bereits in Ihrer settings.php-Datei vorhanden, aber auskommentiert; falls ja, heben Sie die Kommentierung auf (denken Sie daran, sie später wieder auszukommentieren!).

Fertig!

Nachdem Sie Twig-API und Render-API konfiguriert haben, leeren Sie alle Caches: Sie können dazu Drush verwenden oder unter Konfiguration → Leistung die Schaltfläche „Alle Caches leeren“ drücken.

Aktualisieren Sie abschließend die Seite, die Sie prüfen möchten: Sie sollten Twig-Debug-Informationen im Seitenquelltext sehen, und Änderungen an Twig-Templates sollten sofort auf aktualisierten Seiten sichtbar sein.