Migrer son thème vers Drupal 11

Quand on évalue le passage à Drupal 11, l'attention se porte souvent sur le core, les modules contrib et la couche de données. Le thème, lui, passe parfois au second plan. C'est une erreur courante. Le theming a beaucoup évolué depuis Drupal 7, et un thème custom écrit il y a quelques années peut concentrer une bonne part du travail de migration. Bonne nouvelle : si votre thème a déjà été porté en Drupal 8 ou 9, le chemin vers Drupal 11 est nettement plus court qu'on ne l'imagine.

Cet article fait le point sur ce qui a changé dans le theming entre Drupal 7, 8, 9, 10 et 11, sur les pièges concrets (Twig 3, hooks dépréciés, disparition de Classy) et sur la question stratégique qui revient systématiquement : faut-il adapter le thème existant ou profiter de la migration pour repartir sur une base neuve?

Comment le theming a évolué de Drupal 7 à Drupal 11

Pour comprendre l'effort de migration, il faut situer d'où part votre thème. Chaque version majeure a déplacé le curseur.

Drupal 7 : le monde PHPTemplate. Les thèmes reposaient sur des fichiers .tpl.php mêlant logique PHP et balisage, sur un template.php rempli de fonctions de prétraitement et sur des fonctions theme overridables. C'est un modèle complètement différent de celui d'aujourd'hui. Un thème resté en Drupal 7 ne se migre pas vers Drupal 11 : il se réécrit. Il n'y a pas de chemin automatique entre PHPTemplate et l'architecture actuelle.

Drupal 8 : la bascule vers Twig. Drupal 8 a introduit Twig comme moteur de templating, le fichier .info.yml, les libraries pour déclarer CSS et JS et une séparation nette entre logique et présentation. C'est la rupture majeure. Un thème conçu pour Drupal 8 partage l'essentiel de son ADN avec un thème Drupal 11.

Drupal 9 et 10 : continuité et nettoyage. Drupal 9 a surtout consisté à retirer le code déprécié de Drupal 8. Drupal 10 a apporté un changement notable côté theming : la suppression du thème de base Stable et l'arrivée du mécanisme starterkit pour générer des thèmes. Le librairie front a aussi été modernisée (jQuery réduit au minimum, CKEditor 5).

Drupal 11 : consolidation et Twig 3. Drupal 11 ne révolutionne pas le theming, il consolide. Le point d'attention principal est Twig 3, qui durcit certaines règles de syntaxe, et la confirmation de tendances déjà engagées : moins de jQuery, plus de standards web modernes, single directory components qui gagnent du terrain. Si votre thème tourne proprement en Drupal 10, le passage à Drupal 11 relève surtout de la vérification et de l'ajustement.

La leçon est simple : la vraie marche, c'est Drupal 7 vers 8. Une fois cette marche franchie, les versions suivantes s'enchaînent avec un effort décroissant.

Twig 3 : ce qui change concrètement

Drupal 11 embarque Twig 3, qui succède à Twig 2 utilisé par Drupal 9 et 10. Pour la plupart des thèmes bien écrits, la transition est transparente. Quelques points demandent toutefois une vérification.

La syntaxe des filtres et des tests s'est resserrée. Certaines tournures tolérées auparavant déclenchent désormais des avertissements ou des erreurs. Les espaces autour des opérateurs, l'usage de spaceless (remplacé par le filtre apply) et certaines constructions de boucles méritent une relecture.

Un exemple de template Twig propre et compatible :

{% set classes = [
  'card',
  node.bundle ? 'card--' ~ node.bundle|clean_class,
  is_promoted ? 'card--promoted',
] %}
<article{{ attributes.addClass(classes) }}>
  <h2>{{ label }}</h2>
  {% if content.field_image %}
    {{ content.field_image }}
  {% endif %}
</article>

Le réflexe à adopter : activer le mode debug Twig en environnement de développement et surveiller les logs. Les avertissements de dépréciation y apparaissent et constituent votre feuille de route de mise en conformité.

# Activer le debug Twig via drush
drush state:set twig_debug 1
drush cache:rebuild

Hooks et fonctions de theming dépréciés

C'est souvent là que se cachent les surprises. Au fil des versions, Drupal a déprécié puis retiré un certain nombre de fonctions et de hooks de theming. Un thème qui s'y appuie encore déclenchera des erreurs en Drupal 11.

Les fonctions theme procédurales. Le pattern historique des fonctions theme_* et des theme function overrides a été progressivement abandonné au profit des templates Twig. Drupal 10 et 11 poussent fermement vers le tout-Twig. Si votre thème contient encore des fonctions de rendu en PHP, elles doivent migrer vers des templates.

Les hooks de prétraitement. Les hooks hook_preprocess_HOOK() restent valides, c'est le coeur du theming Drupal moderne. Mais certains hooks spécifiques ont changé de signature ou ont été retirés. Il faut vérifier chaque template_preprocess custom contre la version cible.

Les fonctions utilitaires dépréciées. Des helpers comme drupal_render(), l'ancien usage de theme() ou certaines fonctions de la classe Unicode ont disparu. Les render arrays et les services injectés les remplacent. Un outil comme drupal-rector automatise une part de ces remplacements.

# Détecter le code déprécié dans un thème custom
vendor/bin/drupal-check web/themes/custom/mon_theme

L'audit de ces dépréciations est mécanique mais indispensable. Il révèle en quelques minutes l'ampleur réelle du chantier, là où une estimation à l'oeil reste hasardeuse.

Starterkit et la disparition de Classy

Le changement qui surprend le plus les équipes habituées à Drupal 8 et 9 concerne les thèmes de base. Historiquement, beaucoup de thèmes custom héritaient de Classy, le thème de base fourni par le core qui apportait un ensemble de classes CSS prêtes à l'emploi. Classy a été retiré du core à partir de Drupal 10. Stable, autre base historique, a connu le même sort.

À la place, Drupal propose désormais l'approche starterkit : une commande qui génère un nouveau thème à partir d'un modèle, en copiant les fichiers de base dans votre thème plutôt qu'en les laissant dans le core.

# Générer un nouveau thème avec starterkit
php core/scripts/drupal generate-theme mon_theme

La philosophie est différente. Au lieu d'hériter d'un thème de base maintenu par le core, vous obtenez une copie autonome que vous contrôlez entièrement. C'est plus de liberté et moins de dépendances cachées, mais cela signifie aussi que les classes et le markup autrefois fournis par Classy doivent désormais vivre dans votre thème.

Conséquence concrète pour la migration : si votre thème custom déclare base theme: classy dans son .info.yml, ce thème de base n'existe plus. Deux options s'offrent à vous. Soit vous intégrez le module contrib qui republie Classy pour assurer la continuité, ce qui est la voie la plus rapide. Soit vous absorbez les styles et les templates pertinents directement dans votre thème, ce qui assainit la base sur le long terme.

Auditer la compatibilité d'un thème custom

Avant de décider quoi que ce soit, il faut savoir où vous en êtes. Un audit de compatibilité structuré tient en quelques étapes.

Étape 1 : identifier la version de départ. Un thème Drupal 7 en PHPTemplate et un thème Drupal 10 en Twig ne jouent pas dans la même catégorie. La version de départ détermine tout le reste.

Étape 2 : passer les outils automatiques. drupal-check et drupal-rector analysent le code et listent les API dépréciées, les fonctions retirées et les changements de signature. C'est la photographie objective de l'effort technique.

Étape 3 : vérifier les dépendances de theming. Le base theme déclaré existe-t-il toujours? Les libraries pointent-elles vers des assets encore présents? Le thème utilise-t-il des modules contrib de theming dont la compatibilité Drupal 11 reste à confirmer?

Étape 4 : auditer les templates Twig. Relire les overrides Twig à la recherche de syntaxe incompatible avec Twig 3 et de variables qui n'existeront plus dans les render arrays de la version cible.

Étape 5 : évaluer la dette accumulée. Au-delà de la stricte compatibilité, c'est le moment de mesurer l'état réel du thème : duplication, CSS difficile à maintenir, JavaScript vieillissant, absence de système de design cohérent. Cette dette pèsera sur l'arbitrage qui suit.

Cet audit s'inscrit naturellement dans une démarche plus large de migration Drupal, où le thème n'est qu'une des briques à valider aux côtés du core, des modules et des données.

Adapter le thème existant ou repartir de zéro

C'est la décision structurante. Et elle ne se tranche pas par principe mais par analyse.

Adapter le thème existant est généralement le bon choix quand le thème part de Drupal 8, 9 ou 10, qu'il est propre, bien organisé et que le design répond toujours aux besoins. Dans ce cas, la migration consiste à corriger les dépréciations, ajuster la syntaxe Twig 3 et traiter la question du base theme. L'effort est contenu, le risque faible et le rendu visuel préservé à l'identique.

Repartir sur une base neuve s'impose plus souvent qu'on ne le croit, et pas seulement pour des raisons techniques. Quand le thème vient de Drupal 7, la réécriture est de toute façon inévitable. Quand le thème accumule des années de dette, qu'il est difficile à maintenir ou que le design est daté, la migration devient l'occasion idéale d'une refonte Drupal qui livre une base moderne, performante et alignée sur l'identité actuelle de l'organisation.

Le bon arbitrage repose sur trois questions. Le thème actuel sert-il encore correctement les besoins métier et l'image de marque? Le coût d'adaptation est-il proche de celui d'une refonte? La refonte apporterait-elle de la valeur au-delà de la simple compatibilité (performance, accessibilité, expérience éditeur)? Si les réponses penchent vers la valeur ajoutée, repartir de zéro devient un investissement, pas une dépense.

Dans bien des cas, la voie médiane est la plus pertinente : conserver l'architecture et les templates qui fonctionnent, et profiter de la migration pour moderniser les portions les plus fatiguées. Drupal 11 se prête bien à cette approche progressive.

L'essentiel à retenir

Le theming Drupal a connu une rupture majeure entre Drupal 7 et 8, puis une suite d'évolutions plus douces. Un thème Drupal 8 ou plus récent se migre vers Drupal 11 avec un effort raisonnable, centré sur Twig 3, les dépréciations et la disparition de Classy. Un thème Drupal 7, lui, se réécrit. Dans tous les cas, l'audit automatisé est le point de départ qui transforme une intuition en plan d'action chiffré et fiable.

Vous préparez le passage à Drupal 11 et vous vous demandez ce que devient votre thème custom? Un audit de compatibilité lève le doute en quelques jours et clarifie l'arbitrage entre adaptation et refonte. Parlons de votre projet.