get_template() n’est pas get_stylesheet() : la confusion des débutants

Que renvoie get_template() lorsqu’un thème enfant est actif ? La réponse surprend souvent les développeurs qui découvrent cette fonction : elle renvoie le nom du dossier du thème parent, jamais celui du thème enfant actuellement actif. Cette confusion, en apparence anodine, provoque des bugs difficiles à comprendre dès qu’un développeur suppose, par analogie de nom, que get_template() se comporte comme get_stylesheet().

Les deux fonctions existent depuis longtemps dans WordPress et portent des noms suffisamment proches pour entretenir la confusion, en particulier chez les développeurs qui découvrent le mécanisme des thèmes enfants pour la première fois.

Ce que chaque fonction renvoie réellement

get_template() renvoie toujours le nom du dossier du thème parent, que ce thème parent soit actif seul ou qu’un thème enfant soit activé par-dessus. get_stylesheet(), à l’inverse, renvoie toujours le nom du dossier du thème actuellement actif, qu’il s’agisse d’un thème sans parent ou d’un thème enfant.

// Thème enfant "monsite-enfant" actif, thème parent "monsite-parent"
echo get_template();   // affiche "monsite-parent"
echo get_stylesheet();  // affiche "monsite-enfant"

Quand aucun thème enfant n’est utilisé et qu’un thème classique est activé seul, les deux fonctions renvoient la même valeur, ce qui masque la différence pendant longtemps sur les projets sans thème enfant, jusqu’au jour où un thème enfant est introduit et où le code casse silencieusement.

Les fonctions de chemin associées

Cette même logique se retrouve sur les fonctions de chemin de fichier, avec la même règle : les fonctions contenant template pointent vers le thème parent, celles contenant stylesheet pointent vers le thème actif.

• get_template_directory() : chemin absolu vers le dossier du thème parent
• get_stylesheet_directory() : chemin absolu vers le dossier du thème actif (enfant si présent)
• get_template_directory_uri() : URL du dossier du thème parent
• get_stylesheet_directory_uri() : URL du dossier du thème actif (enfant si présent)

Le piège concret

Un développeur qui souhaite charger un fichier spécifique au thème enfant, par exemple une image de démonstration ajoutée uniquement dans l’enfant, écrit parfois par réflexe :

$chemin_image = get_template_directory() . '/images/demo.jpg';

Ce code fonctionne tant que le fichier existe dans le thème parent, mais échoue silencieusement (image manquante, sans erreur PHP visible) dès que l’image se trouve uniquement dans le dossier du thème enfant. La correction consiste simplement à remplacer get_template_directory() par get_stylesheet_directory() pour cibler le thème réellement actif :

$chemin_image = get_stylesheet_directory() . '/images/demo.jpg';

Un moyen mnémotechnique simple

Pour retenir la distinction sans avoir à consulter la documentation à chaque fois, il suffit d’associer stylesheet à la feuille de style style.css qui définit un thème : chaque thème, parent comme enfant, possède son propre style.css, et get_stylesheet() pointe toujours vers celui du thème réellement actif. template, à l’inverse, désigne la source des fichiers de gabarit hérités, presque toujours ceux du parent dans un contexte de thème enfant.

Un conseil qui évite bien des erreurs : dans un thème conçu pour être décliné en thèmes enfants, préférer systématiquement les fonctions stylesheet pour tout ce qui concerne des ressources propres au thème actif, et réserver les fonctions template aux cas où l’on cherche explicitement une ressource du parent.

Quand utiliser volontairement get_template()

Il existe des cas légitimes où cibler explicitement le thème parent est l’intention recherchée : par exemple pour vérifier la version du thème parent installée, indépendamment du thème enfant actif, ou pour charger une ressource partagée que tous les thèmes enfants d’une même famille doivent utiliser à l’identique, sans possibilité de surcharge. Dans ces cas précis, get_template() et ses fonctions associées sont le bon choix, à condition que ce choix soit délibéré et documenté dans le code, pas le fruit d’une confusion de noms.

En résumé

La proximité des noms get_template() et get_stylesheet() entretient une confusion classique chez les développeurs qui découvrent les thèmes enfants. Retenir que stylesheet désigne toujours le thème actif et que template désigne toujours le parent évite la quasi-totalité des bugs liés à cette paire de fonctions, aussi bien pour l’obtention du nom du thème que pour la construction de chemins de fichiers.