Отdebuggen van Twig-sjablonen
De Twig-template-engine biedt een debugtool.
De implementatie van Drupal 8 voegt ook een extra hulpmiddel toe dat je helpt om het sjabloon te vinden dat de markup genereert.
Waarschuwing: het inschakelen van Twig-debug kan sommige delen van de site breken, vooral Views. Zie dit issue.
Debug inschakelen
Je schakelt Twig-debug in via sites/default/services.yml.
Stel de debug-variabele in op true. En maak de cache leeg.
parameters:
twig.config:
debug: true
- Als services.yml nog niet bestaat; kopieer default.services.yml naar services.yml.
- Als Drupal al geïnstalleerd is, moet je mogelijk tijdelijk de schrijfrechten op de map sites/default aanpassen.
- Hoe maprechten wijzigen
- Nadat services.yml is aangemaakt en bewerkt, zet de rechten terug om de map sites/default te beveiligen.
Debug controleren
Als je Firebug gebruikt (in Firefox), zorg ervoor dat "Toon opmerkingen" ("Show Comments") ingeschakeld is, of bekijk de broncode van de pagina direct:
Automatisch herladen
Twig-sjablonen worden voor performance naar PHP-klassen gecompileerd en op schijf opgeslagen, maar dit betekent dat je sjablonen standaard niet worden vernieuwd bij wijzigingen. Zet dit niet aan in productie.
Om sjablonen handmatig opnieuw te bouwen, voer drush cr uit. Om tijd te besparen tijdens ontwikkeling kun je automatisch herladen inschakelen door twig.config.auto_reload: true in services.yml te zetten (standaard is auto_reload ingeschakeld als twig.config.debug: true staat).
Voor meer informatie zie https://drupal.org/node/1903374.
Variabelen bekijken
De beste manier om variabelen te bekijken is Xdebug te gebruiken.
Als je de andere niet-Xdebug-methoden hieronder gebruikt, krijg je veel recursieve render-acties die kunnen leiden tot pagina’s vol informatie die je waarschijnlijk niet nodig hebt.
De meest aanbevolen aanpak is PHPStorm met Xdebug, omdat dit het makkelijkst te configureren is. Maar bijna elke IDE heeft een Xdebug-plugin. Als je een gratis en lichte editor zoekt, is VSCode van Microsoft een open-source optie met plugins voor PHP en Xdebug.
Xdebug configureren
Het configureren van Xdebug kan lastig zijn, dus lees de instructies van de plugin in je IDE en bekijk de Xdebug-documentatie om het correct aan te sluiten. Alleen maar instructies en foutmeldingen online lezen helpt niet als je je richt op het verkeerde type omgeving (bijvoorbeeld: als Xdebug draait in Vagrant, Virtualbox of Docker, heb je mogelijk "remote" connectie-instructies nodig: https://xdebug.org/docs/remote).
Drupal.org biedt handleidingen voor Xdebug met verschillende editors, zie: https://www.drupal.org/docs/develop/development-tools/xdebug-debugger
Wanneer je met Xdebug werkt:
Er zijn drie manieren om breakpoints in je Twig-sjablonen te plaatsen zodat je IDE variabelen en PHP-omgevingstoestand kan tonen:
- Gebruik de nieuwe Twig-debugfunctie in PHPStorm (blog, docs). Drupal-modules zijn niet nodig.
- met de Devel-module
{{ devel_breakpoint() }}
- met de Twig Xdebug-module
{{ breakpoint() }}
Als je Xdebug niet kunt installeren ...
... lees verder en succes, mijn vriend.
{{ dump() }}
{{ dump(variable_name) }}
Lijst van beschikbare variabelen (op topniveau):
{{ dump(_context|keys) }}
Als je de Devel kint-submodule hebt (te installeren via require-dev met Composer: composer require --dev drupal/devel 1.0-alpha1 en activeren met Drush: drush -y en kint), krijg je een nette weergave van de beschikbare variabelen in Twig via:
{{ kint() }}
Er is een grote kans dat kint je browser vast laat lopen als de rendering te groot wordt. In dat geval kunnen de volgende modules beter werken:
Of je kunt de Vardumper Twig-module gebruiken, die Vardumper in Twig integreert. Hiermee kun je de variabelen netjes bekijken:
{{ dump() }}
{{ dump(variable_name) }}
{{ vardumper() }}
{{ vardumper(variable_name) }}
... maar besef ook dat een uurtje besteden om Xdebug goed te laten werken je leven veel makkelijker maakt, omdat je dan precies weet welke variabelen je kunt gebruiken.
Als je de verkeerde aanpak gebruikt ...
Als je veel programmeert in Twig, vraag je dan af of je echt complexe logica daar moet uitvoeren. Bijvoorbeeld: misschien is het beter om een bestaand plugin-bestand van een field formatter te kopiëren naar een custom module (met dezelfde mapstructuur), de annotatie (commentaarblok met de plugin-naam) en de PHP/HTML aan te passen zodat het doet wat jij wil. Plugins in Drupal 8 zijn losse bestanden in specifieke mappen en daarmee erg eenvoudig te gebruiken.
Meer debug-opties vind je in de volgende sectie.