add_filter( 'hooked_block_types', 'wpm_inserer_bandeau_partenaire', 10, 4 );. Cette ligne, ajoutée en 2023 dans le thème bloc d’un site associatif fédérant plusieurs structures partenaires, insère automatiquement un bandeau de mise en avant après chaque bloc de citation grâce à l’API Block Hooks de WordPress 6.4. Trois semaines après une mise à jour du thème, un partenaire a signalé que ce bandeau avait disparu de plusieurs pages, sans qu’aucune alerte n’ait remonté côté équipe technique.
Ce billet décrit la capture ciblée avec Sentry des erreurs générées par le callback d’insertion automatique de bloc, pour éviter ce type de régression silencieuse. Le monitoring PHP général du site et les autres API de blocs ne sont pas traités ici, ce billet se concentrant sur le mécanisme précis des Block Hooks.
Pourquoi une insertion automatique peut échouer silencieusement
L’API Block Hooks fonctionne en filtrant la liste des blocs à insérer automatiquement autour d’un bloc cible donné, via le filtre hooked_block_types, puis en générant le contenu du bloc inséré via un second filtre, hooked_block_wpm/bandeau-partenaire. Si le callback de génération de ce contenu lève une exception, PHP peut l’attraper silencieusement selon la configuration de gestion d’erreurs du site, et WordPress affiche alors simplement la page sans le bloc concerné, sans message visible pour l’éditeur ni pour le visiteur.
Dans ce cas précis, une mise à jour du thème avait renommé un champ personnalisé utilisé par le callback pour récupérer le nom du partenaire à afficher dans le bandeau, provoquant une erreur de type TypeError lors de l’appel à une fonction de formatage attendant une chaîne de caractères.
Capturer spécifiquement ce callback avec Sentry
Le SDK Sentry PHP, déjà installé pour le monitoring général du site, ne capturait par défaut que les erreurs fatales interrompant le rendu complet de la page. Une erreur localisée dans un callback de filtre, récupérée silencieusement par un bloc try/catch englobant plus large de WordPress, n’atteignait jamais Sentry sans instrumentation spécifique.
add_filter( 'hooked_block_wpm/bandeau-partenaire', function( $bloc_contenu, $bloc_context, $bloc_instance ) {
try {
return wpm_generer_bandeau_partenaire( $bloc_context );
} catch ( \Throwable $exception ) {
\Sentry\captureException( $exception );
return $bloc_contenu; // on ne casse pas le rendu, on log et on continue
}
}, 10, 3 );
Cette instrumentation garantit deux choses : la page continue de s’afficher normalement même en cas d’erreur dans le callback, comportement déjà en place, mais l’erreur remonte désormais explicitement dans Sentry avec la pile d’appel complète, plutôt que de disparaître sans trace.
Enrichir le contexte de l’erreur
Une pile d’appel seule ne suffit pas toujours à comprendre pourquoi un callback échoue en production sans se reproduire en local. Le contexte du bloc cible, transmis en second argument du filtre, est ajouté comme donnée supplémentaire à l’événement Sentry avant l’envoi.
- L’identifiant du post concerné est ajouté comme tag Sentry, pour identifier immédiatement quelle page a déclenché l’erreur.
- Le nom du champ personnalisé attendu par le callback est ajouté en contexte additionnel, ce qui a permis, dans ce cas précis, d’identifier en quelques minutes le renommage de champ à l’origine du problème.
- Une règle d’alerte Sentry dédiée à ce tag précis notifie l’équipe dès la première occurrence, contrairement au seuil plus élevé utilisé pour les erreurs générales du site.
Pourquoi ne pas simplement faire planter la page
Une alternative aurait consisté à laisser l’exception remonter et interrompre le rendu de la page en cas d’échec du callback, rendant l’erreur immédiatement visible. Cette option a été écartée : un bandeau manquant est une dégradation mineure, acceptable temporairement, alors qu’une page blanche pour tous les visiteurs aurait été une régression bien plus grave pour un simple problème d’affichage secondaire.
Un mécanisme qui échoue proprement doit échouer bruyamment quelque part, même si ce n’est pas devant les yeux du visiteur.
Notre verdict
L’API Block Hooks, pratique pour garantir la présence systématique d’un bloc autour d’un contenu donné, hérite d’un défaut discret : ses points d’échec ne remontent pas naturellement dans les canaux de monitoring habituels d’un site. Toute utilisation en production de cette API mériterait, par précaution, une instrumentation Sentry équivalente à celle décrite ici, pour éviter qu’une régression fonctionnelle mineure ne passe inaperçue pendant plusieurs semaines avant qu’un partenaire ou un client ne la signale lui-même.
