Débogage des templates Twig

Le moteur de template Twig offre un outil de débogage.

L’implémentation Drupal 8 ajoute également un outil supplémentaire permettant de trouver le template qui génère un rendu.

Avertissement : activer le débogage Twig peut casser certaines parties du site, en particulier Views. Voir ce problème.

Activer le débogage

Vous activez le débogage Twig dans sites/default/services.yml.

Réglez la variable debug à true. Puis videz le cache.

parameters:
  twig.config:
    debug: true

• Si le fichier services.yml n’existe pas, copiez default.services.yml en services.yml.
• Si Drupal est déjà installé, vous devrez peut-être temporairement modifier les permissions du dossier sites/default pour permettre l’écriture.
• Comment modifier les permissions d’un dossier
• Une fois services.yml créé et édité, remettez les permissions en place pour verrouiller le dossier sites/default.

Vérifier le débogage

Si vous utilisez Firebug (dans Firefox), assurez-vous que « Afficher les commentaires » est activé, ou consultez directement le code source de la page :

Rechargement automatique

Les templates Twig sont compilés en classes PHP sur disque pour améliorer les performances, ce qui signifie que par défaut vos templates ne se mettent pas à jour automatiquement lors de modifications. Ne pas activer ceci en production.

Pour recompiler manuellement les templates, lancez drush cr. Pour gagner du temps en développement, activez le rechargement automatique en définissant twig.config.auto_reload: true dans services.yml (par défaut, il est activé si twig.config.debug: true).

Plus d’informations : https://drupal.org/node/1903374.

Afficher les variables

Le meilleur moyen pour inspecter les variables est d’utiliser Xdebug.

Si vous utilisez d’autres méthodes sans Xdebug, vous risquez d’obtenir beaucoup d’appels récursifs de rendu qui produiront des pages d’informations peu exploitables.

L’approche la plus recommandée est d’utiliser PHPStorm avec Xdebug, car sa configuration est la plus simple. Presque toutes les IDE disposent d’un plugin Xdebug. Si vous souhaitez un éditeur gratuit et léger, VSCode de Microsoft est une option open source avec plugins pour PHP et Xdebug.

Configurer Xdebug

La configuration de Xdebug peut être complexe. Lisez attentivement les instructions du plugin de votre IDE et la documentation Xdebug. Lire des tutos généraux peut être inutile si votre environnement est spécifique (ex. Xdebug dans Vagrant, VirtualBox ou Docker nécessite une configuration de connexion distante : https://xdebug.org/docs/remote).

Drupal.org propose des guides pour Xdebug sur différents éditeurs ici : https://www.drupal.org/docs/develop/development-tools/xdebug-debugger

Quand utiliser Xdebug :

Il existe trois façons de placer des points d’arrêt dans vos templates Twig afin que votre IDE affiche les variables et autres informations sur l’état de l’environnement PHP :

• Utiliser la nouvelle fonction de débogage Twig dans PHPStorm (blog, docs). Aucun module Drupal nécessaire.
• Avec le module Devel :

{{ devel_breakpoint() }}

• Avec le module Twig Xdebug :

{{ breakpoint() }}

Si vous ne pouvez pas installer Xdebug ...

... lisez la suite et bonne chance, mon ami.

{{ dump() }}

{{ dump(variable_name) }}

Liste des variables disponibles (au niveau supérieur) :

{{ dump(_context|keys) }}

Si vous avez le sous-module Devel kint (installation via require-dev avec Composer en tapant composer require --dev drupal/devel 1.0-alpha1 et activation avec Drush via drush -y en kint), vous pouvez obtenir un affichage agréable des variables disponibles avec :

{{ kint() }}

Il est très probable que kint bloque votre navigateur si le rendu devient trop volumineux. Dans ce cas, les modules suivants peuvent mieux convenir :

• https://www.drupal.org/project/vardumper

Ou vous pouvez utiliser le module Twig Vardumper, qui fournit Vardumper pour Twig. Vous pouvez afficher joliment les variables Twig disponibles :

{{ dump() }}
{{ dump(variable_name) }}

{{ vardumper() }}
{{ vardumper(variable_name) }}

• https://www.drupal.org/project/twig_vardumper

... mais considérez aussi qu’investir une à deux heures à faire fonctionner Xdebug facilitera grandement votre travail en vous permettant de savoir quelles variables vous pouvez utiliser.

Si vous utilisez une mauvaise approche ...

Si vous faites beaucoup de programmation dans le template, demandez-vous si vous ne devriez pas plutôt faire cela ailleurs. Par exemple : il peut être préférable de copier un fichier plugin de formatter de champ existant dans un module personnalisé (en gardant la même structure de dossiers) et modifier simplement l’annotation (commentaire d’introduction aussi appelé nom du plugin) ainsi que la configuration PHP/HTML pour faire ce que vous souhaitez. Les plugins dans Drupal 8 sont juste des fichiers séparés dans des dossiers spécifiques et sont très faciles à manipuler.

Plus d’options de débogage sont disponibles dans la section suivante.