Un bloc de galerie photo développé nativement affichait, par intermittence, un style de bordure qui ne lui appartenait pas. Pas à chaque chargement de page, pas sur toutes les pages contenant le bloc — un comportement erratique qui a fait perdre un temps considérable avant qu’un simple grep sur le nom des handles de scripts ne révèle la cause réelle.
Le projet mêlait des blocs ACF (déclarés via acf_register_block_type) et des blocs natifs enregistrés via block.json, développés à des périodes différentes par des personnes différentes, sans convention de nommage partagée entre les deux approches.
Le symptôme : un style qui apparaît sans raison apparente
Le bloc de galerie affichait par moment une bordure orange épaisse, un style qui appartenait en réalité à un bloc ACF d’alerte développé plus tôt sur le projet. Les deux blocs n’avaient a priori aucun lien : des fichiers différents, des dossiers différents, aucune référence croisée dans le code.
Le comportement intermittent — un indice important — orientait vers un problème d’ordre de chargement plutôt que vers une erreur de code systématique, ce qui a permis d’exclure rapidement une faute de syntaxe CSS classique.
Diagnostic : deux handles identiques
Les deux blocs enregistraient chacun leur feuille de style avec wp_register_style(), mais sous un handle presque identique, différant d’un seul caractère de casse :
// Bloc ACF (alerte)
wp_register_style( 'wpm-bloc-style', get_theme_file_uri( 'blocks/alerte/style.css' ) );
// Bloc natif (galerie), déclaré dans block.json
"style": "wpm-bloc-style"
WordPress ne considère qu’un seul style par handle : le second enregistrement écrase silencieusement le premier, sans avertissement. Selon l’ordre de chargement des deux blocs sur la page, c’était tantôt la bordure orange, tantôt le style de galerie qui l’emportait — d’où le caractère apparemment aléatoire du bug.
Vérifier l’hypothèse avant de corriger
La commande suivante, exécutée à la racine du thème, a confirmé la collision en quelques secondes :
grep -rn "wpm-bloc-style" --include="*.php" --include="*.json" .
Deux résultats, dans deux dossiers de blocs différents, ont suffi à confirmer le diagnostic sans ambiguïté.
Corriger avec un préfixe systématique
Le correctif consiste à préfixer chaque handle avec le nom du bloc lui-même, une convention simple à appliquer une fois pour toutes sur l’ensemble du projet :
// Bloc ACF (alerte)
wp_register_style( 'wpm-alerte-style', get_theme_file_uri( 'blocks/alerte/style.css' ) );
// Bloc natif (galerie)
"style": "wpm-galerie-style"
Étendre la vérification à tout le projet
- Lister tous les handles de scripts et de styles déclarés dans le projet, avec un script shell simple qui parcourt les fichiers
block.jsonet les appelswp_register_script/wp_register_style. - Adopter un préfixe unique par projet (initiales du client, nom du thème) plutôt qu’un préfixe générique partagé par toutes les extensions maison.
- Documenter la convention de nommage dans le fichier
READMEdu thème, pour que la prochaine personne qui ajoute un bloc la suive naturellement.
Ce que cet article ne couvre pas
La migration complète des blocs ACF vers une déclaration block.json alignée sur celle des blocs natifs change bien plus de choses que ce seul problème de nommage et mérite un projet à part entière.
En résumé
Un style qui apparaît de façon apparemment aléatoire sur un bloc qui n’a pourtant pas changé mérite presque toujours une vérification des handles de script et de style enregistrés sur le projet. ACF Blocks et blocs natifs cohabitent très bien tant que chacun respecte un espace de nommage qui lui est propre.
