« Les métadonnées de bloc, telles que déclarées dans block.json, peuvent être filtrées avant leur enregistrement via le hook block_type_metadata. » Cette phrase, formulée ainsi dans la documentation du Bloc Editor Handbook, résume exactement le problème que ce filtre résout : adapter le comportement déclaratif d’un bloc, y compris un bloc fourni par une extension tierce, sans toucher à son code source.
Le cas typique : une extension tierce enregistre un bloc utile, mais avec des réglages trop larges (un support d’alignement full non désiré, une catégorie mal choisie, une icône générique) qu’il n’est pas question de corriger en modifiant les fichiers du plugin, puisque la moindre mise à jour effacerait la correction.
Le problème concret
Un bloc d’affichage de témoignages, fourni par une extension de formulaires, s’enregistre avec "align": ["wide", "full"] dans son block.json. Sur un projet où la charte graphique interdit toute image en pleine largeur hors de la zone de contenu principale, ce réglage crée régulièrement des mises en page cassées lorsque des rédacteurs l’utilisent sans le savoir. Forker l’extension pour retirer une ligne de configuration serait disproportionné et fragiliserait la maintenance à chaque mise à jour du plugin d’origine.
Le filtre, en pratique
Le filtre block_type_metadata reçoit le tableau de métadonnées tel qu’il vient d’être lu depuis block.json, juste avant que register_block_type() ne l’utilise pour enregistrer le bloc. Il suffit de repérer le bloc visé par son nom et d’ajuster le tableau :
add_filter( 'block_type_metadata', function ( $metadata ) {
if ( ( $metadata['name'] ?? '' ) !== 'formulaires-pro/temoignages' ) {
return $metadata;
}
// On retire les alignements larges non souhaités sur ce projet.
if ( isset( $metadata['supports']['align'] ) ) {
$metadata['supports']['align'] = false;
}
// On recatégorise le bloc pour qu'il apparaisse avec les autres
// blocs de contenu éditorial plutôt que dans « Formulaires ».
$metadata['category'] = 'text';
return $metadata;
} );
Où placer ce code
Ce filtre doit s’exécuter avant l’enregistrement effectif du bloc concerné, ce qui signifie généralement un accrochage sur init avec une priorité égale ou antérieure à celle utilisée par l’extension cible pour enregistrer ses blocs. En cas de doute sur l’ordre d’exécution, une priorité basse (comme 5) sur le hook init garantit que le filtre est bien en place avant la plupart des enregistrements de blocs standards.
- Placer l’ajout du filtre dans un plugin propre au projet plutôt que dans le thème, pour qu’il survive à un changement de thème.
- Toujours vérifier le nom exact du bloc via
$metadata['name']avant toute modification, pour ne jamais affecter d’autres blocs par erreur. - Retourner systématiquement le tableau, même inchangé, dans la branche par défaut : oublier ce retour casse l’enregistrement de tous les autres blocs du site.
Variantes utiles de ce filtre
Ajouter un attribut supplémentaire à un bloc existant
add_filter( 'block_type_metadata', function ( $metadata ) {
if ( ( $metadata['name'] ?? '' ) === 'formulaires-pro/temoignages' ) {
$metadata['attributes']['noteMoyenne'] = array(
'type' => 'number',
'default' => 0,
);
}
return $metadata;
} );Désactiver un rendu côté serveur pour le remplacer par un autre
Il est également possible de retirer la clé render (ou renderCallback côté PHP après enregistrement, via un filtre distinct sur les block types déjà enregistrés) pour rediriger le rendu vers une fonction propre au projet, à condition de reproduire fidèlement les attributs attendus par le balisage existant.
Ce que ce filtre ne permet pas
Le filtre agit sur les métadonnées déclaratives, pas sur le rendu PHP effectif du bloc ni sur son comportement en JavaScript dans l’éditeur. Modifier la logique de render_callback d’un bloc tiers demande un mécanisme différent, généralement le filtre render_block_data ou render_block, selon que l’on souhaite intervenir avant ou après le calcul du rendu.
En résumé
block_type_metadata offre un point d’ajustement précis et non intrusif pour corriger la déclaration d’un bloc, qu’il vienne d’une extension tierce ou de son propre projet, sans jamais modifier de fichier source. Bien ciblé par nom de bloc et bien priorisé sur init, ce filtre évite le fork complet d’une extension pour un réglage qui, souvent, tient en deux lignes.
