Publié le 24 février 2026 SEO Technique

do_action WordPress : guide complet pour comprendre et créer des hooks d’action

Sommaire de l'article

Introduction

Le fonctionnement de WordPress repose sur un système d’actions et de filtres appelés hooks. Parmi ces hooks, la fonction do_action est unélément clé : elle permet aux développeurs de déclencher des actions personnalisées à des moments précis du cycle de chargement de WordPress et d’exécuter toutes les fonctions qui y sont accrochées avec add_action. Cet article explore en profondeur le concept de do_action WordPress, ses applications pratiques et les bonnes pratiques à adopter pour optimiser son utilisation.

Avant de plonger dans les détails techniques, il est essentiel de comprendre que do_action est un outil puissant mais sensible. Une utilisation incorrecte peut affecter les performances de votre site ou même provoquer des comportements inattendus. C’est pourquoi nous allons aborder à la fois les principes théoriques, des exemples concrets et des conseils pratiques pour une intégration propre, sécurisée et maintenable.

Concepts clés : hooks, actions et filtres dans WordPress

Qu’est-ce qu’un hook WordPress ?

Un hook est un point d’entrée dans le code de WordPress où vous pouvez exécuter votre propre logique sans modifier le noyau (core) du CMS. Les hooks permettent donc d’étendre ou modifier le comportement de WordPress de manière propre, via un thème ou un plugin.

Il existe deux grandes catégories de hooks :

Les actions (actions) : elles permettent d’exécuter du code à un moment précis du cycle WordPress (par exemple lors de l’affichage du header, au moment de l’enregistrement d’un article, après la connexion d’un utilisateur, etc.). Elles ne sont pas destinées à renvoyer une valeur.
Les filtres (filters) : ils permettent de modifier des données avant qu’elles ne soient utilisées ou stockées (par exemple modifier le titre d’un article, le contenu affiché, une URL, un e‑mail envoyé, etc.). Un filtre reçoit une valeur en entrée et doit retourner une valeur en sortie.

Les hooks sont déclarés dans le code de WordPress, des thèmes ou des plugins, puis d’autres fonctions peuvent s’y accrocher via add_action ou add_filter. Ce mécanisme rend WordPress hautement extensible sans toucher au core.

Qu’est-ce que do_action en WordPress ?

Contrairement à ce que laisse parfois entendre un vocabulaire imprécis, do_action n’est pas « un type de hook » mais une fonction du core qui permet de déclencher un hook d’action. Quand vous appelez do_action( 'mon_hook', ... ), vous demandez à WordPress d’exécuter toutes les fonctions qui ontété enregistrées sur ce hook via add_action( 'mon_hook', 'ma_fonction' ).

On peut donc résumer ainsi :

Le hook d’action est l’événement lui‑même (par exemple 'init', 'wp_head', 'save_post' ou un nom personnalisé).
do_action est l’appel de déclenchement qui active cetévénement et exécute toutes les fonctions accrochées.
add_action sert à accrocher une fonction à un hook existant, qu’il soit natif ou personnalisé.

Autrement dit, vous utilisez do_action pour créer et déclencher vos propres hooks d’action, et les autres développeurs (ou vous‑même dans un autre fichier) peuvent alors s’y connecter avec add_action.

Comment fonctionne do_action en pratique ?

Signature et principe de do_action

La forme générale de la fonction dans WordPress est :

do_action( string $hook_name, mixed $arg1, mixed $arg2, ... );

Elle fonctionne selon troiséléments principaux :

Nom du hook ($hook_name) : une chaîne de caractères unique, par exemple 'mon_action_personnalisee'. C’est ce nom qui sera utilisé aussi dans add_action.
Arguments optionnels ($arg1, $arg2, ...) : vous pouvez passer autant de paramètres que nécessaire. Ils seront transmis aux fonctions accrochées au hook.
Déclenchement : lorsque do_action est appelé, WordPress exécute dans l’ordre défini par la priorité toutes les fonctions qui ontété ajoutées avec add_action( $hook_name, ... ). Par défaut, la priorité est de 10 et le nombre d’arguments acceptés est de 1, mais ces valeurs sont configurables.

Exemple de do_action et add_action

Voici un exemple simple pour illustrer le fonctionnement :

Dans votre fichier functions.php de thème ou dans un plugin personnalisé :

Puis ailleurs dans votre code (toujours dans un thème ou un plugin chargé par WordPress) :

Au moment où WordPress exécute do_action( 'mon_action_personnalisee' );, la fonction ma_fonction_personnalisee est appelée et le texte « Action personnalisée exécutée ! » est affiché.

Passer des arguments à do_action

Vous pouvez transmettre des données aux fonctions accrochées à votre hook d’action en ajoutant des paramètres à do_action. Par exemple :

Pour que les fonctions accrochées reçoivent ces valeurs, vous devez les déclarer avec des paramètres correspondants et préciser le nombre d’arguments acceptés dans add_action :

Dans cet exemple :

La priorité de la fonction notifier_inscription est 10 (valeur par défaut).
Le nombre d’arguments acceptés ($accepted_args) est 3, ce qui permet de récupérer les trois paramètres passés à do_action.

do_action_ref_array : variante avec tableau d’arguments

WordPress fournitégalement une variante appelée do_action_ref_array. Elle fonctionne comme do_action mais prend un tableau d’arguments au lieu d’une liste d’arguments séparés :

Les fonctions accrochées à 'mon_action_avec_tableau' doivent alorsêtre définies avec des paramètres correspondant à l’ordre deséléments du tableau, et add_action doit spécifier le nombre d’arguments attendus. Cette approche est particulièrement pratique lorsque vous avez déj à vos données dans un tableau ou lorsque vous souhaitez passer un grand nombre d’arguments.

did_action : savoir si un hook a déj àété exécuté

La fonction did_action( 'nom_du_hook' ) retourne le nombre de fois où une action spécifique aété exécutée durant le cycle de chargement de WordPress. Cela permet, par exemple, de vérifier si un hook a déj àété déclenché et d’éviter des appels redondants :

 0 ) { // Le hook 'init' a déj àété exécuté
}
?>

Cycle de chargement WordPress et points d’entrée pour do_action

Les grandesétapes du cycle de WordPress

Pour utiliser efficacement do_action et les hooks d’action en général, il est crucial de comprendre les grandesétapes du cycle de chargement de WordPress. De manière simplifiée, on peut distinguer :

Chargement du noyau : WordPress charge ses fichiers principaux et initialise le cœur du système.
Chargement des plugins : les plugins actifs sont inclus et initialisés.
Chargement du thème : les fichiers du thème actif (etéventuellement du thème parent) sont inclus.
Initialisation : WordPress prépare l’environnement, les règles de réécriture, les types de contenus, les taxonomies, etc.
Traitement de la requête : WordPress analyse l’URL, détermine le type de contenu à afficher (article, page, archive…) et prépare la boucle.
Génération et affichage de la page : le thème affiche le HTML final (header, contenu, sidebar, footer…).
Nettoyage et fin de cycle : actions finales, fermeture de la requête, envoi de la réponse complète au navigateur.

Exemples d’actions natives importantes

À chacune de cesétapes, WordPress déclenche de nombreuses actions via do_action. Parmi les plus utilisées, on peut citer :

init : déclenchée après le chargement du noyau et des fichiers principaux, c’est un hook central pour enregistrer des types de contenus personnalisés, des taxonomies, des règles de réécriture, etc.
wp_head : appelée dans le fichier header.php du thème, juste avant la balise . Elle permet, par exemple, d’ajouter des balises , des scripts ou des feuilles de style.
wp_footer : appelée dans le fichier footer.php, juste avant la balise . Elle est souvent utilisée pour injecter des scripts JavaScript, des outils d’analyse, des codes de suivi, etc.
admin_init : déployée dans l’interface d’administration, idéale pour initialiser des options ou enregistrer des paramètres côté back‑office.
save_post : déclenchée lors de l’enregistrement ou de la mise à jour d’un contenu (article, page ou type personnalisé), pratique pour réaliser des traitements supplémentaires (mise à jour de métadonnées, synchronisation externe, etc.).

Chacune de ces actions est elle‑même déclenchée dans le code du core ou du thème via un appel à do_action( 'nom_du_hook' );, ce qui illustre l’omniprésence de cette fonction dans l’architecture de WordPress.

Créer ses propres hooks d’action avec do_action

Pourquoi créer un hook personnalisé ?

Créer des hooks personnalisés avec do_action permet de rendre votre code extensible. Plutôt que d’écrire un bloc de code figé, vous définissez des points d’extension où d’autres fonctions pourront venir se greffer ultérieurement, sans modifier votre code d’origine.

C’est particulièrement utile lorsque :

vous développez un thème premium ou un framework de thème destiné àêtre personnalisé par d’autres développeurs ;
vousécrivez un plugin modulaire où chaque fonctionnalité peutêtre activée, désactivée ouétendue via des addons ;
vous voulez séparer la logique métier de la logique de présentation, en offrant des points d’entrée bien définis.

Exemple : hook personnalisé dans un thème

Supposons que vous vouliez offrir la possibilité d’ajouter du contenu juste avant la fermeture de la balise dans votre thème, sans que les utilisateurs n’aient à modifier le fichier footer.php.

Dans footer.php :


do_action( 'mon_theme_before_body_closing_tag' );
?>

Dans un plugin ou le thème enfant, un développeur pourra s’accrocher à ce hook :

Ce site utilise des cookies.

';
}
?>

Ainsi, le thème parent reste intact, mais de nouvelles fonctionnalités peuventêtre ajoutées proprement grâce à do_action.

Convention de nommage pour les hooks personnalisés

Pouréviter les collisions de noms et garantir la clarté de votre code, il est recommandé de :

préfixer vos hooks par un préfixe unique lié à votre thème ou plugin, par exemple mon_theme_ ou mon_plugin_ ;
utiliser des noms clairs et descriptifs, par exemple mon_plugin_avant_contenu_article plutôt que action1 ;
éviter d’utiliser des noms de hooks déj à existants dans le core ou dans des plugins populaires, sauf si vous souhaitez volontairement vous accrocher à ces hooks ;
ne pas réutiliser à vos propres fins des hooks réservés à des usages particuliers, comme admin_init, wp_loaded, etc., pour vos propresévénements personnalisés.

Bonnes pratiques d’utilisation de do_action

Respecter les standards de développement WordPress

Pour tirer le meilleur parti de do_action et assurer la maintenabilité de votre code, quelques bonnes pratiques s’imposent :

Utilisez les standards de codage WordPress (WP Coding Standards) : indentation, nommage, commentaires clairs, etc.
Structurez vos fichiers : centralisez idéalement vos déclarations de hooks personnalisés dans des fichiers clairement identifiés (par exemple un fichier hooks.php dans un plugin complexe), afin de faciliter la maintenance.
Documentez vos hooks : commentez au-dessus de chaque do_action le but du hook, les arguments passés et les usages attendus. Cela aide grandement d’autres développeurs à comprendre comment s’y accrocher.
Gérez les dépendances : évitez de supposer qu’une fonction sera toujours accrochée à votre hook ; vérifiez si nécessaire la présence d’extensions ou de plugins requis.

Gestion des performances avec do_action

Même si le système d’actions est très performant et optimisé, une utilisation excessive ou maladroite de do_action peut impacter les performances de votre site. Quelques réflexes utiles :

Évitez de déclencher des actions dans des boucles très fréquentes ou des zones critiques si ce n’est pas nécessaire.
À l’intérieur des fonctions accrochées à un hook, limitez les opérations coûteuses (requêtes SQL multiples, accès distants, traitements lourds) ou mettez en place un système de cache.
Ne dupliquez pas des hooks pour des usages identiques : un point d’extension bien choisi vaut mieux que plusieurs appels redondants.
Utilisez la priorité dans add_action pour contrôler finement l’ordre d’exécution lorsque plusieurs fonctions sont accrochées au même hook. Par défaut, la priorité est de 10, mais vous pouvez utiliser des valeurs plus faibles (par exemple 5) pour exécuter un callback plus tôt, ou plusélevées (par exemple 20) pour l’exécuter plus tard.

Sécurité et robustesse

Les hooks déclenchés via do_action doiventêtre utilisés avec attention du point de vue de la sécurité :

Vérifiez les capacités des utilisateurs dans les callbacks (par exemple avec current_user_can) avant d’exécuter des actions sensibles (suppression de contenus, modifications d’options, etc.).
Validez etéchappez toujours les données reçues dans les fonctions accrochées (sanitisation etéchappement) avant de les enregistrer en base ou de les afficher à l’écran.
Évitez de passer directement des données non filtrées aux callbacks via do_action. Préférez travailler sur des données déj à nettoyées ou valider à nouveau côté callback.

Actions vs filtres : ne pas confondre les rôles

Une confusion fréquente consiste à utiliser une action l à où un filtre serait plus adapté. Rappel important :

Les actions (déclenchées par do_action) servent à exécuter du code à un moment donné. Elles ne retournent pas de valeur destinée àêtre réutilisée par WordPress.
Les filtres (déclenchés par apply_filters) servent à modifier une valeur (texte, variable, HTML, etc.) et doivent toujours retourner une version (éventuellement modifiée) de l’entrée.

Si votre objectif est de changer une valeur (par exemple le titre d’un article, une URL d’image, un texte d’e‑mail), vous devez créer un filtre avec apply_filters plutôt qu’une action avec do_action. Rester cohérent dans l’usage des deux types de hooks rendra votre code plus lisible et plus conforme aux pratiques de l’écosystème WordPress.

Exemples concrets d’utilisation de do_action dans WordPress

1. Ajouter une zone de contenu dans un template

Dans un thème, vous pouvez insérer un hook personnalisé à différents endroits de vos templates pour offrir des points d’extension flexibles. Par exemple, dans single.php, juste après le contenu principal :

', '' ); the_content; // Hook personnalisé après le contenu de l'article do_action( 'mon_theme_apres_contenu_article', get_the_ID ); endwhile;
?>

Ensuite, un plugin ou un thème enfant peut ajouter une fonction sur ce hook pour afficher, par exemple, un bloc d’articles relatifs :

2. Intégration avec un plugin externe

Si vous développez un plugin qui doit offrir des points d’extension à d’autres extensions, vous pouvez définir une série de hooks internes. Par exemple, un plugin d’e‑commerce pourrait déclencher :

do_action( 'mon_plugin_avant_paiement', $commande );
do_action( 'mon_plugin_apres_paiement_valide', $commande );
do_action( 'mon_plugin_apres_generation_facture', $facture );

Ces hooks permettront à d’autres plugins de s’interfacer proprement pour :

notifier un CRM externe ;
déclencher une campagne d’e‑mailing ;
enregistrer des statistiques de vente ;
mettre à jour des stocks dans un système tiers, etc.

3. Debug et conditionnement avec did_action

Dans certaines situations avancées, vous pouvez utiliser did_action pour adapter votre comportement en fonction du statut d’un hook. Par exemple :

Cela reste un usage avancé, mais peut s’avérer utile lorsque vous travaillez avec des plugins multiples et que l’ordre de chargement a une importance particulière.

Erreurs fréquentes àéviter avec do_action

Utiliser do_action à la place d’un filtre

Comme indiqué précédemment, si l’objectif est de modifier une donnée (titre, contenu, URL, e‑mail…), il faut créer ou utiliser un filtre via apply_filters. Utiliser do_action pour tenter de « renvoyer » une valeur est une erreur conceptuelle qui compliquera la maintenance.

Nom de hook incohérent ou imprécis

Un nom de hook trop générique ('action1', 'test', etc.) rend le code difficile à comprendre et augmente le risque de collision avec d’autres plugins ou thèmes. Préférez des noms descriptifs et préfixés, par exemple 'mon_plugin_apres_enregistrement_utilisateur'.

Oublier de déclarer le bon nombre d’arguments dans add_action

Si vous passez plusieurs arguments à do_action mais que vous n’indiquez pas le bon nombre dans add_action, seule une partie des données sera disponible dans votre callback. Par exemple :

Pour recevoir tous les arguments, il fautécrire :

Ignorer les performances et la lisibilité

Multiplier les hooks et y accrocher de nombreuses fonctions lourdes peut rapidement ralentir un site à fort trafic. Il est important de :

garder un œil sur les fonctions exécutées à chaque hook ;
désactiver ou nettoyer les callbacks obsolètes ;
utiliser un profilage si nécessaire pour identifier les points de blocage.

Résumé des points essentiels sur do_action en WordPress

Pour terminer ce tour d’horizon de do_action WordPress, retenez leséléments clés suivants :

do_action sert à déclencher un hook d’action et à exécuter toutes les fonctions qui y sont accrochées avec add_action.
Les actions permettent d’exécuter du code à des moments précis du cycle WordPress, tandis que les filtres sont dédiés à la modification de données.
Vous pouvez créer vos propres hooks personnalisés dans vos thèmes et plugins pour rendre votre code plus modulable et extensible.
add_action( $hook, $function_to_add, $priority, $accepted_args ) permet de s’accrocher à un hook existant, avec une priorité par défaut de 10 et un nombre d’arguments accepté par défaut de 1.
do_action_ref_array est une variante qui accepte un tableau d’arguments, pratique pour passer de nombreuses données ou des données déj à structurées.
did_action retourne le nombre de fois où une action aété exécutée, utile pour des logiques conditionnelles avancées.
Le respect des bonnes pratiques de nommage, de performances, de sécurité et de documentation est indispensable pour exploiter tout le potentiel des hooks dans WordPress.

En maîtrisant do_action, vous disposez d’un levier puissant pour transformer WordPress en une plateforme parfaitement adaptée à vos besoins, tout en restant conforme à l’écosystème et aux standards de développement du CMS.