# Un thème classique et son dossier /patterns : pourquoi certains manquent

> Cinq fichiers ajoutés dans le dossier /patterns d'un thème classique, mais seuls trois motifs apparaissent dans l'inserteur de blocs : la cause tient à un en-tête mal renseigné.

- Auteur : Clément Hadrot
- Publié le : 2025-08-05
- Mis à jour le : 2025-08-05
- Catégorie : Thèmes
- URL : https://wpmoderne.dev.wordpress-developpement.fr/themes/theme-classique-dossier-patterns-pourquoi-certains-manquent/

## L’essentiel

- Depuis WordPress 6.0, tout thème actif peut enregistrer des motifs depuis un simple dossier /patterns
- Un en-tête sans le champ Title suffit à faire disparaître un motif sans message d'erreur
- Le fichier reste lisible par PHP, mais invisible pour l'API des motifs

Cinq fichiers déposés dans le dossier `/patterns` d'un thème classique, trois motifs seulement visibles dans l'inserteur de blocs de l'éditeur : ce genre de décalage, sans message d'erreur ni notice PHP, déroute même une équipe habituée aux blocs. Le thème reste actif, le site fonctionne normalement, et pourtant deux motifs restent invisibles comme s'ils n'existaient tout simplement pas.

Ce mécanisme d'enregistrement automatique des motifs depuis un dossier ne dépend pas de l'ancienneté du thème : il fonctionne pour tout thème actif, classique ou bloc, depuis WordPress 6.0. Le problème rencontré ici ne concerne donc pas un thème trop vieux pour supporter cette fonctionnalité, mais un détail de formatage propre aux fichiers de motifs eux-mêmes.

## Symptôme : des fichiers présents, des motifs absents de l'inserteur

Chaque fichier PHP placé dans `/patterns` devrait, en théorie, apparaître automatiquement comme motif disponible dans l'éditeur de blocs, sans appel manuel à `register_block_pattern()`. Sur ce projet, les fichiers étaient bien présents sur le serveur, correctement nommés, et ne généraient aucune erreur PHP au chargement du thème. Pourtant, deux d'entre eux n'apparaissaient jamais dans la liste des motifs proposés à l'insertion.

- Aucune notice ni avertissement dans les journaux d'erreurs PHP.
- Le fichier s'exécute normalement si on l'inclut manuellement, sans erreur de syntaxe.
- Les autres motifs du même dossier, eux, s'enregistrent normalement.

## Diagnostic : l'en-tête du fichier, pas son contenu

Chaque fichier du dossier `/patterns` doit débuter par un commentaire d'en-tête au format spécifique, comparable à celui d'un fichier de thème ou d'extension, qui déclare les métadonnées du motif :

```
<?php
/**
 * Title: Bloc d'accroche avec image
 * Slug: mon-theme/accroche-image
 * Categories: featured
 */
?>
<!-- wp:group {"layout":{"type":"constrained"}} -->
...
```

Sur les deux fichiers fautifs, le champ `Title` était absent de l'en-tête, remplacé par une simple description en commentaire classique sans les deux-points attendus après le mot-clé. Or ce champ est le seul strictement obligatoire pour qu'un motif soit reconnu par l'API d'enregistrement automatique : sans lui, WordPress ignore silencieusement le fichier, sans lever la moindre erreur, puisqu'il considère simplement qu'aucun en-tête de motif valide n'a été trouvé.

> L'essentiel à retenir : Depuis WordPress 6.0, tout thème actif peut enregistrer des motifs depuis un simple dossier /patterns ; Un en-tête sans le champ Title suffit à faire disparaître un motif sans message d'erreur ; Le fichier reste lisible par PHP, mais invisible pour l'API des motifs

## Le rôle du champ Slug, souvent confondu avec le champ obligatoire

Le champ `Slug`, à tort, est parfois perçu comme le champ indispensable, sans doute parce qu'il détermine l'identifiant unique du motif. En réalité, s'il est absent, WordPress en génère un automatiquement à partir du nom de fichier et du nom du thème. C'est `Title`, seul, qui conditionne l'enregistrement du motif : son absence bloque tout, y compris si `Slug` est correctement renseigné.

## Correctif : compléter l'en-tête, fichier par fichier

1. Ouvrir chaque fichier du dossier `/patterns` qui n'apparaît pas dans l'inserteur.
2. Vérifier la présence exacte du champ `Title:`, avec les deux-points et un espace, dans le bloc de commentaire d'en-tête.
3. Ajouter le champ manquant, puis recharger l'éditeur de blocs : aucune commande WP-CLI ni vidage de cache spécifique n'est nécessaire, l'enregistrement se fait à chaque chargement.

## Prévention : un gabarit d'en-tête commun à l'équipe

Pour éviter que ce détail ne se reproduise à chaque nouveau motif ajouté par un développeur différent, un fichier gabarit vide, avec l'en-tête complet déjà présent, évite l'oubli. Une simple copie du gabarit avant modification du contenu garantit que le champ obligatoire ne soit jamais omis :

```
<?php
/**
 * Title: À renommer
 * Slug: mon-theme/a-renommer
 * Categories: text
 * Description:
 * Keywords:
 */
?>
```

> Un motif absent sans erreur n'est presque jamais un bug du cœur de WordPress : c'est un en-tête de fichier qui ne respecte pas exactement le format attendu, souvent à un seul mot-clé près.

## En résumé

La disparition silencieuse d'un motif dans l'inserteur de blocs d'un thème classique s'explique presque toujours par un en-tête incomplet, et particulièrement par l'absence du champ `Title`, seul réellement obligatoire dans ce mécanisme d'enregistrement automatique. Un gabarit d'en-tête partagé au sein de l'équipe, copié systématiquement avant toute création de nouveau motif, évite cette perte de temps récurrente et invisible dans les journaux d'erreurs.