Le Block Editor Handbook rappelle que la fonction JavaScript registerBlockType et son équivalent PHP register_block_type forment, encore aujourd’hui, le socle de tout bloc Gutenberg. Ce qui a changé depuis la sortie de l’éditeur en décembre 2018, c’est la façon dont ces deux fonctions reçoivent leurs informations. Pendant plusieurs années, il n’existait aucun fichier central : chaque détail du bloc vivait uniquement dans le code qui l’appelait.
Comprendre cette période aide à lire un vieux code sans paniquer, et à mesurer ce que le fichier de métadonnées a réellement résolu. Cet article ne traite pas de la structure actuelle de block.json, déjà largement documentée ailleurs ; il s’attache uniquement à ce qui existait avant, et pourquoi cela posait problème.
Un objet JavaScript complet, et rien d’autre
Avant toute notion de manifeste, un développeur enregistrait un bloc ainsi : un appel à registerBlockType( 'mon-plugin/carte', { ... } ) dans un fichier JavaScript, avec un objet contenant le titre, la catégorie, l’icône, les attributs, et les fonctions edit et save. Rien de tout cela n’existait ailleurs. Le nom du bloc, sa catégorie, son icône : toutes ces informations étaient enfouies dans un bundle JavaScript compilé, invisibles pour PHP sans un travail supplémentaire.
Cette approche fonctionnait très bien pour l’éditeur lui-même, puisque c’est justement du JavaScript qui charge l’interface. Le problème apparaissait dès qu’une autre partie de WordPress avait besoin de connaître l’existence du bloc : le générateur de flux RSS, une extension tierce qui liste les blocs disponibles, ou simplement un script d’administration qui veut savoir si un bloc est actif sur le site.
Ce que l’éditeur devait deviner sans fichier de manifeste
Côté PHP, la fonction register_block_type existait déjà, mais elle demandait alors les mêmes informations, saisies une seconde fois, à la main, dans un tableau associatif PHP. Un développeur consciencieux dupliquait donc le titre, la catégorie et les attributs dans deux langages différents, avec le risque évident de laisser les deux versions diverger au fil des mises à jour.
- Le nom du bloc devait être identique, caractère pour caractère, dans le fichier JS et dans le fichier PHP.
- Les attributs déclarés côté JavaScript pour le rendu client n’étaient pas automatiquement connus de PHP pour un rendu dynamique.
- Aucun outil ne validait la cohérence entre les deux déclarations : l’erreur ne se révélait qu’à l’usage, souvent bien après l’écriture du code.
Le double enregistrement et ses effets de bord
Ce fonctionnement en miroir avait une conséquence concrète : renommer un attribut, par exemple passer de couleurFond à couleur_fond, obligeait à modifier deux fichiers dans deux syntaxes différentes, sans qu’aucun message n’avertisse en cas d’oubli d’un des deux. Le bloc continuait de s’afficher dans l’éditeur, mais le rendu dynamique côté serveur recevait un attribut vide ou une valeur par défaut, silencieusement.
Pour les blocs purement statiques, dont le rendu se limite à la fonction save, ce risque restait limité. Il devenait sérieux dès qu’un bloc utilisait un render_callback PHP, puisque ce dernier lisait alors des attributs déclarés uniquement côté client, sans garantie de correspondance.
Des extensions qui contournaient déjà le problème
Certaines extensions avaient anticipé la difficulté en générant elles-mêmes un tableau PHP à partir d’un fichier de configuration interne, une sorte de manifeste maison avant l’heure. Cette pratique, bien qu’artisanale, préfigurait directement ce que deviendrait block.json une fois généralisé par le cœur de WordPress à partir de la version 5.8, en juillet 2021, après une phase expérimentale dans l’extension Gutenberg dès la fin de l’année 2020.
Les premiers signes d’un besoin de manifeste unique
Avec la multiplication des extensions à blocs, l’équipe cœur a constaté que la duplication manuelle devenait un frein réel à la fiabilité de l’écosystème. Un fichier unique, lu à la fois par PHP et par les outils de build JavaScript, supprimait la duplication à la source : une seule déclaration, deux consommateurs.
Un conseil qui reste valable pour lire du vieux code : si vous tombez sur un bloc sans
block.json, cherchez d’abord les deux appels — JS et PHP — avant de toucher à quoi que ce soit. C’est souvent là que se cache l’incohérence.
En résumé
La période sans fichier de métadonnées n’était pas un simple détail historique : elle imposait une discipline manuelle que peu de projets tenaient sur la durée. Chaque bloc portait le risque d’une désynchronisation entre son enregistrement JavaScript et son enregistrement PHP, un risque qui grandissait avec le nombre de blocs et le nombre de mains qui les maintenaient. Ce constat explique pourquoi block.json s’est imposé aussi vite une fois stabilisé : il ne changeait pas ce qu’un bloc pouvait faire, mais il supprimait une source d’erreurs devenue systémique.
