Ce que post_content contient réellement quand un gabarit est enregistré en base

wp post list --post_type=wp_template --field=post_title — cette commande WP-CLI révèle une chose que beaucoup de développeurs découvrent tardivement : dès qu’un template de bloc est modifié depuis l’éditeur de site, WordPress ne touche jamais le fichier .html correspondant dans le thème. Il crée à la place une entrée dans la table wp_posts, de type wp_template, qui devient la source de vérité tant qu’elle existe.

Définition : un post comme un autre, presque

Un gabarit modifié en base reste, structurellement, un article WordPress ordinaire : il possède un ID, un post_title, un post_status, et surtout un post_content qui contient l’intégralité du balisage de blocs du template, exactement comme le post_content d’un article classique contient le contenu rédactionnel. Ce qui distingue un wp_template d’un article, c’est essentiellement son type de contenu et une colonne post_name qui reprend le nom du fichier d’origine, sans son extension.

Fonctionnement interne : ce que contient vraiment post_content

Le contenu stocké reprend fidèlement la syntaxe des commentaires de bloc, identique à celle qu’on retrouve dans le fichier .html source du thème. Une modification simple, comme l’ajout d’un paragraphe dans le pied de page, se traduit par un post_content qui ressemble à ceci :

<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->
<!-- wp:group {"layout":{"type":"constrained"}} -->
<div class="wp-block-group">
  <!-- wp:paragraph -->
  <p>Mentions ajoutées depuis l'éditeur</p>
  <!-- /wp:paragraph -->
</div>
<!-- /wp:group -->

La colonne post_name vaut ici le slug du template modifié, par exemple single ou archive, ce qui permet à WordPress de savoir quel fichier du thème ce gabarit remplace. La colonne post_type vaut wp_template, et un champ de méta associé, wp_theme, précise à quel thème actif ce gabarit se rattache — un même slug de template peut ainsi coexister, en base, pour plusieurs thèmes installés successivement sur le site.

Ordre de priorité entre fichier et base

Quand un gabarit existe à la fois sous forme de fichier dans le thème et sous forme d’entrée en base pour ce même thème, WordPress privilégie systématiquement la version en base pour le rendu. Le fichier du thème redevient la référence uniquement si l’entrée en base est supprimée, via l’option « Effacer les personnalisations » proposée dans l’éditeur de template.

Cas d’usage : comprendre une divergence inattendue

Ce mécanisme explique un scénario fréquent en reprise de projet : un développeur modifie le fichier page.html du thème, déploie la modification, et ne voit aucun changement sur le site. La cause la plus probable n’est pas un problème de cache, mais l’existence d’une entrée wp_template en base qui masque désormais le fichier modifié. Une requête simple permet de vérifier cette hypothèse avant de chercher plus loin :

wp post list --post_type=wp_template --post_status=publish --field=post_name

Pièges à connaître

• déployer un thème modifié sans vérifier les gabarits déjà personnalisés en base revient à déployer un changement qui, pour le visiteur, ne se produira jamais ;
• supprimer une entrée wp_template en pensant « nettoyer » la base revient à effacer toutes les personnalisations du client sur ce gabarit, sans possibilité de restauration simple hors de l’historique de révisions ;
• oublier que chaque révision d’un gabarit modifié génère elle aussi une entrée en base, de statut inherit, ce qui peut faire gonfler la table wp_posts sur un site où les templates sont retouchés fréquemment.

Avant tout déploiement d’un thème modifié, nous listons désormais les gabarits personnalisés en base sur l’environnement de destination : c’est la seule façon de savoir, à l’avance, si le changement sera visible ou silencieusement masqué.

Ce qu’il faut retenir

Le fichier .html d’un template de bloc n’est qu’un point de départ, pas une garantie de ce qui s’affiche réellement sur un site en production. Tant qu’aucune modification n’a été enregistrée en base pour ce gabarit, le fichier fait foi ; dès qu’une modification existe, post_content devient la seule source fiable, indépendamment de ce que contient le dépôt de code du thème.