Hiérarchie des Templates WordPress : Le Guide Technique Complet
La Hiérarchie de Modèles de WordPress est le système de résolution déterministe que WordPress utilise pour sélectionner quel fichier de modèle PHP affiche une requête de page donnée. Lorsqu’un visiteur charge une URL sur votre site, WordPress évalue le contexte de la requête — type de publication, taxonomie, slug, ID, et plus encore — puis parcourt une liste priorisée de noms de fichiers candidats jusqu’à trouver une correspondance dans le répertoire de votre thème actif. Si aucun modèle spécifique n’existe, il se replie sur index.php.
Comprendre ce système en profondeur n’est pas optionnel pour le développement WordPress sérieux. C’est le fondement de chaque mise en page personnalisée, de chaque remplacement de thème, et de chaque optimisation des performances impliquant la mise en cache des modèles. Que vous gériez une publication à fort contenu, une boutique WooCommerce, ou une configuration WordPress headless, la hiérarchie régit quel PHP s’exécute à chaque chargement de page.
Ce qu’est réellement la Hiérarchie de Modèles
Dans son essence, la Hiérarchie de Modèles est une chaîne de recherche intégrée dans le cœur de WordPress (wp-includes/class-wp-query.php et wp-includes/template.php). Lorsque WordPress termine l’analyse de la requête et remplit l’objet global $wp_query, il appelle les équivalents de get_template_part() en interne pour résoudre le modèle correct. La résolution n’est pas aléatoire — c’est une liste stricte et ordonnée de noms de fichiers vérifiés dans le répertoire racine de votre thème.
L’insight architectural clé que la plupart des tutoriels manquent : WordPress ne scanne pas votre répertoire de thème. Il construit un tableau priorisé de noms de fichiers candidats basé sur les variables de requête, puis vérifie chaque fichier en utilisant locate_template(). Cette distinction est importante lorsque vous déboguez des modèles manquants ou construisez des générateurs de thèmes programmatiques.
La chaîne de repli se termine toujours à index.php. Ce fichier est le seul fichier de modèle que WordPress exige que chaque thème inclue, conformément aux normes de développement de thèmes.
Fichiers de Modèles Principaux que Chaque Thème Doit Comprendre
| Fichier de Modèle | Se Déclenche Quand | Repli Vers |
|---|---|---|
front-page.php | La page d’accueil statique est définie dans Réglages > Lecture | home.php |
home.php | Page d’index des articles de blog | index.php |
single-{post-type}.php | Article unique d’un type de publication personnalisé spécifique | single.php |
single.php | Tout article unique (type de publication par défaut) | singular.php |
singular.php | Tout article ou page unique (fourre-tout générique) | index.php |
page-{slug}.php | Une page spécifique par slug | page-{ID}.php |
page-{ID}.php | Une page spécifique par ID de base de données | page.php |
page.php | Toute page statique | singular.php |
category-{slug}.php | Archive de catégorie par slug | category-{ID}.php |
category-{ID}.php | Archive de catégorie par ID de terme | category.php |
category.php | Toute archive de catégorie | archive.php |
tag-{slug}.php | Archive d’étiquette par slug | tag-{ID}.php |
tag.php | Toute archive d’étiquette | archive.php |
taxonomy-{tax}-{term}.php | Taxonomie personnalisée, terme spécifique | taxonomy-{tax}.php |
taxonomy-{tax}.php | Taxonomie personnalisée, tout terme | taxonomy.php |
taxonomy.php | Toute archive de taxonomie personnalisée | archive.php |
author-{nicename}.php | Archive d’auteur par nom d’utilisateur | author-{ID}.php |
author-{ID}.php | Archive d’auteur par ID utilisateur | author.php |
author.php | Toute archive d’auteur | archive.php |
archive-{post-type}.php | Archive de type de publication personnalisé | archive.php |
archive.php | Toute archive (date, auteur, taxonomie) | index.php |
date.php | Archive basée sur la date | archive.php |
search.php | Page de résultats de recherche | index.php |
404.php | Aucun contenu correspondant trouvé | index.php |
attachment.php | Page de pièce jointe unique | single.php |
embed.php | Cadre oEmbed pour un article | index.php |
index.php | Repli universel | — |
Notez l’entrée singular.php — c’est un modèle que de nombreux développeurs ignorent complètement. Introduit dans WordPress 4.3, il se situe entre single.php/page.php et index.php dans la hiérarchie, agissant comme un fourre-tout unifié pour toute vue de contenu singulier. Si votre thème inclut singular.php, il interceptera les cas où ni single.php ni page.php n’existe.
L’Ordre Complet de Résolution des Modèles par Type de Page
Articles de Blog Uniques
Lorsqu’un visiteur demande un article standard (post_type = 'post'), WordPress vérifie dans cet ordre exact :
single.phpsingular.phpindex.php
single-post-{slug}.php (WordPress 4.4+, ex. single-post-hello-world.php)
single-post.phpLa variante basée sur le slug à l’étape 1 est rarement documentée mais extrêmement utile pour donner à un seul article phare une mise en page entièrement unique sans toucher à aucun autre modèle.
Types de Publications Personnalisés
Pour un type de publication personnalisé enregistré comme portfolio :
single-portfolio-{slug}.phpsingle-portfolio.phpsingle.phpsingular.phpindex.php
Pour son archive (nécessite 'has_archive' => true dans register_post_type()) :
archive-portfolio.phparchive.phpindex.php
Un écueil courant : enregistrer un type de publication personnalisé avec 'has_archive' => false (la valeur par défaut) et se demander ensuite pourquoi archive-portfolio.php ne se charge jamais. L’URL d’archive renvoie simplement une erreur 404 dans ce cas.
Pages Statiques
- Fichier de modèle défini via la boîte méta Attributs de page (modèle de page personnalisé)
page-{slug}.phppage-{ID}.phppage.phpsingular.phpindex.php
Les modèles de pages personnalisés sont des fichiers PHP dans le répertoire de votre thème qui incluent un commentaire d’en-tête de fichier :
<?php
/**
* Template Name: Full Width Layout
* Template Post Type: page
*/La déclaration Template Post Type (WordPress 4.7+) restreint les types de publications pouvant utiliser ce modèle depuis l’éditeur. Sans elle, le modèle apparaît dans le menu déroulant Attributs de page uniquement pour les pages.
Archives de Catégories
category-{slug}.phpcategory-{ID}.phpcategory.phparchive.phpindex.php
Archives de Taxonomies Personnalisées
Pour une taxonomie enregistrée comme genre avec un slug de terme thriller :
taxonomy-genre-thriller.phptaxonomy-genre.phptaxonomy.phparchive.phpindex.php
Archives d’Auteurs
author-{user_nicename}.phpauthor-{user_ID}.phpauthor.phparchive.phpindex.php
La Page d’Accueil (Cas Limite Critique)
C’est la partie la plus mal comprise de la hiérarchie. WordPress distingue deux scénarios de page d’accueil :
Scénario A — Index des articles de blog comme page d’accueil (Réglages > Lecture : « Vos derniers articles ») :
front-page.phphome.phpindex.php
Scénario B — Page statique comme page d’accueil (Réglages > Lecture : « Une page statique ») :
front-page.php
page.php (si aucun front-page.php n’existe)
index.phpLa nuance critique : front-page.php a la priorité dans les deux scénarios. Si front-page.php existe dans votre thème, il affiche toujours la page d’accueil quels que soient les paramètres de Lecture. Cela surprend de nombreux développeurs qui créent front-page.php pour une page d’accueil statique mais oublient qu’il remplacera également l’index du blog s’ils changent le paramètre ultérieurement.
Résultats de Recherche et 404
Résultats de recherche :
search.phpindex.php
Pages d’erreur 404 :
404.phpindex.php
Un 404.php bien conçu est un atout de conversion, pas une réflexion après coup. Il doit inclure un formulaire de recherche, des liens vers le contenu populaire, et une navigation claire — tout ce qui nécessite de comprendre le système de modèles pour être correctement implémenté.
Comment WordPress Résout les Modèles en Interne
Comprendre les mécanismes internes aide lors du débogage ou de l’extension du système. Le processus de résolution dans wp-includes/template.php fonctionne comme suit :
// Simplified representation of WordPress template resolution
function get_query_template( $type, $templates = array() ) {
$type = preg_replace( '|[^a-z0-9-]+|', '', $type );
if ( empty( $templates ) ) {
$templates = array( "{$type}.php" );
}
// Fires before template resolution — allows plugins/themes to modify the list
$templates = apply_filters( "_{$type}_template_hierarchy", $templates );
$template = locate_template( $templates );
// Fires after template is located — allows final override
$template = apply_filters( "{$type}_template", $template, $type, $templates );
return $template;
}Deux hooks de filtre sont essentiels ici :
_{$type}_template_hierarchy — se déclenche avant la recherche de fichier, vous permettant d’injecter des candidats supplémentaires dans le tableau
{$type}_template — se déclenche après que le fichier est localisé, vous permettant de remplacer entièrement le chemin du modèle résolu
Ces hooks sont la façon dont les plugins de constructeurs de pages, les réseaux multisite, et WooCommerce remplacent les modèles sans toucher aux fichiers du thème.
Remplacement Programmatique de la Hiérarchie de Modèles
Injection d’un Chemin de Modèle Personnalisé
add_filter( 'single_template_hierarchy', function( $templates ) {
// Prepend a plugin-directory template before theme templates are checked
if ( is_singular( 'portfolio' ) ) {
array_unshift( $templates, plugin_dir_path( __FILE__ ) . 'templates/single-portfolio.php' );
}
return $templates;
} );
Remplacement d’un Modèle Après Résolution
add_filter( 'template_include', function( $template ) {
if ( is_singular( 'portfolio' ) && current_user_can( 'edit_posts' ) ) {
// Load a debug template for editors
$debug_template = get_stylesheet_directory() . '/debug/single-portfolio-debug.php';
if ( file_exists( $debug_template ) ) {
return $debug_template;
}
}
return $template;
} );
Le filtre template_include est le dernier hook avant que WordPress charge le fichier de modèle. Il reçoit le chemin entièrement résolu et doit retourner un chemin de fichier valide.
Parties de Modèles et la Fonction get_template_part()
Les parties de modèles sont des fragments PHP réutilisables chargés via get_template_part(). Elles suivent leur propre mini-hiérarchie :
// Loads content-video.php if it exists, falls back to content.php
get_template_part( 'template-parts/content', 'video' );
WordPress 5.5 a ajouté un troisième paramètre pour passer des données aux parties de modèles :
get_template_part( 'template-parts/card', 'product', array(
'post_id' => get_the_ID(),
'show_price' => true,
) );
À l’intérieur de la partie de modèle, récupérez ces données avec :
$args = wp_parse_args( $args, array(
'post_id' => 0,
'show_price' => false,
) );
Cela élimine le besoin d’utiliser des variables globales pour passer des données entre les modèles — une amélioration significative pour la maintenabilité et la testabilité.
Thèmes Enfants et le Système de Remplacement de Modèles
Les thèmes enfants étendent la hiérarchie en ajoutant le répertoire du thème enfant au début du chemin de recherche de modèles. Lorsque locate_template() s’exécute, il vérifie :
Répertoire du thème enfant (get_stylesheet_directory())
Répertoire du thème parent (get_template_directory())
Cela signifie que vous pouvez remplacer n’importe quel modèle de thème parent en créant un fichier avec le nom identique dans votre thème enfant. Vous n’avez pas besoin de copier le fichier entier — seulement les parties que vous souhaitez modifier — mais WordPress charge le fichier comme une unité complète, vous devez donc inclure tout le balisage requis.
Erreur courante avec les thèmes enfants : Copier functions.php du thème parent dans le thème enfant en s’attendant à ce qu’il remplace les fonctions du parent. Contrairement aux autres fichiers de modèles, functions.php dans un thème enfant est chargé en plus du functions.php du parent, et non à sa place. Les deux fichiers s’exécutent.
Pour créer une structure minimale de thème enfant :
my-child-theme/
├── style.css (required — contains theme header comment)
├── functions.php (optional — enqueue parent styles here)
└── single-post.php (overrides parent's single-post.php)
L’en-tête style.css doit déclarer le parent :
/*
Theme Name: My Child Theme
Template: parent-theme-directory-name
*/
Débogage du Modèle Actif
Méthode 1 : Plugin Query Monitor
Le plugin Query Monitor (gratuit, WordPress.org) affiche le fichier de modèle résolu et la hiérarchie complète des candidats dans son panneau de barre d’outils d’administration. C’est l’outil de débogage le plus fiable disponible et ajoute une surcharge négligeable.
Méthode 2 : Le Hook template_include
add_filter( 'template_include', function( $template ) {
if ( current_user_can( 'manage_options' ) ) {
echo '<!-- Template: ' . esc_html( str_replace( ABSPATH, '', $template ) ) . ' -->';
}
return $template;
} );
Cela affiche le chemin du modèle sous forme de commentaire HTML visible uniquement par les administrateurs. Supprimez-le avant de déployer en production.
Méthode 3 : WP_DEBUG et Journalisation
Sur un serveur de développement, activez la journalisation de débogage dans wp-config.php :
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
Puis ajoutez une journalisation temporaire dans template_include :
add_filter( 'template_include', function( $template ) {
error_log( 'Resolved template: ' . $template );
return $template;
} );
Sur un environnement Hébergement VPS avec accès root, vous pouvez surveiller le journal de débogage en temps réel :
tail -f /var/www/html/wp-content/debug.log
Cette approche est bien plus fiable que de s’appuyer sur des outils de débogage basés sur le navigateur lors du dépannage de la résolution de modèles sur un serveur en production ou de staging.
WooCommerce et le Système de Remplacement de Modèles
WooCommerce est livré avec sa propre hiérarchie de modèles qui se superpose au système natif de WordPress. Les modèles WooCommerce se trouvent dans wp-content/plugins/woocommerce/templates/ et sont chargés via sa propre fonction wc_get_template(), qui vérifie les remplacements dans :
wp-content/themes/your-theme/woocommerce/wp-content/themes/your-child-theme/woocommerce/Pour remplacer le modèle de produit unique de WooCommerce, copiez woocommerce/templates/single-product.php vers your-theme/woocommerce/single-product.php. Ne modifiez jamais directement les fichiers de modèles du plugin — ils sont écrasés à chaque mise à jour du plugin.
WooCommerce s’accroche également aux hooks d’action woocommerce_template_single_*, ce qui vous donne un contrôle granulaire sur les sections individuelles (prix, onglets, bouton d’ajout au panier) sans remplacer des fichiers de modèles entiers. C’est l’approche préférée pour les modifications mineures.
Thèmes Blocs et la Hiérarchie de Modèles dans l’Édition Complète du Site
WordPress 5.9 a introduit l’Édition Complète du Site (FSE) avec les thèmes blocs, ce qui change la façon dont la hiérarchie de modèles fonctionne en pratique. Les thèmes blocs stockent les modèles sous forme de fichiers HTML dans un répertoire templates/ plutôt que des fichiers PHP :
my-block-theme/
├── templates/
│ ├── index.html
│ ├── single.html
│ ├── page.html
│ ├── archive.html
│ └── 404.html
├── parts/
│ ├── header.html
│ └── footer.html
└── theme.jsonLa logique de résolution suit les mêmes règles de hiérarchie, mais WordPress vérifie maintenant également la base de données pour les modèles personnalisés par l’utilisateur enregistrés via l’Éditeur de Site. L’ordre de recherche devient :
- Modèle enregistré par l’utilisateur dans la base de données (type de publication
wp_template) - Fichier HTML du répertoire
templates/du thème - Fichier HTML du répertoire
templates/du thème parent - Modèles de repli intégrés de WordPress
Les thèmes PHP classiques et les thèmes blocs peuvent coexister dans une installation WordPress, mais vous ne pouvez pas mélanger des modèles PHP et des modèles blocs HTML au sein d’un seul thème. Si votre thème possède un répertoire templates/ et un theme.json valide, WordPress le traite comme un thème bloc.
Pour les équipes gérant des charges de travail critiques en termes de performances sur des Serveurs Dédiés, comprendre cette distinction est essentiel lors de l’évaluation des frameworks de thèmes — les thèmes blocs déchargent le rendu des modèles vers l’analyseur de blocs, qui a des caractéristiques de mise en cache différentes de l’exécution de modèles PHP.
Implications de Performance de la Hiérarchie de Modèles
Chaque résolution de modèle implique des vérifications du système de fichiers via locate_template(). Sur un site à fort trafic, cela peut ajouter une surcharge mesurable si elle n’est pas mise en cache. Optimisations clés :
Mise en cache des objets : Utilisez un cache d’objets persistant (Redis ou Memcached) pour mettre en cache les résultats de WP_Query et réduire le nombre de requêtes de base de données qui alimentent la sélection des modèles.
OPcache : Assurez-vous que PHP OPcache est activé et correctement configuré. Puisque les modèles sont des fichiers PHP, OPcache les compile en bytecode au premier chargement et sert les requêtes suivantes depuis la mémoire. Sur un VPS avec cPanel correctement configuré, OPcache est généralement activé par défaut mais peut nécessiter un réglage de opcache.memory_consumption et opcache.max_accelerated_files pour les thèmes volumineux avec de nombreux fichiers de modèles.
Évitez les fichiers de modèles inutiles : Chaque fichier de modèle dans le répertoire de votre thème est un candidat que locate_template() doit vérifier. Les thèmes avec des centaines de fichiers de modèles (courant dans les thèmes commerciaux surchargés) augmentent les E/S du système de fichiers à chaque requête non mise en cache. Auditez votre thème et supprimez les modèles inutilisés.
Mise en cache de page complète : Des outils comme WP Rocket, W3 Total Cache, ou la mise en cache au niveau du serveur (cache FastCGI Nginx, Varnish) contournent entièrement l’exécution des modèles PHP pour les utilisateurs anonymes. La résolution de la hiérarchie de modèles ne s’exécute que lorsque le cache est manqué.
Modèles de Personnalisation Pratiques
Modèle 1 : Mise en Page Spécifique à une Catégorie Sans Plugin
Créez category-news.php dans le répertoire de votre thème. WordPress l’utilise automatiquement pour l’archive de la catégorie « news ». Aucun plugin, aucun hook de filtre — juste un fichier avec le nom correct.
<?php
/**
* Template for the "news" category archive.
* Inherits from: category.php → archive.php → index.php
*/
get_header();
?>
<main class="news-archive">
<h1><?php single_cat_title(); ?></h1>
<?php if ( have_posts() ) : while ( have_posts() ) : the_post(); ?>
<?php get_template_part( 'template-parts/card', 'news' ); ?>
<?php endwhile; endif; ?>
<?php the_posts_pagination(); ?>
</main>
<?php get_footer(); ?>Modèle 2 : Mise en Page Par Auteur pour les Contributeurs Vedettes
// author-jane-smith.php — loads only for the author with nicename "jane-smith"
get_header();
?>
<div class="featured-author-layout">
<?php get_template_part( 'template-parts/author', 'featured' ); ?>
<!-- Custom bio section, social links, etc. -->
</div>
<?php get_footer(); ?>Modèle 3 : Logique Conditionnelle Dans index.php
Si vous construisez un thème minimal et souhaitez éviter plusieurs fichiers de modèles, vous pouvez utiliser des balises conditionnelles dans index.php :
<?php get_header(); ?>
<?php if ( is_front_page() && is_home() ) : ?>
<?php get_template_part( 'template-parts/home', 'blog-index' ); ?>
<?php elseif ( is_front_page() ) : ?>
<?php get_template_part( 'template-parts/home', 'static' ); ?>
<?php elseif ( is_single() ) : ?>
<?php get_template_part( 'template-parts/content', get_post_type() ); ?>
<?php elseif ( is_archive() ) : ?>
<?php get_template_part( 'template-parts/archive', 'default' ); ?>
<?php else : ?>
<?php get_template_part( 'template-parts/content', 'none' ); ?>
<?php endif; ?>
<?php get_footer(); ?>Ce modèle est utilisé par des thèmes comme Twenty Twenty-One et est parfaitement valide. Le compromis est qu’un seul index.php volumineux devient plus difficile à maintenir à mesure que la complexité augmente.
Multisite et Hiérarchie de Modèles
Dans un réseau WordPress Multisite, chaque site du réseau peut utiliser un thème actif différent. La hiérarchie de modèles fonctionne de manière identique par site, mais les plugins activés au niveau du réseau peuvent utiliser les filtres template_include ou _{$type}_template_hierarchy pour injecter des modèles partagés sur tous les sites sans dupliquer les fichiers de thèmes.
Un modèle multisite courant est un répertoire de « modèles réseau » en dehors de la racine web qui est référencé via des hooks de filtre au niveau du plugin. Cela permet à une équipe de conception centrale de pousser des mises à jour de modèles vers tous les sites simultanément — un avantage opérationnel significatif pour les agences gérant des dizaines de sites clients sur un seul environnement d’Hébergement Web Mutualisé ou VPS.
SSL, Sécurité et Permissions des Fichiers de Modèles
Les fichiers de modèles sont du PHP et doivent être traités comme du code exécutable. Des permissions de fichiers incorrectes sont un vecteur d’attaque courant. Sur un serveur Linux, les fichiers de modèles de thème doivent appartenir à l’utilisateur du serveur web (généralement www-data ou nginx) et être définis en mode 644 :
find /var/www/html/wp-content/themes/your-theme -type f -name "*.php" -exec chmod 644 {} ;
find /var/www/html/wp-content/themes/your-theme -type d -exec chmod 755 {} ;Ne définissez jamais les fichiers PHP à 777. Si un fichier de modèle nécessite un accès en écriture (inhabituel et généralement déconseillé), utilisez 664 avec une propriété de groupe appropriée à la place.
Associer votre installation WordPress à un Certificat SSL valide garantit que le contenu rendu par les modèles — y compris les pages générées dynamiquement avec des données utilisateur sensibles — est toujours transmis via HTTPS. C’est non négociable pour tout site utilisant des formulaires de contact, des comptes utilisateurs, ou du commerce électronique.
Référence de la Hiérarchie de Modèles : Flux Visuel
Request URL
|
v
WordPress Query Resolution (WP_Query)
|
+-- Is it the front page?
| front-page.php → home.php → index.php
|
+-- Is it a single post?
| single-{type}-{slug}.php → single-{type}.php → single.php → singular.php → index.php
|
+-- Is it a static page?
| [custom template] → page-{slug}.php → page-{ID}.php → page.php → singular.php → index.php
|
+-- Is it a category archive?
| category-{slug}.php → category-{ID}.php → category.php → archive.php → index.php
|
+-- Is it a custom taxonomy?
| taxonomy-{tax}-{term}.php → taxonomy-{tax}.php → taxonomy.php → archive.php → index.php
|
+-- Is it an author archive?
| author-{nicename}.php → author-{ID}.php → author.php → archive.php → index.php
|
+-- Is it a date archive?
| date.php → archive.php → index.php
|
+-- Is it search results?
| search.php → index.php
|
+-- Is it a 404?
404.php → index.phpMatrice de Décision : Quand Utiliser Quelle Approche de Personnalisation
| Scénario | Approche Recommandée | À Éviter |
|---|---|---|
| Remplacer une catégorie spécifique | Créer category-{slug}.php dans le thème | Modifier archive.php directement |
| Remplacer une page spécifique | Créer page-{slug}.php ou utiliser l’en-tête de modèle personnalisé | Modifier page.php |
| Modifier un modèle WooCommerce | Copier dans le répertoire theme/woocommerce/ | Modifier les fichiers du plugin |
| Modifier un modèle de thème parent | Créer un fichier identique dans le thème enfant | Modifier les fichiers du thème parent |
| Appliquer une logique à plusieurs types de pages | Utiliser des balises conditionnelles dans un modèle partagé | Dupliquer le code entre les modèles |
| Injecter des modèles depuis un plugin | Utiliser le filtre _{$type}_template_hierarchy | Coder en dur les chemins dans les fichiers de thème |
| Remplacer tout modèle en dernier recours | Utiliser le filtre template_include | Utiliser exit() ou die() dans les modèles |
| Personnalisation de thème bloc | Utiliser l’Éditeur de Site ou les fichiers HTML templates/ | Mélanger des modèles PHP et HTML blocs |
Points Techniques Clés à Retenir
index.phpest obligatoire. Chaque thème doit l’inclure. C’est le repli universel qui termine chaque chaîne de résolution.singular.phpest la couche intermédiaire sous-utilisée. Il intercepte tout article ou page unique lorsque nisingle.phpnipage.phpn’existe. Utilisez-le dans les thèmes minimaux pour réduire le nombre de fichiers.front-page.phpremplace tout pour la page d’accueil, quels que soient les paramètres de Lecture. S’il existe, il se charge — toujours.- Les noms de fichiers sont sensibles à la casse sur les serveurs Linux.
Category-News.phpne correspondra pas lorsque WordPress recherchecategory-news.php. C’est un échec silencieux difficile à déboguer sans Query Monitor. - Le filtre
template_includeest le remplacement maître. Il se déclenche après que toute la résolution de la hiérarchie est terminée et vous donne une dernière opportunité de remplacer n’importe quel modèle pour n’importe quelle raison. - Les thèmes blocs stockent les modèles en HTML, pas en PHP. La logique de hiérarchie est identique, mais le format de fichier et la structure de répertoire diffèrent fondamentalement des thèmes classiques.
- Le
functions.phpdu thème enfant se charge en plus de celui du parent, et non à sa place. Tous les autres fichiers de modèles suivent le modèle de remplacement standard. - Le réglage d’OPcache est important à grande échelle. Sur les sites à fort trafic, assurez-vous que
opcache.max_accelerated_filesdépasse le nombre total de fichiers PHP dans votre installation WordPress, y compris tous les modèles de thèmes. - Les modèles WooCommerce se trouvent en dehors de la hiérarchie WordPress. Ils nécessitent un flux de remplacement séparé via le sous-répertoire
woocommerce/dans votre thème. - Associez votre travail de personnalisation de modèles à un domaine correctement configuré et à un Enregistrement de Domaine pour garantir la cohérence des URL canoniques sur toutes les pages rendues par les modèles.
FAQ
Que se passe-t-il si WordPress ne trouve aucun fichier de modèle dans la hiérarchie ?
WordPress trouve toujours index.php car il est requis pour chaque thème valide. Si index.php est manquant, WordPress génère une erreur fatale et affiche une page blanche ou une erreur serveur. C’est le seul fichier de modèle dont l’absence casse entièrement le site.
Puis-je utiliser la hiérarchie de modèles dans un plugin sans modifier le thème actif ?
Oui. Utilisez le filtre _{$type}_template_hierarchy pour ajouter un chemin de répertoire de plugin au début du tableau des candidats avant que locate_template() ne s’exécute, ou utilisez template_include pour remplacer le chemin du modèle résolu après la résolution. C’est ainsi que WooCommerce, bbPress, et la plupart des plugins majeurs injectent leurs propres modèles sans nécessiter de modifications du thème.
Pourquoi front-page.php remplace-t-il mon index de blog même lorsque j’ai défini « Vos derniers articles » dans les paramètres de Lecture ?
Parce que front-page.php a une priorité inconditionnelle pour la page d’accueil dans toutes les configurations de Lecture. Si vous souhaitez que l’index du blog utilise home.php à la place, renommez ou supprimez front-page.php de votre thème. À l’intérieur de front-page.php, utilisez is_home() pour détecter si la page d’accueil est également l’index du blog et effectuer le rendu en conséquence.
Comment puis-je savoir quel fichier de modèle WordPress utilise actuellement pour une page spécifique ?
Installez le plugin Query Monitor. Il affiche le chemin du modèle résolu et la hiérarchie complète des candidats dans la barre d’outils d’administration à chaque chargement de page. Alternativement, ajoutez un filtre template_include temporaire qui affiche le chemin sous forme de commentaire HTML visible uniquement par les administrateurs.
La hiérarchie de modèles fonctionne-t-elle de la même façon dans WordPress Multisite ?
La logique de résolution par site est identique. Chaque site résout les modèles par rapport à son propre thème actif. La différence se situe au niveau du réseau : les plugins activés au niveau du réseau peuvent utiliser des hooks de filtre pour injecter des modèles partagés sur tous les sites, et la fonction get_stylesheet_directory() retourne le chemin correct pour le thème actif de chaque site individuel, et non un chemin réseau partagé.
