Debugging van gecompileerde Twig-sjablonen

Hoe Twig normaal werkt

Standaard compileert de Twig-themingengine sjablonen naar PHP-code en slaat de gecompileerde code op in het geheugen. De gecompileerde code is niet handig voor ontwikkeling, omdat wijzigingen in Twig-sjablonen niet onmiddellijk zichtbaar worden op je Drupal-site.

Nadat Twig bepaalde markup heeft gerenderd, komt er nog een extra cachelaag vanuit de Render API. Deze cachet de markup die Twig heeft aangemaakt, zodat Twig helemaal niet betrokken is bij volgende paginaverzoeken. Hierdoor worden Twig-debuginstellingen uiteindelijk genegeerd.

Caches kunnen worden geleegd via de cache-clear interface in Drupal, maar voor ontwikkeling is het makkelijker om de instellingen van Drupal zo te wijzigen dat noch Twig, noch de Render API iets cachet.

Twig en Render API configureren voor debugging

De twee lagen, Twig en Render API, moeten afzonderlijk ingesteld worden voor debugging:

1. De Twig-engine biedt opties om debugging in te stellen, automatische hercompilatie van sjablonen en caching van gecompileerde sjablonen in het bestandssysteem. Dit stel je in in services.yml.
2. De caching van de Render API kun je instellen in settings.php van je site.

We bekijken beide stappen hieronder in detail.

1. Twig configureren voor debugging

Je kunt hiervoor de Drupal Console gebruiken of de instellingen handmatig wijzigen.

Debug inschakelen met Drupal Console

Installeer eerst de Drupal Console. Voer vervolgens uit:

drupal site:mode dev

Let op dat dit meerdere instellingen wijzigt, waaronder de volgende waarde in sites/default/services.yml:

twig.config: { debug: true }

Je zou iets als dit moeten zien:

Debug handmatig inschakelen

1. Zoek het bestand services.yml van je site, meestal sites/default/services.yml.
2. Als services.yml nog niet bestaat, kopieer default.services.yml en hernoem dit naar services.yml.
3. Bewerk services.yml en stel een of meerdere van onderstaande debugopties in:
    - Twig debug opties
    - Twig auto_reload
    - Twig cache
4. Leeg de cache.

Zoek naar twig.config in je services.yml en pas deze aan. Bijvoorbeeld:

parameters:
  twig.config:
    debug: true

Debugopties van Twig

Let op: zet deze nooit aan in productie! Deze drie opties moeten standaard uitgeschakeld blijven in productieomgevingen.

- debug (standaard: false)

Wanneer debug: true is ingesteld:

• De markup van elk Twig-sjabloon wordt omgeven door HTML-commentaar met informatie over thema hooks en sjabloonnaamsuggesties.
• Deze debugmarkup kan automatische tests breken die exact HTML vergelijken. Voor tests moet twig_debug dus false zijn.
• De dump()-functie kan gebruikt worden in Twig-sjablonen om variabelen te inspecteren.
• Sjablonen worden automatisch hergecompileerd bij wijzigingen (zie auto_reload hieronder).

- auto_reload (standaard: null, afgeleid van debug)

Wanneer auto_reload: true is ingesteld:

• Worden Twig-sjablonen automatisch hergecompileerd telkens wanneer de broncode wijzigt. Als geen waarde wordt opgegeven, volgt deze optie de waarde van debug.
• Als je geen auto_reload wilt en ook geen debug, hoef je deze optie niet te gebruiken.

- cache (standaard: true, maar overschreven door debug)

Wanneer cache: false is ingesteld:

• Schakel dit alleen uit als dat echt nodig is. Bij debug of auto_reload belemmert caching niet je workflow. Het volledig uitschakelen van Twig-cache maakt ontwikkelen trager, omdat alle sjablonen telkens opnieuw gecompileerd worden, ongeacht of ze gewijzigd zijn.
• Standaard worden Twig-sjablonen gecompileerd en opgeslagen in het bestandssysteem. Bij cache: false wordt telkens opnieuw gecompileerd. Meestal volstaat het om enkel auto_reload te gebruiken.

2. Render API-cache configureren voor debugging

Standaard cachet Drupal gerenderde output van blokken en entiteiten voor snellere paginalading. Dit betekent dat wijzigingen in Twig-sjablonen niet meteen zichtbaar worden. Door de rendercache uit te schakelen, wordt dit opgelost.

Om de rendercache uit te schakelen, voeg de volgende regels toe:

• in settings.php, maar niet op productie
• of in settings.local.php (na het deblokkeren van de verwijzingen in je settings.php)

Regels:

$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';

Misschien staan deze regels al in je settings.php, maar dan uitgecommentarieerd. In dat geval hoef je ze alleen maar te decommentariëren (en vergeet niet ze later weer uit te schakelen!).

Klaar!

Met deze Twig- en Render-instellingen kun je alle caches legen (via Drush of via Configuratie → Prestaties en dan op Alle caches leegmaken klikken).

Ververs daarna de pagina die je test: je zou Twig-debuginformatie in de bron moeten zien, en sjabloonupdates worden meteen doorgevoerd.