Précédence des template parts entre thème enfant et parent bloc

« Mon thème enfant ne charge jamais mon header.html, c’est toujours celui du parent qui s’affiche. » Ce message, reçu d’un développeur travaillant sur un thème enfant de thème bloc, illustre une confusion fréquente au sujet d’une fonctionnalité encore en cours de stabilisation à cette date, actuellement disponible via le plugin Gutenberg et dont l’arrivée complète dans le cœur de WordPress est annoncée pour la prochaine version majeure.

Contrairement à l’héritage bien connu des thèmes enfants PHP classiques, où un simple fichier du même nom dans le thème enfant suffit à remplacer celui du parent, le mécanisme équivalent pour les thèmes blocs impose une organisation précise du dossier, sans quoi rien ne se passe comme attendu.

Ce que la résolution vérifie précisément

Pour qu’un fichier de template part du thème enfant remplace effectivement celui du parent, il doit se trouver exactement au même chemin relatif dans le dossier parts du thème enfant que celui utilisé par le thème parent, avec un nom de fichier strictement identique. Une différence de casse, un sous-dossier supplémentaire, ou un chemin légèrement différent suffit à faire échouer silencieusement le remplacement.

Sur ce projet précis, le thème parent rangeait son fichier dans parts/header.html, mais le développeur du thème enfant avait placé le sien dans parts/site-header.html, en pensant, à tort, qu’un nom de fichier différent mais explicite suffirait à être reconnu comme un remplacement intentionnel du header. Ce n’est absolument pas le cas : le mécanisme repose entièrement sur l’identité exacte du chemin et du nom de fichier.

Le correctif appliqué

# Structure attendue pour que le remplacement fonctionne correctement
mon-theme-parent/
  parts/
    header.html
    footer.html

mon-theme-enfant/
  style.css          (avec Template: mon-theme-parent)
  parts/
    header.html      (même nom, même emplacement relatif)

Une fois le fichier renommé et déplacé au bon emplacement, exactement parts/header.html dans le thème enfant, le remplacement a fonctionné immédiatement, sans configuration PHP supplémentaire ni déclaration explicite dans un fichier de fonctions. Cette simplicité, une fois le bon chemin identifié, contraste avec la difficulté initiale à comprendre pourquoi rien ne se passait.

Ce qui distingue ce mécanisme de l’héritage PHP classique

• Aucune fonction équivalente à get_stylesheet_directory() n’a besoin d’être appelée manuellement : la résolution est entièrement gérée par le cœur du système de thèmes blocs.
• Le principe de résolution s’applique de la même façon aux fichiers de templates et de parts, avec la même exigence de chemin identique entre parent et enfant.
• Le fichier theme.json suit une logique différente : il peut être partiellement complété par l’enfant, sans obligation de dupliquer l’intégralité du fichier parent, contrairement aux templates et template parts qui fonctionnent en tout ou rien.

Une vérification rapide à connaître

Pour confirmer qu’un remplacement fonctionne réellement, la méthode la plus fiable reste d’ajouter temporairement un commentaire HTML visible, comme <!-- version enfant -->, dans le fichier suspecté, puis de vérifier sa présence dans le code source de la page affichée. Cette méthode rustique évite bien des suppositions erronées sur ce qui est réellement chargé.

Un mécanisme d’héritage, aussi élégant soit-il sur le papier, ne vaut que par la rigueur de son application. Un chemin de fichier approximatif suffit à le rendre totalement inopérant.

En résumé

Cette règle de précédence stricte, bien que déroutante au premier abord pour qui connaît l’héritage plus permissif des thèmes PHP classiques, reste finalement simple une fois comprise : même chemin, même nom, rien de plus. Je recommande de toujours vérifier cette structure de dossiers en tout premier lieu, avant d’envisager une cause plus complexe à un remplacement de template part qui ne fonctionne pas comme attendu.