Instructions pour la conversion de Drupal Twig (de tpl.php à html.twig)

05/07/2025, by Ivan

Ce document a été utilisé pendant la majeure partie du processus de conversion Twig pour Drupal 8 et peut également vous être utile pour mettre à jour vos propres thèmes et modules afin d’utiliser le moteur de templates Twig dans Drupal 8.

Note : tout le travail avec Twig est désormais effectué dans la file des problèmes du cœur Drupal. Utilisez uniquement le sandbox de conversion Twig pour retrouver les templates et fonctions déjà convertis.

Étapes pour les principaux contributeurs :

Trouvez les problèmes principaux pour publier et consulter les correctifs.
Ne pas appliquer de patchs au sandbox.
Ne pas créer de patchs pour le sandbox.
Utilisez le sandbox uniquement pour tester et/ou récupérer du code converti précédemment.
Regardez cette vidéo YouTube pour un aperçu du processus.

Configuration

Cloner Drupal 8.0.x :

git clone -b 8.0.x http://git.drupal.org/project/drupal.git d8

La version courante de Drupal sera installée dans le dossier « d8 » (nommez-le comme vous voulez)

1. Installez Drupal comme d’habitude (en utilisant le profil d’installation Standard).
2. Activez les trois paramètres Twig (debugging, cache, auto_reload) à True dans services.yml.

Conversion

Fonctions de thème

Convertissez la fonction de thème en fichier template et fonction de prétraitement :

1. Identifiez le fichier d’origine de votre fonction de thème (theme.inc ? core/modules/color/ ?)
2. Créez un fichier template X.html.twig pour la fonction de thème :
- Nommez votre nouveau fichier en conséquence
- Supprimez « theme_ » du début de votre fonction et terminez par .html.twig
- Transformez les underscores (« _ ») en tirets (« - »).
- Exemples :
* theme_link() devient link.html.twig
* theme_user_signature() devient user-signature.html.twig

3. Placez votre nouveau template Twig dans le dossier templates de votre thème complet (dans le sandbox) :
- pour les fonctions provenant d’un module spécifique, par exemple stark/templates/comment etc.
- pour les fonctions provenant de theme.inc, stark/templates/theme.inc
- pour les fonctions provenant de form.inc, stark/templates/form.inc
4. Consultez la documentation API Drupal 8 et trouvez votre fonction.
- (Des liens vers toutes les fonctions sont disponibles dans cette feuille de calcul)
5. Ajoutez un docblock PHP en haut du fichier, entouré des commentaires Twig {# #}
- Ajoutez la ligne @file tout en haut.
- Copiez la définition de la fonction juste sous la ligne @file. Réécrivez « Retourne le HTML... » en « Implémentation de thème par défaut ... ». Réécrivez en une seule ligne.
- Ajoutez la ligne « Variables disponibles: » (remplacez les variables @param)
- Copiez les variables indiquées dans la section « Paramètres » de la documentation api.drupal.org
- Supprimez la ligne @see template_preprocess() si elle existe.
- Ajoutez la ligne @see template_preprocess_THEME_HOOK().
- Ajoutez la ligne thématique @ingroup (voir exemple de docblock ci-dessous).

6. Copiez le code source de votre fonction sous le docblock (voir exemple ci-dessous)
7. Modifiez le code PHP principalement en HTML avec opérateurs d’impression
- Supprimez le code PHP du HTML, exemples :
* function whatever() {
* // …
* return $output; }
- Supprimez les opérateurs PHP d’impression et remplacez-les par {{ }}
* Convertissez $variables en noms simples : $variable['title'] devient {{ title }}
* Remplacez la syntaxe de tableau par la syntaxe pointée : $variable['page']['tabs'] devient {{ page.tabs }}
- Supprimez la logique PHP et remplacez-la par la syntaxe conditionnelle {%%}.
* <?php foreach $items as $item ?> devient {% for item in items %}
- Remplacez les commentaires PHP par des commentaires Twig {# #}
- Remplacez les fonctions t() autour des littéraux par le filtre t : {{ 'texte entre guillemets'|t }}
- Déplacez toute la logique PHP dans les variables vers une fonction de prétraitement. (instructions de prétraitement ci-dessous)
8. Si vous remarquez des choses à améliorer, par exemple fusionner des templates redondants ou améliorer le balisage ou les noms de variables, signalez-le dans cette feuille de calcul ou créez un problème dans notre sandbox. Par exemple : http://drupal.org/node/180591

Conversion ou fusion dans les fonctions de prétraitement

REMARQUE :

Les fonctions de prétraitement remplacent toutes les fonctions de thème.
Si votre template contient de la logique PHP affectant les variables affichées, ce code doit être déplacé dans une fonction de prétraitement.
Si votre template était initialement une fonction de thème, celle-ci devra être convertie en fonction de prétraitement.
Si certaines fonctions de thème ont déjà des fonctions de prétraitement associées, déplacez la logique de traitement des variables dans ces fonctions de prétraitement.
Ne pas ajouter de ligne dans hook_theme pour dire à Drupal d’utiliser un fichier template à la place d’une fonction de thème.

INSTRUCTIONS :

Renommez theme_VOTREFONCTION en template_preprocess_VOTREFONCTION.
Passez $variables par référence avec un esperluette (&). Par exemple theme_select($variables) devient template_preprocess_select(&$variables).
Modifiez la fonction pour qu’elle ne traite que la logique de préparation des variables ; supprimez toute mise en forme (par ex. $output).

Si vos templates Twig manquent de fonctions ...

Si vous avez besoin d’un accès à un filtre ou une fonction dans Twig qui ne fonctionne pas encore, ajoutez-le à ce ticket ouvert. Notez que la plupart des fonctions PHP ou Drupal doivent être déplacées dans des fonctions de prétraitement. Une fonction ne doit rester dans le template que si un développeur thème en a réellement besoin.

EXEMPLE SIMPLE DE CONVERSION (theme_link)

Code PHP

function theme_link($variables) { return '<a href="' . $variables['options']['html'] ? $variables['text'] : check_plain($variables['text']) . '">' . $variables['text'] . '</a>'; }

Template Twig (nom de fichier : link.html.twig)

{# 
/** 
 * @file 
 * Implémentation de thème par défaut pour afficher un lien. 
 * 
 * Variables disponibles : 
 * - text : Le texte du lien pour la balise anchor. 
 * - url : L’URL complète vers laquelle le lien pointe, par exemple "/node/34" ou "http://example.com/foo". 
 * - attributes : Les attributs HTML restants pour l’élément contenant. 
 * 
 * @see template_preprocess_link() 
 * 
 * @ingroup themeable 
 */ 
#}
{{ text }}

Modifications dans system.module (fonction de prétraitement)

/** 
 * Prépare les variables pour les templates de lien. 
 * 
 * Template par défaut : link.html.twig. 
 * 
 * @param array $variables 
 *   Tableau associatif contenant : 
 *   - text : Le texte traduit du lien pour la balise anchor. 
 *   - path : Le chemin interne ou URL externe du lien. 
 *   - options : Un tableau associatif d’options supplémentaires. 
 */ 
function template_preprocess_link(&$variables) { 
  $variables['url'] = url($variables['path'], $variables['options']); 
}

Commentaires :

Andrey Podanenko : http://drupal.org/node/1783130 Comment renommer les variables
jen : Ajoutez vos propres marqueurs de commentaire Twig {# et #}.
jen : Suivez les marqueurs de commentaires Twig avec les marqueurs doxygen PHP standards.
jen : Copiez-collez cette définition depuis api.drupal.org.
James Wilson : Lors du copier-coller de la définition d’une fonction, réécrivez « Retourne HTML ... » par « Implémentation de thème par défaut ».
jen : Copiez-collez les paramètres depuis api.drupal.org.
James Wilson : Supprimez le signe dollar dans les noms de variables, pour référencer une autre variable dans le bloc doc, utilisez des quotes simples autour de la variable. [Voir la discussion ici http://drupal.org/node/1804710]
jen : Vous « affichez » les variables dans Twig avec la syntaxe {{ }}.
jen : Les attributs sont « percés », donc vous pouvez référencer des classes.
jen : La plupart des fonctions comme url() doivent être supprimées du template et déplacées dans le prétraitement.

Types de blocs supplémentaires (EBT) – Nouvelle expérience de Layout Builder❗

❗Types de paragraphes supplémentaires (EPT) – Nouvelle expérience Paragraphes