do action WordPress example

do_action WordPress example : guide complet

Introduction

Dans l’écosystème WordPress, les hooks (actions et filtres) sont au cœur de la personnalisation du CMS et de l’extension de ses fonctionnalités. Parmi eux, la fonction do_action est l’un des outils les plus importants pour les développeurs de thèmes et de plugins : elle permet de déclencher un hook d’action à un endroit précis du code afin d’exécuter toutes les fonctions qui y sont rattachées.

Cet article détaillé vous explique ce qu’est do_action, comment elle fonctionne dans le cœur de WordPress, comment créer vos propres hooks personnalisés, et comment l’utiliser efficacement dans vos projets pour garder un code propre, extensible et performant.

Rappels sur les hooks WordPress

Actions et filtres : la base du système d’extensions

Les hooks WordPress sont des points d’ancrage dans l’exécution du CMS où vous pouvez injecter ou modifier du comportement sans toucher au noyau. On distingue deux grands types de hooks :

• Actions (action hooks) : elles permettent d’exécuter du code à un moment donné du cycle de vie de WordPress (chargement du cœur, affichage du head HTML, enregistrement d’un article, connexion d’un utilisateur, etc.). Par exemple, le hook wp_head est déclenché dans la balise de la page, et de nombreux thèmes et plugins y ajoutent des scripts, feuilles de style ou balises meta.
• Filtres (filter hooks) : ils servent à modifier des données (texte, HTML, variables PHP, tableaux de configuration) avant qu’elles ne soient utilisées ou affichées. Un filtre reçoit généralement une valeur en entrée, la modifie et doit retourner cette valeur transformée.

La fonction do_action concerne exclusivement les hooks d’action. Elle ne renvoie aucune valeur significative et se contente de lancer toutes les fonctions enregistrées sur un hook donné.

Comprendre la fonction do_action

Définition générale

La fonction do_action est une fonction native du cœur de WordPress. Elle sert à déclencher un hook d’action (existant ou personnalisé) et à exécuter toutes les fonctions qui ont été associées à ce hook via add_action. Tant qu’aucune fonction n’est attachée à ce hook, l’appel à do_action ne produira tout simplement aucun effet visible.

Signature officielle

La signature officielle de do_action dans WordPress est la suivante :

do_action( string $hook_name, mixed ...$arg );

• $hook_name (ou parfois $tag) : chaîne de caractères obligatoire, il s’agit du nom du hook d’action à déclencher (par exemple 'wp_head', 'init', 'my_custom_action'…).
• ...$arg : liste d’arguments optionnels (0, 1 ou plusieurs). Ce sont des valeurs qui seront transmises aux fonctions callback attachées à ce hook via add_action.

Les arguments supplémentaires sont donc optionnels : vous pouvez tout à fait appeler do_action( 'mon_hook' ); sans passer d’arguments.

Valeur de retour de do_action

Un point fondamental : la fonction do_action ne retourne rien d’utile. Sa valeur de retour est null. Elle se contente d’exécuter les callbacks associées au hook et de terminer son travail. Si vous avez besoin de récupérer une valeur transformée, il faut utiliser un filtre (via apply_filters), pas une action.

Fonctionnement interne simplifié

De manière simplifiée, on peut décrire le fonctionnement de do_action comme suit :

1. Enregistrer une nouvelle exécution du hook (compteur interne).
2. Exécuter éventuellement les callbacks enregistrées sur le hook spécial all, qui s’appliquent à tous les hooks d’action.
3. Vérifier si des fonctions ont été enregistrées sur le hook $hook_name via add_action.
4. Préparer le tableau d’arguments transmis (avec quelques ajustements pour la rétrocompatibilité).
5. Appeler successivement toutes les callbacks associées à ce hook, en leur passant les arguments prévus.

Si aucune fonction n’est liée au hook $hook_name, l’appel à do_action( $hook_name ) se termine rapidement sans rien exécuter.

Exemples de base avec do_action

Exemple minimal sans argument

Voici un exemple minimaliste d’utilisation de do_action avec un hook personnalisé ne recevant aucun argument :

Action personnalisée exécutée.
';
} // 2. Attacher la fonction à un hook personnalisé.
add_action( 'mon_hook_simple', 'mon_hook_simple_callback' ); // 3. Déclencher le hook à l’endroit voulu dans le code.
do_action( 'mon_hook_simple' );

Dans cet exemple, 'mon_hook_simple' est le nom du hook d’action. Lorsque do_action( 'mon_hook_simple' ) est exécutée, WordPress va appeler mon_hook_simple_callback. S’il n’y avait aucune fonction attachée à ce hook, l’appel à do_action ne ferait rien.

Exemple avec arguments

Passons maintenant à un exemple où l’on transmet des arguments aux callbacks via do_action. Supposons que l’on souhaite déclencher une action en passant un nom d’utilisateur et un message :

' . esc_html( $nom_utilisateur ) . ' : ' . esc_html( $message ) . '
';
} // 2. Attacher la fonction à un hook personnalisé.
// Le 4e paramètre (2) indique que la callback acceptera 2 arguments.
add_action( 'mon_hook_message', 'afficher_message_personnalise', 10, 2 ); // 3. Déclencher l’action avec 2 arguments.
$utilisateur = 'Alice';
$message = 'Bienvenue sur notre site WordPress !'; do_action( 'mon_hook_message', $utilisateur, $message );

Dans cet exemple :

• 'mon_hook_message' est le nom du hook d’action.
• $utilisateur et $message sont passés en arguments via do_action.
• add_action( 'mon_hook_message', 'afficher_message_personnalise', 10, 2 ); précise que la callback accepte 2 arguments.

Les callbacks doivent déclarer et accepter un nombre d’arguments cohérent avec le paramètre $accepted_args fourni dans add_action. Si vous déclarez 2 ici, la fonction recevra au maximum 2 arguments, même si do_action en fournit davantage.

Créer un hook personnalisé avec do_action

Principe général

Créer un hook d’action personnalisé revient simplement à choisir un nom de hook et à l’utiliser dans un appel à do_action. N’importe quel développeur de thème ou de plugin pourra ensuite brancher ses propres fonctions sur ce hook via add_action.

Exemple complet : hook d’action personnalisé pour un message de bienvenue

L’article d’origine mentionnait l’idée d’afficher un message personnalisé lorsqu’un utilisateur se connecte, avec un hook nommé user_logged_in. Pour rester cohérent avec le fonctionnement réel de WordPress, on va ici illustrer la même idée avec un hook personnalisé déclenché après un traitement de connexion dans un plugin ou un thème.

Bienvenue ' . esc_html( $utilisateur->display_name ) . ' !
'; }
} /** * 3. Attacher la fonction au hook personnalisé. * On précise 1 pour $accepted_args car la callback reçoit 1 argument : $user_id. */
add_action( 'mon_plugin_apres_connexion', 'mon_message_bienvenue', 10, 1 );

Dans ce scénario :

• mon_plugin_apres_connexion déclenche le hook 'mon_plugin_apres_connexion' avec l’identifiant utilisateur $user_id.
• mon_message_bienvenue est exécutée automatiquement lorsqu’on appelle do_action( 'mon_plugin_apres_connexion', $user_id ).
• Tout autre développeur peut lui aussi se brancher sur ce hook pour réagir à la connexion (envoyer un email, enregistrer un log, déclencher une notification, etc.).

do_action et hooks du cœur WordPress

Exemples de hooks d’action natifs

Le cœur de WordPress utilise do_action à de nombreux endroits pour offrir des points d’extension standardisés. Parmi les hooks les plus courants, on trouve notamment :

• init : déclenché une fois WordPress chargé mais avant l’envoi de tout contenu. Il sert souvent à enregistrer des custom post types, taxonomies, scripts, etc.
• wp_head : exécuté dans la balise du front-office, idéal pour injecter des balises meta, des scripts ou des feuilles de style supplémentaires.
• wp_footer : déclenché juste avant la fermeture de la balise dans la plupart des thèmes, très utile pour charger des scripts ou du tracking (Analytics, pixels, etc.).
• admin_init : utilisé dans l’interface d’administration pour initialiser des paramètres, vérifier des permissions ou enregistrer des options.

Ces hooks sont tous déclarés via do_action dans le code du core. Par exemple, dans un template de thème, on peut retrouver :

Tous les plugins et thèmes qui se branchent sur wp_head via add_action( 'wp_head', 'ma_fonction' ); verront leur fonction exécutée à cet endroit précis.

Utiliser do_action pour étendre vos propres thèmes et plugins

En ajoutant vos propres appels à do_action dans un thème ou un plugin, vous offrez à d’autres développeurs (ou à vous-même, dans un autre plugin) la possibilité de modifier le comportement sans éditer le code source principal. C’est une excellente pratique pour :

• rendre un thème premium plus extensible,
• proposer une API interne dans un gros plugin,
• séparer les responsabilités entre différents modules,
• faciliter les surcharges propres à chaque projet client.

Bien utiliser add_action avec do_action

Rappel sur add_action

Pour que do_action ait un effet, il faut que des fonctions soient préalablement attachées au hook concerné via add_action. Sa signature est :

add_action( string $hook_name, callable $function_to_add, int $priority = 10, int $accepted_args = 1
);

• $hook_name : nom du hook d’action (doit correspondre exactement à celui utilisé dans do_action).
• $function_to_add : nom de la fonction ou callable à exécuter.
• $priority : entier définissant l’ordre d’exécution (plus le nombre est petit, plus la fonction est exécutée tôt). Par défaut, 10.
• $accepted_args : nombre d’arguments que la fonction callback accepte, en cohérence avec ceux fournis par do_action.

Importance du paramètre $accepted_args

Le quatrième paramètre de add_action, $accepted_args, est souvent négligé, mais il est crucial pour éviter des comportements inattendus. Par exemple :

do_action_ref_array( string $hook_name, array $args );

Promotion spéciale cette semaine !