Détection et validation des variables dans les templates Twig

Lorsqu'on travaille avec un fichier de template Twig, la plupart des variables sont documentées dans les commentaires du fichier template. Cependant, lorsque ce n’est pas le cas, ou lorsque des thèmes ou modules introduisent de nouvelles variables, nous avons besoin d’un moyen pour détecter toutes les variables disponibles dans le cadre du template. Twig fournit la fonction dump() pour détecter et vérifier les variables dans les fichiers de template.

La fonction dump() n’affichera pas de sortie si le mode debug n’est pas activé. Découvrez comment activer le debug Twig.

Une fois activé, la fonction dump() peut être utilisée pour afficher des informations sur une variable ou plusieurs variables dans le template.

Vérification d’une seule variable

Si votre template contient une variable title, ce qui suit affichera son contenu dans votre template :

{{ dump(title) }}

Détection de toutes les variables disponibles dans le template

Pour afficher toutes les variables disponibles ainsi que leur contenu dans le template, ajoutez ce qui suit dans le template (après activation du debug) :

{{ dump() }}

Pour afficher uniquement les clés des variables disponibles, utilisez :

{{ dump(_context|keys) }}

Tous les templates Twig ont accès à des variables globales supplémentaires :

• _self fait référence au template courant et contient des informations avancées sur le template, comme le nom de la classe compilée et les informations sur l’environnement Twig. _self est obsolète et supprimé depuis Twig 2.x.
• _context fait référence au contexte courant et contient toutes les variables passées au template, telles que celles envoyées depuis theme(), préparées par un preprocess ou définies dans le template. Utiliser {{ dump() }} sans variable est équivalent à {{ dump(_context) }}.
• _charset fait référence à l’encodage de caractères courant.

Attention avec dump()

Si vous souhaitez voir toutes les variables, mais que dump() provoque un dépassement de mémoire à cause de récursions ou autres, vous pouvez examiner _context pour voir toutes les clés :

<ol>
  {% for key, value in _context  %}
    <li>{{ key }}</li>
  {% endfor %}
</ol>

Puis utilisez une condition (par exemple, {% if loop.index == 2 %}) pour afficher uniquement la valeur nécessaire.

Plus d’informations

Voir la documentation de la fonction dump Twig pour en savoir plus sur dump().

Debugging avec xdebug

La méthode la plus couramment recommandée pour le débogage est d’utiliser un IDE avec le plugin xdebug.

La configuration la plus simple consiste à utiliser PHPStorm (commercial) avec xdebug. Microsoft VSCode est un IDE gratuit et open source avec des plugins offrant les mêmes fonctionnalités, sans nécessiter d’achat de logiciel commercial.

Utiliser xdebug vous permet de suivre le processus, de visualiser le contenu des variables et de le faire de manière à lever le voile sur ce qui se passe sous le capot, tout en évitant les boucles infinies qui peuvent survenir avec dump ou kint.

Un petit module utile nommé twig_xdebug peut aider à afficher les variables disponibles dans xdebug.

Debugging avec kint

La fonction dump() dans Twig affiche souvent beaucoup de texte sur la page web, ce qui rend difficile de trouver l’aiguille dans la botte de foin.

L’alternative à dump() est kint, un outil de debug PHP. La fonction kint() fonctionne exactement comme dump(), mais fournit une interface extensible et exploratoire pour les variables qu’elle affiche.

Le projet devel fournit le module devel kint, qui permet aux développeurs d’utiliser kint() au lieu de dump().

1. Téléchargez le module devel.
2. Installez le module « devel kint ».
3. Comme pour dump, kint() n’affichera rien si le mode debug n’est pas activé. Découvrez comment activer le debug Twig.
4. Dans vos fichiers .twig, utilisez kint() pour vérifier les variables, de la même manière que dump().
5. Si besoin, installez et activez également le module Search Kint pour rechercher dans la liste des variables imbriquées.

Politique de liste blanche pour méthodes et classes

Lorsqu’on travaille avec des objets, on place en liste blanche un certain ensemble de méthodes getter/setter ou d’objets via la classe TwigSandboxPolicy. Cela empêche l’appel de méthodes aléatoires dans vos templates. Par exemple : {{ node.delete }} sur un objet node pourrait supprimer ce nœud si aucune liste blanche n’est en place. Vous pouvez étendre cette liste blanche en ajoutant dans votre fichier settings.php ce qui suit :

$settings['twig_sandbox_whitelisted_methods'] = [
  'id',
  'label',
  'bundle',
  'get',
  '__toString',
  'toString',
  'referencedEntities',
];

Où referencedEntities est une méthode que vous souhaitez utiliser dans votre template.