has_action WordPress : guide complet pour maîtriser ce hook d’action

Sommaire de l'article

Introduction

WordPress est une plateforme de CMS (Content Management System) extrêmement populaire pour créer et gérer des sites web de tous types : blogs, sites vitrines, boutiques en ligne, plateformes de formation, etc. Parmi ses mécanismes les plus puissants figurent les hooks, qui permettent de personnaliser et d’étendre les fonctionnalités de base du système sans modifier le noyau (core) de WordPress.

Au cœur de ce système de hooks, la fonction has_action occupe une place importante. Elle permet aux développeurs de vérifier la présence de callbacks (fonctions) accrochés à un hook d’action donné avant d’exécuter du code dépendant de ces actions. Bien utilisée, elle rend votre code plus robuste, plus modulaire et plus compatible avec les thèmes et extensions tiers.

Dans ce guide complet, nous allons détailler le fonctionnement réel de has_action, corriger les idées reçues les plus fréquentes, expliquer sa valeur de retour exacte, ses paramètres, sa version d’apparition, ainsi que ses relations avec d’autres fonctions essentielles comme add_action, do_action, remove_action et has_filter. Vous trouverezégalement de nombreux exemples pratiques d’utilisation et de bonnes pratiques pour vos thèmes et plugins.

Rappel : le rôle des hooks dans WordPress

Qu’est-ce qu’un hook ?

Dans WordPress, les hooks sont des points d’ancrage disséminés dans le code du cœur, des thèmes et des extensions. Ils permettent à d’autres développeurs d’« accrocher » des fonctions personnalisées qui seront exécutées à des moments précis du cycle de vie de WordPress ou lors de certains traitements de données.

On distingue deux grandes familles de hooks :

Les actions : elles permettent d’exécuter du code à des moments précis (chargement de WordPress, affichage du header, enregistrement d’un article, connexion d’un utilisateur, etc.).
Les filtres : ils permettent de modifier des données (titre d’un article, contenu, URL, attributs d’une image, etc.) avant qu’elles ne soient affichées ou stockées.

Cette architecture rend WordPress très extensible : vous pouvez intervenir dans l’exécution du CMS sans jamais toucher au code du noyau. C’est précisément ce qui permet à des milliers de thèmes et de plugins de cohabiter sur un même site.

Qu’est-ce qu’une action dans WordPress ?

Une action est un type de hook qui déclenche l’exécution d’une fonction à un moment précis du cycle de traitement de WordPress. Par exemple :

L’action init est appelée lorsque WordPress est initialisé et prêt à charger la plupart de ses fonctionnalités.
L’action wp_head est exécutée dans la balise d’une page HTML, avant l’affichage du contenu.
L’action wp_footer est exécutée juste avant la fermeture de la balise .

Pour accrocher une fonction à une action, on utilise add_action. Pour déclencher l’exécution de tous les callbacks associés à un hook, on utilise do_action. Ces deux fonctions fonctionnent de pair :


// Accrocher une fonction à l'action 'init'
function mon_plugin_init { // Code de votre plugin
}
add_action( 'init', 'mon_plugin_init' ); // Plus loin dans le core, ou dans un thème / plugin
do_action( 'init' ); // Déclenche toutes les fonctions accrochées à 'init'

Différence entre actions et filtres

Bien que les actions et les filtres soient tous deux des hooks WordPress, ils servent des objectifs distincts :

Actions : utilisées pour exécuter du code à un moment précis. Exemple : envoyer un email après la publication d’un article, charger des scripts dans le header, enregistrer des logs.
Filtres : utilisés pour modifier des données avant leur utilisation. Exemple : filtrer le titre d’un article, changer le contenu d’un widget, adapter une URL.

Cette distinction est essentielle pour comprendre l’usage correct des fonctions associées :

add_action / do_action / has_action pour les actions.
add_filter / apply_filters / has_filter pour les filtres.

Présentation correcte de la fonction has_action

Définition exacte de has_action

La fonction has_action ne sert pas à exécuter un hook ni à tester l’existence « théorique » d’une action dans le cœur de WordPress. Elle a un rôle très précis :

has_action vérifie si au moins une fonction (callback) aété enregistrée sur un hook d’action donné.

Selon les paramètres fournis, elle peut :

Retourner un booléen (true / false).
Retourner un entier correspondant à la priorité de la fonction accrochée.

Elle n’est donc pas limitée à un simple retour booléen, contrairement à ce qu’on lit parfois.

Signature officielle et paramètres

La signature actuelle de la fonction est :


has_action( $tag, $callback = false );

Les paramètres sont les suivants :

$tag (obligatoire) : chaîne de caractères, le nom du hook d’action à vérifier (par exemple 'init', 'wp_head', 'wp_footer', etc.).
$callback (optionnel) : callback (string ou array), la fonction à vérifier sur ce hook. Par défaut, sa valeur est false.

Cette signature est très proche de celle de has_filter, car en interne has_action s’appuie sur le même mécanisme que has_filter.

Version d’introduction dans WordPress

La fonction has_action aété introduite dans WordPress à partir de la version 2.5.0. Cette information est importante pour les développeurs qui doivent gérer la compatibilité avec de très anciennes installations, même si aujourd’hui la plupart des sites utilisent des versions beaucoup plus récentes.

Type de retour de has_action

Une des erreurs les plus fréquentes consiste à affirmer que has_action renvoie toujours un booléen. Ce n’est pas le cas.

Le comportement exact est le suivant :

Quand le paramètre $callback est fourni :
- Si la fonction est trouvée sur le hook, has_action retourne un entier, qui est la priorité de cette fonction.
- Si la fonction n’est pas trouvée, has_action retourne false.
Quand le paramètre $callback n’est pas fourni :
- has_action retourne true si au moins une fonction est enregistrée sur ce hook.
- has_action retourne false si aucune fonction n’est accrochée à ce hook.

En résumé : selon les cas, le type de retour peutêtre booléen ou entier. Il est donc essentiel d’en tenir compte dans vos conditions.

has_action vs « existence d’un hook »

Une autre confusion courante consiste à dire que has_action teste si un hook « existe » dans le cœur de WordPress. En réalité, un hook est simplement une chaîne de caractères passée à do_action ou utilisée par add_action. Il n’y a pas de registre central de tous les hooks « prédéfinis » dans WordPress.

Ce que fait réellement has_action :

Elle vérifie si au moins une fonction de rappel (callback) aété enregistrée sur ce hook via add_action.
Elle ne vérifie pas si le hook est « prévu par WordPress » ou déclaré dans le core.

Autrement dit, vous pouvez appeler has_action( 'mon_hook_personnalise' ) même si ce hook n’est jamais utilisé dans le cœur de WordPress : la fonction se contentera de vérifier si quelqu’un a accroché une callback sur ce nom de hook.

Syntaxe de base et exemples simples

Tester si un hook a au moins une fonction attachée

Pour vérifier si au moins une fonction est enregistrée sur un hook donné, il suffit de passer le nom du hook en premier paramètre et de laisser le second paramètre vide (ou à sa valeur par défaut) :


if ( has_action( 'init' ) ) { // Au moins une fonction est attachée à 'init' // Vous pouvez déclencher un comportement conditionnel ici
}

Dans cet exemple, has_action( 'init' ) renverra true si une ou plusieurs fonctions ontété ajoutées à l’action 'init' via add_action.

Vérifier si une fonction précise est attachée et récupérer sa priorité

Pour savoir si une fonction spécifique est accrochée à une action, et en même temps connaître sa priorité, on fournitégalement le second paramètre :


$priority = has_action( 'init', 'mon_plugin_init' ); if ( $priority ) { // 'mon_plugin_init' est attachée à 'init' // $priority contient la priorité de cette fonction (entier)
} else { // La fonction n'est pas attachée à 'init'
}

Notez que la condition if ( $priority ) fonctionnera car un entier positif seraévalué comme vrai. Si la fonction n’est pas trouvée, has_action renverra false.

has_action dans un workflow WordPress réel

Combinaison avec add_action et remove_action

Dans la pratique, has_action est souvent utilisé en complément de add_action et remove_action pourécrire un code plus défensif et plus modulable.

Exemple : vérifier la présence d’une fonction avant de tenter de la retirer :


// Dans un plugin ou un thème enfant
if ( has_action( 'wp_head', 'mon_theme_affiche_meta' ) ) { remove_action( 'wp_head', 'mon_theme_affiche_meta', 10 );
}

Dans ce cas, has_action vous permet de vérifier que la fonction mon_theme_affiche_meta est bien enregistrée sur le hook wp_head avant de tenter de la supprimer, ce quiévite des suppressions « silencieuses » qui n’ont aucun effet.

Adapter un plugin à un thème ou à un autre plugin

Dans un environnement WordPress, plusieurs plugins et le thème actif peuvent optimiser ou altérer le comportement du site via des hooks. has_action devient alors un outil précieux pour :

Ne pas dupliquer une fonctionnalité si un autre plugin l’a déj à ajoutée.
Modifier le comportement si une action tierce est présente.
Offrir une meilleure compatibilité entre extensions.

Exemple : un plugin de SEO qui n’ajoute un script que si un autre plugin n’a pas déj à accroché sa propre action :


if ( ! has_action( 'wp_head', 'autre_plugin_seo_meta' ) ) { add_action( 'wp_head', 'mon_plugin_seo_meta', 5 );
}

Dans ce cas, le plugin vérifie d’abord si une action concurrente est déj à présente, ce qui améliore la compatibilité etévite de dupliquer des balises meta.

Comportement avancé et pièges courants

Attention au type de retour

Comme expliqué plus haut, le type de retour de has_action n’est pas toujours booléen. Lorsque vous fournissez un callback, la fonction peut renvoyer un entier (priorité). Cela a deux implications importantes :

Une comparaison stricte avec true ou false peut donner des résultats inattendus.
Un simple if ( has_action( 'hook', 'callback' ) ) fonctionne, mais il est bon de savoir qu’en interne la valeur est parfois un entier.

Exemple de code robuste :


$priority = has_action( 'wp_footer', 'afficher_auteur' ); if ( false !== $priority ) { // La fonction est attachée, $priority contient sa priorité
} else { // La fonction n'est pas attachée
}

Ici, on utilise une comparaison stricte avec false pour distinguer clairement l’absence de callback d’une priorité entière retournée par la fonction.

has_action ne retourne pas la liste des fonctions

Une erreur fréquente consiste à penser que has_action renvoie la liste des fonctions accrochées à un hook. Ce n’est pas le cas. Elle se limite à indiquer :

S’il y a au moins un callback accroché à un hook donné (retour booléen).
Ou, si un callback spécifique est passé en paramètre, la priorité de ce callback.

Si vous avez besoin d’auditer en détail toutes les fonctions rattachées à un hook, il faut manipuler la variable globale $wp_filter de WordPress, ce qui sort du cadre de has_action et doitêtre fait avec précaution.

Différence entre has_action et has_filter

Techniquement, has_action et has_filter s’appuient sur le même mécanisme interne. La différence est surtout conceptuelle :

has_action est utilisée pour vérifier des hooks d’action, c’est-à-dire desévénements où du code est exécuté.
has_filter est utilisée pour vérifier des hooks de filtre, c’est-à-dire des points de transformation de données.

Utiliser la fonction appropriée améliore la lisibilité et la clarté de votre code pour d’autres développeurs.

Exemples concrets d’utilisation de has_action

Conditionner une fonctionnalité à la présence d’une action

Imaginons un thème qui propose un hook personnalisé mytheme_after_header. Un plugin veut ajouter un contenu spécifique à cet emplacement, mais seulement si le thème (ou un autre plugin) accroche déj à quelque chose à ce hook :


if ( has_action( 'mytheme_after_header' ) ) { add_action( 'mytheme_after_header', 'mon_plugin_contenu_special', 20 );
}

Cela permet au plugin de ne fonctionner que dans un contexte où ce hook est actif, évitant des comportements inattendus sur d’autres thèmes.

Vérifier qu’une action a bienété redéfinie dans un thème enfant

Un thème parent peut prévoir des hooks internes pour permettre à un thème enfant de surcharger certaines parties du layout. Le thème parent peut alors vérifier si une fonction aété ajoutée dans le thème enfant :


if ( has_action( 'mytheme_before_footer', 'childtheme_custom_before_footer' ) ) { // Le thème enfant fournit une implémentation personnalisée
} else { // Code de secours (fallback) du thème parent
}

Ce genre de vérification améliore la flexibilité et la maintenabilité de vos thèmes.

Récupérer la priorité d’une fonction pour une manipulation avancée

Parfois, vous avez besoin de connaître la priorité à laquelle une fonction est exécutée pour la repositionner ou la retirer proprement :


$priority = has_action( 'wp_footer', 'afficher_signature' ); if ( false !== $priority ) { // On retire la fonction à sa priorité actuelle remove_action( 'wp_footer', 'afficher_signature', $priority ); // Puis on la ré-accroche avec une autre priorité add_action( 'wp_footer', 'afficher_signature', 99 );
}

Sans has_action, vous seriez obligé de deviner ou de connaître à l’avance la priorité exacte, ce qui n’est pas toujours possible dans un environnement complexe.

Bonnes pratiques pour utiliser has_action en développement WordPress

1. Vérifier intelligemment, pas systématiquement

Il peutêtre tentant de vérifier systématiquement avec has_action avant chaque appel à do_action ou remove_action. En pratique, ce n’est pas toujours nécessaire :

do_action ne provoque pas d’erreur s’il n’y a aucune fonction accrochée au hook.
remove_action échoue silencieusement si aucune fonction ne correspond.

Utilisez has_action lorsque vous avez un besoin fonctionnel réel : audit, compatibilité avec des extensions tierces, optimisation de performance ou logique conditionnelle.

2. Toujours tenir compte du type de retour

Dans vos conditions, gardez en tête qu’un résultat non booléen peutêtre renvoyé. Deux approches sont possibles :

Si vous n’avez pas besoin de la priorité, un simple if ( has_action( 'hook', 'callback' ) ) suffit.
Si vous avez besoin d’être précis (priorité, comparaison stricte), stockez d’abord le résultat et utilisez une comparaison avec false.

3. Documenter vos hooks personnalisés

Lorsque vous créez des hooks d’action personnalisés dans vos thèmes ou plugins, documentez-les clairement dans votre code etéventuellement dans votre documentation externe. Indiquez :

Le nom exact du hook.
À quel moment il est appelé.
Quels paramètres sont passés aux callbacks.

Cela facilitera l’utilisation de has_action par d’autres développeurs souhaitant interagir avec vos points d’extension.

4. Ne pas confondre has_action, add_action et do_action

Pouréviter les erreurs conceptuelles, gardez bien en tête les rôles de chaque fonction :

add_action : accroche une fonction à un hook d’action.
do_action : déclenche l’exécution de toutes les fonctions accrochées à un hook.
has_action : vérifie si une ou plusieurs fonctions sont accrochées à un hook, etéventuellement renvoie leur priorité.

has_action ne remplace ni add_action ni do_action : elle les complète.

has_action et sécurité / performance

Impact sur les performances

L’appel à has_action implique un accès à la structure interne qui stocke les callbacks enregistrés. Sur un site standard, l’impact est généralement négligeable. Toutefois, sur des sites à très forte charge ou avec un grand nombre de hooks, il est conseillé de :

Limiter son usage à des cas utiles (pas dans une boucle de milliers d’itérations, par exemple).
Éviter de l’appeler de manière répétitive avec les mêmes paramètres dans un même contexte.

Si nécessaire, vous pouvez stocker le résultat d’un has_action dans une variable pour le réutiliser plusieurs fois au lieu de rappeler la fonction.

Sécurité et logique métier

Sur le plan de la sécurité, has_action n’est pas une fonction de filtrage ou d’échappement de données. Elle ne protège pas contre les failles de type XSS ou injections SQL. En revanche, elle peut contribuer à une logique métier plus sûre enévitant la double exécution de certaines actions sensibles.

Pour sécuriser vos sorties et vos entrées, continuez d’utiliser les fonctions adaptées de WordPress :

esc_html, esc_attr, esc_url, etc. pour l’échappement des sorties.
wp_nonce_field, check_admin_referer, etc. pour la validation des requêtes.

Comparer has_action avec d’autres fonctions utiles

has_action vs did_action

Une fonction souvent associée à has_action est did_action. Les deux ne doivent pasêtre confondues :

has_action( $tag ) : vérifie si des fonctions sont accrochées au hook $tag.
did_action( $tag ) : retourne le nombre de fois où le hook $tag a déj àété exécuté pendant le cycle de chargement.

Vous pouvez par exemple vérifier qu’un hook aété déclenché au moins une fois avant d’exécuter une logique dépendante.

has_action et has_filter

Comme mentionné plus haut, has_action et has_filter partagent la même logique interne. Retenez simplement cette règle pratique :

Pour un hook appelé avec do_action, utilisez has_action.
Pour un hook appelé avec apply_filters, utilisez has_filter.

Cela rend votre code plus clair et conforme aux conventions de la communauté.

Étude de cas : rendre un plugin plus flexible grâce à has_action

Scénario

Supposons que vous développez un plugin qui affiche un bandeau promotionnel en bas de page. Par défaut, vous utilisez l’action wp_footer. Cependant, certains thèmes premium proposent un hook personnalisé theme_footer_before_closing_body qui est plus adapté visuellement.

Objectif

Vous souhaitez que votre plugin :

Utilise le hook personnalisé s’il est effectivement utilisé par le thème.
Sinon, se rabatte sur wp_footer.

Implémentation avec has_action


function mon_plugin_affiche_bandeau { echo 'Promotion spéciale !';
} // Si le thème exploite déj à le hook personnalisé, on s'y accroche
if ( has_action( 'theme_footer_before_closing_body' ) ) { add_action( 'theme_footer_before_closing_body', 'mon_plugin_affiche_bandeau', 20 );
} else { // Sinon, on utilise le hook standard add_action( 'wp_footer', 'mon_plugin_affiche_bandeau', 20 );
}

Grâce à has_action, votre plugin s’adapte intelligemment au contexte sans nécessiter de configuration manuelle de l’utilisateur.

Conclusion intermédiaire : ce qu’il faut retenir sur has_action

Pour résumer l’essentiel de manière pragmatique :

has_action sert à vérifier la présence de callbacks sur un hook d’action, pas à exécuter l’action.
Elle accepte deux paramètres : $tag (obligatoire, nom du hook) et $callback (optionnel, fonction à vérifier).
Elle peut retourner un booléen ou un entier :
- Sans callback : true ou false selon qu’au moins une fonction est attachée.
- Avec callback : un entier (priorité) ou false.
Elle existe depuis WordPress 2.5.0.
Elle ne renvoie pas la liste complète des fonctions attachées, seulement la priorité ou un booléen.
Elle est complémentaire de add_action, do_action, remove_action et de sa cousine has_filter.

En maîtrisant correctement has_action, vousécrirez des thèmes et plugins WordPress plus fiables, plus modulaires et plus compatibles avec l’écosystème riche etévolutif de WordPress.