locate_template()

Définition : locate_template() recherche un fichier de template WordPress parmi plusieurs noms candidats et renvoie son chemin si une correspondance est trouvée. Elle peut éventuellement charger le fichier retenu.

Terminologie

Nom technique : locate_template()

Appellations : Nom principal utilisé

À quoi cela sert, concrètement

Elle sert à construire des mécanismes de repli et à respecter les surcharges d’un thème enfant, sans coder en dur un chemin vers le parent ou vers une installation particulière.

Fonctionnement détaillé

La fonction recherche dans les emplacements reconnus des thèmes, en donnant priorité au thème enfant avant le parent. Avec load=false, elle retourne uniquement le chemin ; le mode chargement accepte aussi un tableau d’arguments.

Quand l’utiliser : contexte et choix techniques

L’utiliser lorsque plusieurs variantes d’un fragment sont possibles ou lorsqu’une extension doit trouver un template du thème de manière contrôlée. Pour une inclusion habituelle, get_template_part() est souvent plus simple.

Situation professionnelle réaliste

Un thème tente de localiser un fragment de carte premium puis retombe sur une version standard si la première n’est pas présente.

Exemple pratique — PHP commenté

Exemple pédagogique : adapter le nom du thème, les fichiers et les conditions à un environnement de développement. Il ne constitue pas une preuve d’exécution sur ATOOLPHA.

<?php
// Recherche uniquement, sans inclusion automatique.
$path = locate_template( array(
    'template-parts/card-premium.php',
    'template-parts/card.php',
), false, false );
if ( $path && is_readable( $path ) ) {
    // Exemple : information destinée au journal de développement.
    error_log( 'Template sélectionné : ' . basename( $path ) );
}

Décryptage de l’exemple, étape par étape

WordPress compare les noms dans l’ordre et cherche dans les répertoires admissibles. load=false empêche l’exécution du fichier ; le test is_readable() vérifie la lisibilité du résultat avant toute action métier supplémentaire.

Résultat observable

Si un des fichiers existe, le chemin de la variante prioritaire est identifié. Aucun template n’est rendu et aucun contenu n’est ajouté à la page par cet exemple.

Exercice de vérification pratique

Créer deux fichiers de test, observer quel chemin est renvoyé, puis retirer le premier. Vérifier que le repli sélectionne le second et que le thème enfant reste prioritaire si une surcharge existe.

Pièges, limites et sécurité

Ne pas construire la liste des noms à partir d’une chaîne utilisateur non contrôlée. Le retour est un chemin local et ne doit pas être inséré comme URL de ressource publique.

Différences avec les notions voisines

locate_template() localise éventuellement un fichier ; get_template_part() sert à inclure un composant de rendu du thème.

Diagnostic avancé et cas de maintenance

Cas avancé : une extension cherche un template personnalisé et doit se comporter normalement lorsqu’il n’existe pas. Utiliser une liste explicite de candidats, tester la valeur de retour et prévoir un repli maîtrisé. Laisser un visiteur choisir librement le nom d’un fichier serait une erreur de sécurité.