# taxonomy.php : le gabarit générique de toute taxonomie personnalisée

> Une extension déclare une taxonomie sans que le thème ne prévoie de gabarit dédié. WordPress ne plante pas pour autant : il retombe sur taxonomy.php, un fichier générique trop souvent absent des thèmes.

- Auteur : WordPress Développement
- Publié le : 2026-10-16
- Mis à jour le : 2026-09-30
- Catégorie : Thèmes
- URL : https://www.wpmoderne.fr/themes/taxonomy-php-gabarit-generique-taxonomie-personnalisee/

## L’essentiel

- taxonomy.php affiche l'archive de n'importe quelle taxonomie sans gabarit plus spécifique
- Le nom de la taxonomie et celui du terme permettent d'aller plus loin en spécificité
- Sans ce fichier, l'affichage retombe sur archive.php puis index.php

Une extension qui déclare une taxonomie personnalisée avec `register_taxonomy()` ne fournit jamais son propre gabarit d'affichage : c'est au thème de savoir l'habiller. Quand ce dernier n'a rien prévu de spécifique, l'archive de cette taxonomie ne casse pas pour autant, elle retombe sur un fichier générique trop souvent absent des thèmes classiques : `taxonomy.php`.

## Ce que couvre exactement ce fichier

La hiérarchie de templates réservée aux taxonomies suit un ordre précis. Pour une taxonomie nommée `destination` et un terme `bretagne`, WordPress cherche d'abord `taxonomy-destination-bretagne.php`, puis `taxonomy-destination.php`, puis enfin `taxonomy.php`. Ce dernier fichier n'a besoin de connaître ni le nom de la taxonomie ni celui du terme affiché : il s'appuie sur des fonctions génériques comme `single_term_title()` ou `get_queried_object()` pour afficher le bon intitulé, quel que soit le contexte réel de la requête.

Deux taxonomies bien connues du cœur, la catégorie et l'étiquette, ne passent jamais par ce fichier : elles disposent de leur propre branche de hiérarchie, avec `category.php` et `tag.php`. `taxonomy.php` ne concerne donc que les taxonomies déclarées par un thème ou une extension, jamais les deux taxonomies natives des articles.

## Comportement réel et cas limites

> L'essentiel à retenir : taxonomy.php affiche l'archive de n'importe quelle taxonomie sans gabarit plus spécifique ; Le nom de la taxonomie et celui du terme permettent d'aller plus loin en spécificité ; Sans ce fichier, l'affichage retombe sur archive.php puis index.php

Un cas limite fréquent concerne les taxonomies déclarées avec l'argument `'public' => false` ou sans `'rewrite'` activé : leur archive n'a alors aucune URL publique accessible, et `taxonomy.php` ne se déclenche jamais pour elles, même s'il existe dans le thème. Autre cas limite : une taxonomie partagée entre plusieurs types de contenu (par exemple une taxonomie de destination utilisée à la fois par des articles et par un type personnalisé « circuit ») affiche dans `taxonomy.php` un mélange des deux types de contenu dans la même boucle, ce qui surprend souvent lors des premiers tests si le gabarit ne filtre pas explicitement par `post_type`.

Il faut aussi noter que `taxonomy.php` reçoit exactement la même requête principale que celle affichée normalement par `archive.php` pour les types de contenu personnalisés : la variable globale `$wp_query` contient déjà tous les articles du terme demandé, sans qu'aucune requête additionnelle ne soit nécessaire dans le gabarit lui-même.

## Pièges fréquents en intégration

- Un thème qui ne fournit ni `taxonomy.php` ni `archive.php`, et qui retombe alors sur `index.php` sans que personne ne comprenne pourquoi l'archive de la taxonomie ressemble à la page d'accueil.
- Une condition `is_tax()` ajoutée par précaution dans `archive.php` pour distinguer les taxonomies personnalisées, alors qu'un simple fichier `taxonomy.php` aurait évité cette branche de code entière.
- Un titre de terme affiché en anglais ou avec des balises HTML brutes faute d'utiliser `single_term_title()`, qui échappe correctement le nom du terme contrairement à un accès direct à l'objet du terme.

## Cas concret avec code

Voici un `taxonomy.php` qui affiche le nom et la description du terme, puis la liste des contenus associés, quel que soit le type de contenu concerné :

```
<?php get_header(); ?>

<main id="contenu-taxonomie">
  <header class="archive-header">
    <h1><?php single_term_title(); ?></h1>
    <?php
    $description = term_description();
    if ( ! empty( $description ) ) {
        echo '<div class="archive-description">' . wp_kses_post( $description ) . '</div>';
    }
    ?>
  </header>

  <?php if ( have_posts() ) : ?>
    <?php while ( have_posts() ) : the_post(); ?>
      <article>
        <h2><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h2>
        <?php the_excerpt(); ?>
      </article>
    <?php endwhile; ?>
    <?php the_posts_pagination(); ?>
  <?php else : ?>
    <p>Aucun contenu associé à ce terme pour l'instant.</p>
  <?php endif; ?>
</main>

<?php get_footer(); ?>
```

La fonction `term_description()` récupère automatiquement la description saisie dans l'écran d'édition du terme, indépendamment de la taxonomie concernée.

## Quand ne pas s'arrêter à ce fichier

Dès qu'une taxonomie précise nécessite un affichage vraiment différent des autres, par exemple une grille de vignettes pour une taxonomie de destinations touristiques quand toutes les autres taxonomies s'affichent en simple liste, il vaut mieux créer `taxonomy-destination.php` plutôt que de multiplier les conditions dans `taxonomy.php`. Ce dernier reste pertinent comme filet de sécurité générique, pas comme lieu où empiler des `if ( is_tax( 'destination' ) )` qui finissent par le rendre illisible.

> Un gabarit générique n'a de valeur que tant qu'il reste générique. Dès qu'une taxonomie mérite un traitement à part, mieux vaut lui donner son propre fichier que de charger taxonomy.php de conditions qui ne concernent qu'elle.

Garder ce fichier simple, appuyé sur les fonctions génériques du cœur plutôt que sur des conditions nominatives, évite qu'il ne devienne au fil des extensions installées un empilement de cas particuliers impossible à maintenir.