« The block_categories hook was deprecated in WordPress 5.8! Use block_categories_all instead. » Ce message, visible dans le journal des erreurs PHP d’un site fraîchement mis à jour, signale un changement discret mais réel dans l’API des catégories de blocs. Une extension qui enregistrait une catégorie personnalisée via l’ancien filtre continue de fonctionner, mais génère cet avis à chaque chargement de l’éditeur.
Cet article explique ce que change concrètement block_categories_all par rapport à son prédécesseur, et comment migrer un filtre existant sans perdre de fonctionnalité au passage.
Ce que faisait block_categories
Introduit avec l’éditeur de blocs, le filtre block_categories recevait deux arguments : le tableau des catégories existantes, et l’objet WP_Post de l’article en cours d’édition. Cette dépendance à un objet article posait un problème dès l’arrivée de l’éditeur de site (FSE) dans WordPress 5.8 : dans ce contexte, il n’existe pas nécessairement d’article associé, puisqu’on édite un gabarit ou une partie de gabarit.
Ce qui change avec block_categories_all
Le nouveau filtre reçoit, en second argument, une instance de WP_Block_Editor_Context plutôt qu’un simple objet WP_Post. Ce contexte reste exploitable dans tous les écrans qui chargent l’éditeur de blocs, avec ou sans article associé :
add_filter( 'block_categories_all', function( $categories, $context ) {
$categories[] = [
'slug' => 'mon-extension',
'title' => 'Mon extension',
'icon' => null,
];
return $categories;
}, 10, 2 );
Le format du tableau retourné n’a pas changé : chaque catégorie reste un tableau associatif avec les clés slug, title et icon. Seul le second argument de la fonction de rappel diffère.
Migrer un filtre existant
La migration se résume, dans l’immense majorité des cas, à remplacer le nom du filtre et à adapter, si besoin, l’accès à l’article en cours :
// avant, avec WP_Post directement
add_filter( 'block_categories', function( $categories, $post ) {
if ( $post && 'produit' === $post->post_type ) {
// ...
}
return $categories;
}, 10, 2 );
// après, avec le contexte d'édition
add_filter( 'block_categories_all', function( $categories, $context ) {
if ( $context->post && 'produit' === $context->post->post_type ) {
// ...
}
return $categories;
}, 10, 2 );
La propriété $context->post remplace directement l’ancien second argument, avec l’avantage de rester vide et exploitable (sans erreur) dans l’éditeur de site, là où l’ancien filtre recevait un objet potentiellement inattendu.
Pourquoi ce changement était nécessaire
- L’éditeur de site introduit des écrans d’édition sans article associé : gabarits, parties de gabarit, styles globaux.
- Un filtre qui présuppose la présence d’un
WP_Postvalide plante ou se comporte de façon imprévisible dans ces écrans. WP_Block_Editor_Contextdevient le point de passage commun à plusieurs filtres liés à l’éditeur, pas seulement aux catégories.- Le même schéma de migration s’applique à
allowed_block_types, devenuallowed_block_types_allà la même période.
Faut-il garder une rétrocompatibilité ?
Une extension diffusée largement, encore utilisée sur des sites qui n’ont pas mis à jour WordPress au-delà de la version 5.7, peut avoir intérêt à enregistrer les deux filtres en parallèle, avec une condition sur la version de WordPress détectée via get_bloginfo( 'version' ). Pour un site interne dont l’infrastructure est maîtrisée, migrer directement vers block_categories_all suffit, sans code de compatibilité supplémentaire.
Sur nos extensions diffusées à plusieurs clients, on garde l’ancien filtre en parallèle pendant une période de transition, avec un commentaire daté qui rappelle quand le supprimer définitivement.
En résumé
Le passage de block_categories à block_categories_all illustre un mouvement plus large amorcé par WordPress 5.8 : remplacer les filtres liés à l’éditeur qui dépendaient d’un article précis par des équivalents capables de fonctionner aussi dans l’éditeur de site. La migration reste simple, mais ignorer l’avis de dépréciation revient à accumuler une dette technique facile à éviter dès aujourd’hui.
