# Le fallback d’archive silencieux : quand un CPT retombe sur index.html

> Sans fichier archive dédié, un CPT retombe discrètement sur le gabarit générique du thème, sans erreur visible. Méthode pour le repérer avant la mise en ligne.

- Auteur : Clément Hadrot
- Publié le : 2024-05-21
- Mis à jour le : 2024-05-21
- Catégorie : FSE
- URL : https://wpmoderne.dev.wordpress-developpement.fr/fse/cpt-archive-fallback-index-html/

## L’essentiel

- Sans archive-{cpt}.html, WordPress retombe sur archive.html puis index.html
- Aucune erreur ne signale ce repli, seul l'affichage trahit le problème
- Une checklist de vérification avant mise en ligne évite la mauvaise surprise

Un client éditeur avait fait développer un type de contenu personnalisé « Études de cas » pour son site en éditeur de site, avec un gabarit d'archive spécifique montrant une grille de vignettes. Trois semaines après la mise en ligne, il m'a signalé que la page listant les études de cas ressemblait à un article de blog classique, avec du texte empilé verticalement, sans grille ni vignette.

Aucune erreur PHP, aucun message dans la console, le site fonctionnait « normalement » du point de vue technique. C'est précisément ce genre de repli silencieux qui rend ce type de bug difficile à repérer avant qu'un client ne le signale.

## Symptôme : une archive qui ressemble au mauvais gabarit

La page `/etudes-de-cas/` affichait bien la liste des contenus du CPT, avec pagination fonctionnelle, mais avec la mise en page du blog standard du site plutôt que la grille de cartes prévue par la maquette. Rien ne permettait, à l'œil, de deviner immédiatement que le problème venait d'un gabarit manquant plutôt que d'un bug de CSS.

## Diagnostic : la hiérarchie de templates fait son travail, silencieusement

> L'essentiel à retenir : Sans archive-{cpt}.html, WordPress retombe sur archive.html puis index.html ; Aucune erreur ne signale ce repli, seul l'affichage trahit le problème ; Une checklist de vérification avant mise en ligne évite la mauvaise surprise

La hiérarchie de templates de WordPress, valable aussi bien pour les thèmes classiques que pour les thèmes blocs, prévoit une chaîne de repli précise pour les archives de types de contenu personnalisés. Pour un CPT nommé `etude_cas`, l'ordre de recherche est le suivant :

```
archive-etude_cas.html
archive.html
index.html
```

Dans ce dossier de gabarits, seul `archive.html` existait, hérité d'un thème parent générique, et affichait donc la liste des études de cas avec la mise en page du blog. Le fichier `archive-etude_cas.html`, censé exister d'après le cahier des charges initial, n'avait en réalité jamais été créé : le prestataire précédent avait développé le CPT côté PHP, avec `register_post_type()` et l'argument `has_archive` correctement défini à `true`, mais avait oublié l'étape de création du gabarit dédié dans l'éditeur de site.

```
register_post_type( 'etude_cas', array(
    'public'      => true,
    'has_archive' => true,
    'show_in_rest' => true,
    'supports'    => array( 'title', 'editor', 'thumbnail', 'custom-fields' ),
    'labels'      => array( 'name' => __( 'Études de cas', 'client-theme' ) ),
) );
```

Le code PHP était donc parfaitement correct. C'est l'absence du fichier de gabarit côté éditeur de site qui provoquait le repli, sans qu'aucun message n'alerte qui que ce soit du problème.

## Correctif : créer le gabarit dédié et vérifier son association

La correction s'est faite en trois étapes depuis l'éditeur de site : ajout d'un nouveau template via **Apparence > Éditeur > Modèles > Ajouter un nouveau modèle**, sélection du type « Archive » puis du CPT `etude_cas` dans la liste proposée, et enfin reconstruction de la grille de cartes avec un bloc Query Loop configuré sur ce type de contenu précis.

Une fois le fichier `archive-etude_cas.html` présent dans le dossier `templates` du thème, WordPress l'a immédiatement priorisé sans configuration supplémentaire, conformément à la hiérarchie native.

## Méthode pour repérer ce piège avant la mise en ligne

Depuis cet incident, j'ai ajouté une vérification systématique à ma checklist de recette pour tout projet impliquant des CPT :

1. Lister tous les CPT publics du projet via `wp post-type list --public=true --field=name`.
2. Pour chacun, vérifier dans **Apparence > Éditeur > Modèles** qu'un gabarit spécifique existe, et pas seulement un gabarit générique hérité.
3. Visiter physiquement l'URL d'archive de chaque CPT en environnement de recette, capture d'écran à l'appui pour la validation client.

### Un outil de vérification en une commande

Pour accélérer cette vérification sur des projets à nombreux CPT, un petit script WP-CLI personnalisé liste désormais les CPT publics et vérifie la présence du fichier de gabarit correspondant dans le dossier `templates` du thème actif, avant chaque mise en production :

```
wp eval '
foreach ( get_post_types( array( "public" => true, "_builtin" => false ) ) as $cpt ) {
    $path = get_stylesheet_directory() . "/templates/archive-{$cpt}.html";
    echo $cpt . " : " . ( file_exists( $path ) ? "OK" : "MANQUANT" ) . PHP_EOL;
}
'
```

> Un CPT sans gabarit d'archive dédié ne provoque jamais d'erreur visible : il se contente d'hériter silencieusement du gabarit générique le plus proche. C'est précisément ce silence qui en fait un piège de recette classique.

## En résumé

La hiérarchie de templates de WordPress est une mécanique fiable, mais son silence en cas de gabarit manquant peut faire passer un problème de configuration pour un bug esthétique mineur. Vérifier systématiquement l'existence des gabarits d'archive dédiés pour chaque CPT avant la mise en ligne, plutôt que de se fier à l'absence d'erreur, reste la meilleure garantie contre ce type de repli silencieux.