Débogage des templates Twig compilés

Comment fonctionne Twig habituellement

Par défaut, le moteur de thème Twig compile les templates en code PHP et stocke ce code compilé en mémoire. Le code compilé n’est pas adapté au développement car les modifications dans les templates Twig ne sont pas immédiatement reflétées sur votre site Drupal.

Après que Twig a généré un certain balisage, l’API Render applique un autre niveau de cache. Ce cache conserve le balisage généré par Twig, de sorte que Twig n’intervient plus lors des requêtes suivantes, ce qui fait que les options de débogage Twig sont finalement ignorées.

Les caches peuvent être vidés via l’interface de Drupal, mais pour un développement plus efficace, il est préférable de configurer Drupal pour que ni Twig ni l’API Render ne mettent quoi que ce soit en cache.

Configurer Twig et l’API Render pour le débogage

Les deux niveaux, Twig et Render API, doivent être configurés séparément pour le débogage :

1. Le moteur Twig offre des options pour activer le débogage, le rechargement automatique (recompilation) des templates et la gestion du cache des templates compilés sur le système de fichiers. Cela se configure dans le fichier services.yml de votre site.
2. Le cache de l’API Render se configure dans le fichier settings.php de votre site.

Nous allons détailler ces deux étapes ci-dessous.

1. Configuration de Twig pour le débogage

Vous pouvez utiliser Drupal Console ou modifier manuellement les fichiers.

Activer le débogage via Drupal Console

Installez d’abord Drupal Console puis lancez :

drupal site:mode dev

Cette commande modifie plusieurs réglages, dont la ligne suivante dans votre sites/default/services.yml :

twig.config: { debug: true }

Vous devriez voir quelque chose de similaire à ceci :

Activer le débogage manuellement

1. Trouvez le fichier services.yml dans votre site (probablement dans sites/default/services.yml).
2. Si services.yml n’existe pas, copiez default.services.yml et renommez-le en services.yml.
3. Éditez services.yml et activez un ou plusieurs paramètres de débogage Twig listés ci-dessous :
• Options de débogage Twig
• Auto-rechargement de Twig
• Cache Twig
4. Videz le cache.

Trouvez la clé twig.config dans services.yml et modifiez-la ainsi :

parameters:
  twig.config:
    debug: true

Options de débogage Twig

Attention : ne les activez pas en production ! Ces trois paramètres doivent rester désactivés (par défaut) sur les environnements de production.

- debug (par défaut : false)

Si debug est à true :

• Le balisage de chaque template Twig est entouré de commentaires HTML indiquant des informations sur les templates (comme le nom du fichier).
• Cette sortie de débogage casse les tests automatiques qui vérifient le HTML rendu. Pour les tests, twig_debug doit être désactivé.
• La fonction dump() est disponible dans Twig pour afficher les variables.
• Les templates Twig se recompilent automatiquement à chaque modification (voir auto_reload ci-dessous).

- auto_reload (par défaut : null, dépend de debug)

Si auto_reload est true :

• Les templates Twig se recompilent automatiquement à chaque modification.
• Si vous ne voulez pas auto_reload et ne faites pas de débogage, ce paramètre peut rester inchangé.

- cache (par défaut : true, mais remplacé par debug)

Si cache est false :

• Ne désactivez pas le cache Twig sauf cas spécifique. Quand debug ou auto_reload sont activés, le cache ne gêne pas.
• Désactiver le cache ralentit le développement car chaque template est recompilé à chaque utilisation, même sans modification.
• Par défaut, Twig compile et stocke les templates dans le système de fichiers pour accélérer le rendu. Désactiver le cache force la recompilation à chaque fois.

2. Configurer le cache Render API pour le débogage

Drupal met par défaut en cache le rendu des blocs et entités pour accélérer le chargement. Cela signifie que les changements dans les templates Twig ne sont pas visibles immédiatement. Désactiver ce cache permet que les changements soient pris en compte sans délai.

Pour désactiver le cache Render, ajoutez dans :

• settings.php (évitez de le faire sur un site en production)
• ou settings.local.php (après avoir décommenté les lignes à la fin de settings.php)

Les lignes à ajouter :

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

Ces lignes peuvent déjà être présentes dans settings.php, mais commentées. Dans ce cas, il suffit de les décommenter (pensez à les remettre en commentaire après).

Vous y êtes !

Avec la configuration de Twig et de Render API, videz tous les caches via Drush ou par l’interface Configuration → Performance → Vider tous les caches.

Enfin, rechargez la page à tester : vous devez voir les informations de débogage Twig dans le code source, et les modifications des templates Twig doivent apparaître immédiatement lors du rechargement de la page.