has_block WordPress : guide complet pour les développeurs

Introduction

Dans l’écosystème WordPress moderne, largement dominé par l’éditeur de blocs (Gutenberg), la fonction has_block joue un rôle essentiel pour contrôler l’affichage conditionnel et optimiser les performances d’un site. Cette fonction native permet de savoir si un contenu (article, page, contenu brut) contient un type de bloc donné, comme un bloc galerie, image, paragraphe, titre ou un bloc personnalisé. En comprenant précisément le fonctionnement de has_block, sa signature officielle, ses limites et les alternatives plus avancées introduites récemment, vous pourrez construire des thèmes et plugins plus robustes, flexibles et performants.

Ce guide détaille en profondeur l’utilisation de has_block dans WordPress, en corrigeant les approximations fréquentes, en présentant les bonnes pratiques de développement et en intégrant les nouveautés du cœur WordPress jusqu’à la version 6.9. Vous y trouverez des explications claires, des exemples concrets, ainsi que des conseils pour intégrer cette fonction dans vos templates, hooks et logiques métier.

Qu’est-ce que la fonction has_block dans WordPress ?

has_block est une fonction PHP du cœur de WordPress qui permet de déterminer si un contenu donné contient un bloc spécifique. Elle est intimement liée à l’éditeur de blocs introduit à partir de WordPress 5.0 et fait partie intégrante de l’API de blocs.

Concrètement, has_block analyse un contenu (post, page, custom post type ou chaîne de texte brute) et renvoie une valeur booléenne :

• true si le bloc spécifié est trouvé dans le contenu analysé ;
• false si aucun bloc correspondant n’est détecté.

Cette fonction est donc particulièrement utile pour :

• appliquer un rendu conditionnel dans un thème (par exemple, n’afficher un script ou une feuille de style que si un bloc précis est présent) ;
• modifier la structure de la page selon les blocs utilisés dans l’éditeur ;
• adapter le comportement d’un plugin en fonction de la présence ou non de certains blocs ;
• optimiser les performances enévitant de charger des ressources inutiles lorsque des blocs spécifiques ne sont pas utilisés.

Signature officielle et paramètres de has_block

La signature de has_block a parfoisété mal citée dans la documentation non officielle. Pourêtre à jour avec le cœur WordPress récent (jusqu’à la série 6.9), la signature correcte est :

has_block( string $block_name, $post = null );

Voici le détail de chaque paramètre :

• $block_name (string, obligatoire) : le nom complet du bloc recherché. Exemples courants :
  • 'core/paragraph' pour un paragraphe ;
  • 'core/heading' pour un titre ;
  • 'core/gallery' pour une galerie ;
  • 'core/image' pour une image ;
  • 'mon-plugin/mon-bloc-personnalise' pour un bloc personnalisé.
• $post (optionnel) : ce paramètre accepte plusieurs types de valeurs :
  • un ID de post (int) ;
  • un objet WP_Post ;
  • une chaîne de contenu brut (string), par exemple du HTML comportant des commentaires de blocs ;
  • null : dans ce cas, WordPress utilisera le post global courant (la variable $post issue de la boucle).

Il est donc inexact de limiter le second paramètre à une simple chaîne de contenu ou à un objet WP_Post uniquement. La souplesse de ce paramètre rend has_block particulièrement pratique à utiliser dans divers contextes (templates, hooks, filtres, etc.).

Valeur de retour et comportement réel de has_block

La valeur de retour de has_block est un booléen pur :

• true si le bloc spécifié par $block_name est détecté dans le contenu analysé ;
• false sinon.

Cependant, un point est souvent mal compris : ce test ne vise pas une exactitude structurelle parfaite, mais un compromis entre performance et précision. Sous le capot, has_block s’appuie sur un mécanisme similaire à has_blocks et sur une détection de motifs dans les commentaires de blocs () plutôt que sur une validation complète de la structure HTML de chaque bloc.

En pratique, cela signifie :

• le test est très performant et adapté à une utilisation fréquente (par exemple dans un template de thème) ;
• il est suffisamment fiable pour la plupart des cas d’usage courants ;
• il n’est pas conçu pour faire une analyse structurelle fine (par exemple la profondeur exacte de chaque bloc ou la validation d’attributs complexes).

Pour la quasi-totalité des besoins de thème et de plugin, ce compromis est largement suffisant. Pour les cas d’analyse plus avancés, WordPress met maintenant à disposition des outils plus spécialisés, que nous verrons plus loin.

has_block et l’évolution de l’éditeur de blocs dans WordPress

La fonction has_block est apparue avec l’éditeur de blocs (Gutenberg) introduit dans WordPress 5.0. Depuis, l’éditeur a fortementévolué, notamment avec l’arrivée des thèmes basés sur des blocs, de l’édition complète du site (Full Site Editing) et de nombreuses améliorations de performance.

Dans ce contexte, has_block reste un pilier pour :

• les développeurs de thèmes classiques souhaitant adapter certaines parties de leurs templates aux blocs utilisés par leséditeurs de contenu ;
• les auteurs de thèmes blocs qui veulent appliquer des comportements spécifiques selon la présence de blocs particuliers dans certaines zones (contenu principal, modèles, parties de modèles) ;
• les développeurs de plugins qui conditionnent le chargement de scripts à l’usage réel d’un bloc (par exemple, charger une librairie de diaporama uniquement si un bloc galerie avancée est présent).

Signature détaillée et typologie du second paramètre

Pouréviter tout malentendu sur la fonction, rappelons précisément les types acceptés par le second paramètre $post :

• ID de post (int) : idéal dans les hooks comme the_content ou lorsque vous travaillez avec un identifiant numérique, par exemple dans une requête personnalisée.
• Objet WP_Post : pratique lorsque vous disposez déj à d’un objet de post complet acquis via get_post ou la boucle WordPress.
• Chaîne de contenu (string) : très utile pour tester des contenus générés dynamiquement, des extraits personnalisés ou des contenus stockés en dehors des posts classiques.
• null : WordPress se rabat alors sur le post global, ce qui convient parfaitement dans la boucle principale ou dans les templates de thème.

Une erreur courante consiste à penser que has_block ne fonctionne que sur le contenu textuel via $post->post_content. En réalité, vous pouvez lui passer directement un ID ou un objet, la fonction se chargeant de récupérer et d’analyser le contenu correspondant lorsque ce n’est pas déj à une chaîne.

Exemples pratiques d’utilisation de has_block

1. Vérifier la présence d’un bloc galerie dans un article

Dans cet exemple, on passe l’ID du post courant à has_block. Si un bloc core/gallery est détecté, un script de lightbox est chargé pour améliorer l’expérience utilisateur sur les galeries.

2. Afficher une mise en page différente si un bloc couverture est utilisé

Ici, aucun second paramètre n’est fourni : has_block utilisera donc le post global (parfait dans un fichier single.php). On adapte la structure de contenu affichée selon la présence d’un bloc couverture.

3. Tester un bloc personnalisé dans une chaîne de contenu brute

Exemple
'; if ( has_block( 'core/paragraph', $content ) ) { echo '
Le contenu contient au moins un paragraphe bloc.
';
}
?>

Ce cas illustre l’utilisation de has_block directement sur une chaîne sans passer par un post enregistré en base. C’est très pratique pour tester des contenus temporaires ou générés à la volée.

4. Charger des styles uniquement si un bloc vidéo est présent

Dans ce cas, la présence d’un bloc vidéo dans le contenu principal conditionne le chargement d’une feuille de style spécifique. Cela contribue à limiter les ressources chargées lorsqu’elles ne sont pas nécessaires.

Limites de has_block et comportement d’analyse

Pour utiliser has_block de manière fiable, il est important de comprendre ses limites :

• Test basé sur des motifs : la fonction recherche principalement la présence de commentaires de blocs au format . Elle ne réalise pas une validation complète de l’HTML.
• Performance prioritaire : le moteur de détection est pensé pourêtre rapide, même sur des contenus longs. Il ne garantit donc pas une précision structurelle parfaite dans tous les cas extrêmes.
• Spécificité du bloc : vous devez fournir le nom exact du bloc. Par exemple, 'gallery' ne correspond pas automatiquement à 'core/gallery'. Il est recommandé d’utiliser systématiquement le nom « namespacé » complet (core/..., plugin/..., etc.).
• Gestion des blocs imbriqués : dans la majorité des cas, les blocs imbriqués restent détectables, mais pour certaines analyses structurelles très fines (comme la position exacte d’un bloc dans un parent spécifique), has_block n’est pas le meilleur outil.

Ces limites ne posent généralement pas de problème pour les usages courants (chargement conditionnel de ressources, affichage conditionnel de sections, etc.), mais elles doiventêtre connues lorsqu’on met en place des logiques complexes basées sur la structure complète d’un document de blocs.

WP_Block_Processor : un outil avancé à partir de WordPress 6.9

Avec WordPress 6.9, le cœur introduce un nouvel outil bas niveau dédié à l’analyse de la structure des blocs : WP_Block_Processor. Cet outil est conçu pour parcourir et analyser un document HTML afin d’en extraire une représentation structurée des blocs.

Contrairement à has_block, qui fournit une simple réponse booléenne, WP_Block_Processor permet :

• de transformer un document HTML comportant des blocs en un tableau imbriqué de blocs ;
• de produire des structures JSON contenant les attributs et la hiérarchie des blocs ;
• de parcourir précisément la structure (blocs parents, enfants, profondeur, ordre, etc.).

Ce processeur est donc particulièrement adapté si vous devez :

• effectuer des analyses structurelles complexes (par exemple, détecter un bloc seulement s’il est enfant d’un autre bloc spécifique) ;
• générer des vues personnalisées de la structure de contenu ;
• mettre en place des migrations de contenu basées sur la hiérarchie des blocs.

En pratique :

• utilisez has_block pour des besoins simples de détection de présence de blocs, avec une excellente performance ;
• utilisez WP_Block_Processor lorsque vous avez besoin d’une compréhension détaillée de la structure complète du document de blocs.

Cas d’usage concrets dans un thème WordPress

Adapter le header ou le footer selon les blocs utilisés

Imaginons un thème qui propose deux types d’en-têtes : un en-tête standard et un en-tête « immersif » lorsqu’un bloc couverture est présent en haut de la page. Vous pouvez utiliser has_block pour déterminer quelle variante charger.

Cette approche permet de garder un code de thème propre, tout en tirant parti de la flexibilité de l’éditeur de blocs.

Afficher un sommaire automatique si des blocs titre sont présents

Pour améliorer l’expérience de lecture, certains thèmes affichent un sommaire automatique lorsqu’un contenu contient suffisamment de titres (blocs core/heading). has_block peut servir de premier filtre rapide avant de lancer une analyse plus complète des en-têtes.

Vous combinez ainsi un test léger et performant avec une analyse plus approfondie uniquement lorsque cela est nécessaire.

Conditionner l’affichage d’une colonne latérale

Certains contenus peuventêtre plus immersifs et se prêter à un affichage pleine largeur. Par exemple, lorsqu’un bloc pleine largeur spécifique ou un certain type de maquette de blocs est utilisé. has_block peut vous aider à déterminer si une sidebar doitêtre affichée.

Ce type de logique améliore la cohérence visuelle du site et l’expérience utilisateur tout en restant simple à maintenir.

Bonnes pratiques de développement avec has_block

Pour tirer pleinement parti de has_block dans vos projets WordPress, voici quelques recommandations :

• Utiliser le nom complet du bloc : évitez les noms raccourcis ou ambigus. Privilégiez systématiquement le format namespace/slug, par exemple core/gallery plutôt que gallery.
• Limiter le nombre d’appels répétés : si vous devez tester plusieurs blocs sur le même contenu dans un même contexte, envisagez de mémoriser les résultats ou d’utiliser un outil d’analyse plus complet plutôt que d’appeler has_block en boucle de manière intensive.
• Prendre en compte le post global : si vous travaillez dans la boucle principale, ne pas passer le second paramètre suffit. Toutefois, dans des hooks pluséloignés ou dans l’admin, passez explicitement un ID ou un objet WP_Post.
• Ne pas l’utiliser pour de la validation stricte : pour des migrations complexes, de la validation de structure ou des transformations profondes, orientez-vous vers WP_Block_Processor ou d’autres fonctions d’analyse de blocs.

Intégration avec d’autres fonctions liées aux blocs

has_block s’inscrit dans un ensemble plus large de fonctions utiles pour travailler avec l’éditeur de blocs et le contenu en blocs. Parmi les plus pertinentes :

• has_blocks : vérifie si un contenu contient au moins un bloc, sans préciser lequel. Très utile pour distinguer rapidement un contenu en blocs d’un contenu « classique ».
• Fonctions de rendu de blocs et parseurs de contenu : permettent d’extraire ou de transformer les blocs en PHP.
• WP_Block_Processor (WordPress 6.9+) : pour un parcours fin de la structure des blocs et la création de structures de données imbriquées ou JSON.

En combinant ces fonctions, vous pouvez construire des expériences très avancées autour du contenu en blocs, allant de simples optimisations d’affichage à des transformations complètes de la structure des pages.

Impact de has_block sur la performance et l’optimisation globale du site

Bien que has_block soit pensé pourêtre performant, il reste important de l’utiliser avec discernement dans un site WordPress à fort trafic :

• Évitez de l’appeler de manière répétée dans des boucles très lourdes sans mise en cache des résultats.
• Utilisez-le de préférence dans des contextes où le contenu est déj à chargé (par exemple dans la boucle) plutôt que d’effectuer des requêtes supplémentaires pour chaque test.
• Combinez-le avec des mécanismes de cache (objet cache, transients, cache de page) lorsque vous mettez en place des logiques complexes basées sur la présence de blocs.

Correctement employée, la fonction contribue à un site mieux optimisé, enévitant des chargements inutiles de ressources et en adaptant l’affichage aux besoins réels du contenuéditorial.

FAQ sur has_block WordPress

La fonction has_block fonctionne-t-elle uniquement avec Gutenberg ?

Oui, has_block est liée à l’éditeur de blocs introduit à partir de WordPress 5.0. Elle détecte les blocs structurés via les commentaires spécifiques . Sur des contenus entièrement anciens (sanséditeur de blocs), la fonction renverra généralement false, sauf si ces motifs sont présents.

Puis-je utiliser has_block dans l’admin WordPress ?

Oui, vous pouvez utiliser has_block aussi bien sur le front-office que dans l’admin, à condition de lui passer un contenu ou un post valide. Par exemple, dans certains hooks d’administration, il est possible de modifier l’interface selon la présence de blocs spécifiques dans un contenu.

Le second paramètre doit-il toujoursêtre une chaîne de contenu ?

Non. Le second paramètre de has_block peutêtre un ID de post, un objet WP_Post, une chaîne de contenu brute ou null. La fonction se charge de récupérer et d’analyser le contenu à partir de ces différentes formes.

has_block est-elle fiable pour une analyse structurelle complète ?

has_block est fiable pour détecter la présence d’un type de bloc, mais elle est optimisée pour la performance plutôt que pour une validation structurelle exhaustive. Pour une analyse détaillée (hiérarchie des blocs, profondeur, relations parent/enfant, etc.), il est préférable d’utiliser WP_Block_Processor ou d’autres outils plus avancés.

Comment vérifier plusieurs types de blocs avec has_block ?

Vous pouvez combiner plusieurs appels à has_block avec des opérateurs logiques. Par exemple :

Pour des tests multiples plus fréquents, réfléchissez à une logique d’analyse plus globale afin d’éviter les appels redondants.

has_block détecte-t-elle les blocs réutilisables ?

Dans un flux standard, les blocs réutilisables sont représentés à travers des blocs spécifiques. Selon le contexte et la manière dont ils sont rendus ou transformés, il peutêtre nécessaire de combiner has_block avec d’autres techniques si vous souhaitez distinguer précisément les blocs réutilisables des autres blocs. Pour des besoins pointus sur ce sujet, une approche basée sur un traitement plus avancé de la structure des blocs sera souvent plus adaptée.

Conclusion

La fonction has_block est un outil incontournable pour tout développeur WordPress travaillant avec l’éditeur de blocs. Correctement comprise et utilisée, elle permet de mettre en place des logiques conditionnelles puissantes, d’optimiser le chargement des ressources et d’adapter finement l’affichage des thèmes et plugins à la réalité du contenuéditorial.

En gardant à l’esprit sa signature officielle (has_block( string $block_name, $post = null )), la variété des types acceptés par le second paramètre, ainsi que son positionnement clair en faveur de la performance plutôt que de l’analyse structurelle exhaustive, vous serez en mesure de l’utiliser de façon fiable et efficace. Pour les besoins d’analyse plus poussés, les outils plus récents comme WP_Block_Processor offrent un complément idéal, permettant d’explorer en profondeur la structure des blocs dans WordPress moderne.