Comprendre les hooks WordPress (et add_action)

Derniers trucs & astuces

Un hook (crochet) dans WordPress est un point d’ancrage dans le code où vous pouvez attacher des fonctions pour modifier ou ajouter des fonctionnalités sans avoir à modifier directement le cœur de WordPress. Il existe deux types principaux de hooks : les actions et les filtres.

  • Les actions permettent d’exécuter du code à un moment précis du cycle de vie de WordPress. Par exemple, vous pouvez ajouter du contenu avant l’affichage d’une page, charger des scripts ou des styles CSS, ou encore effectuer des redirections. Une action ne retourne rien, elle exécute simplement une tâche.

  • Les filtres, quant à eux, vous permettent de modifier ou de filtrer des données avant qu’elles ne soient utilisées ou affichées. Par exemple, vous pouvez filtrer le contenu d’un article avant qu’il soit rendu.

Utilité de add_action

La fonction add_action est utilisée pour attacher une fonction personnalisée à un hook d’action. Cela signifie que vous dites à WordPress : « Lorsque cet événement se produit (le hook), exécute cette fonction. » Cela te permet de personnaliser le comportement de WordPress ou d’ajouter des fonctionnalités sans toucher au code existant, ce qui est essentiel pour garder ton installation flexible et maintenable.

				
					add_action('nom_du_hook', 'nom_de_la_fonction', [priorité], [nombre d'arguments]);
  • nom_du_hook : C’est le nom de l’événement auquel vous voulez attacher votre fonction (par exemple wp_head, init, wp_enqueue_scripts, etc.).
  • nom_de_la_fonction : C’est le nom de la fonction que vous voulez exécuter lorsqu’un certain événement se produit.
  • priorité (facultatif) : Indique l’ordre d’exécution de ta fonction par rapport aux autres fonctions attachées au même hook. Plus la valeur est faible, plus la fonction sera exécutée tôt. La valeur par défaut est 10.
  • nombre d’arguments (facultatif) : Le nombre d’arguments que votre fonction accepte. La valeur par défaut est 1.

Quelques hooks de WordPress

Ce ne sont ici que quelques exemples mais vous trouverez la liste complète des hooks de WordPress sur cette page.

1. init

  • Définition : Ce hook est exécuté après que WordPress a initialisé ses éléments de base, mais avant qu’il ne commence à traiter la requête.
  • Exemple :
				
					function ma_fonction_init_perso() {
    // Code exécuté lors de l'initialisation
    if (!session_id()) {
        session_start();
    }
}
add_action('init', 'ma_fonction_init_perso');

2. wp_enqueue_scripts

  • Définition : Utilisé pour charger les fichiers CSS et JavaScript dans le front-end (partie publique du site).
  • Exemple :
				
					function mes_scripts_perso() {
    wp_enqueue_style('mon-style-perso', get_template_directory_uri() . '/css/style.css');
    wp_enqueue_script('mon-script-perso', get_template_directory_uri() . '/js/script.js', array('jquery'), null, true);
}
add_action('wp_enqueue_scripts', 'mes_scripts_perso');

3. wp_head

  • Définition : Insère des éléments dans la balise <head> du site. Généralement utilisé pour ajouter du code supplémentaire comme des balises meta ou du CSS en ligne.
  • Exemple :
				
					function ajout_meta_perso() {
    echo '<meta name="custom-meta" content="My Custom Meta">';
}
add_action('wp_head', 'ajout_meta_perso');

4. admin_menu

  • Définition : Ce hook est utilisé pour ajouter des éléments de menu dans l’administration.
  • Exemple :
				
					// Fonction pour ajouter un élément de menu personnalisé dans l'administration
function mon_menu_personnalise_admin() {
    // add_menu_page ajoute une nouvelle page au menu d'administration
    // Paramètres :
    // 1. Titre de la page (affiché en haut de la page de l'admin)
    // 2. Titre du menu (affiché dans le menu de l'admin)
    // 3. Capacité requise pour voir cette page ('manage_options' signifie que seul un administrateur peut voir cette page)
    // 4. Slug unique pour cette page (identifiant utilisé dans l'URL)
    // 5. Fonction à appeler pour générer le contenu de la page
    add_menu_page(
        'Titre de la Page Personnalisée',   // Titre de la page
        'Menu Personnalisé',                // Nom du menu
        'manage_options',                   // Permission requise
        'slug-page-personnalisee',          // Slug de la page
        'afficher_contenu_page_personnalisee' // Fonction callback qui génère le contenu de la page
    );
}
// Attache la fonction 'mon_menu_personnalise_admin' au hook 'admin_menu'
// Ce hook est déclenché pour construire le menu d'administration de WordPress
add_action('admin_menu', 'mon_menu_personnalise_admin');

// Fonction qui génère le contenu de la page personnalisée dans l'administration
function afficher_contenu_page_personnalisee() {
    // Affiche un simple titre dans l'administration
    echo '<h1>Bonjour depuis la page personnalisée de l\'administration</h1>';
}

5. the_content

  • Définition : Filtre le contenu d’un article avant son affichage. Il est souvent utilisé pour ajouter ou modifier le contenu avant qu’il ne soit rendu sur la page.
  • Exemple :
				
					function ajout_contenu_apres($content) {
    if (is_single()) {
        $content .= '<p>Merci d\'avoir lu cet article !</p>';
    }
    return $content;
}
add_action('the_content', 'ajout_contenu_apres');

Cette fonction va ajouter “Merci d’avoir lu cet article !” au pied de tous vos articles.

6. wp_footer

  • Définition : Permet d’ajouter du contenu avant la fermeture de la balise <body>. Souvent utilisé pour ajouter du JavaScript personnalisé ou des scripts d’analyse.
  • Exemple :
				
					function ajout_script_footer() {
    echo '<script>console.log("Ceci est mon script perso ajouté au pied de page !");</script>';
}
add_action('wp_footer', 'ajout_script_footer');

7. template_redirect

  • Définition : Ce hook est exécuté juste avant que WordPress ne détermine quel template utiliser pour la page. Il est souvent utilisé pour rediriger des utilisateurs.
  • Exemple :
				
					function redirection_perso() {
    if (is_page('ancienne-page')) {
        wp_redirect(home_url('/nouvelle-page'));
        exit();
    }
}
add_action('template_redirect', 'custom_redirect');

Note à propos de la fonction WordPress wp_redirect() : elle prend 2 paramètres, l’URL de redirection (obligatoire) et le code de redirection (facultatif).

				
					wp_redirect(home_url('/nouvelle-page'), 301); // Redirection permanente
wp_redirect('https://exemple.com', 302);      // Redirection temporaire

La priorité dans WordPress

Cette notion est importante car elle détermine dans quel ordre vont s’appliquer des actions ou des filtres lorsqu’ils sont attachés au même hook. Plus le nombre est bas, plutôt va s’exécuter la tâche. Par exemple :

				
					add_action('init', 'ma_premiere_fonction', 5);  // Exécutée en premier (priorité plus faible)
add_action('init', 'ma_deuxieme_fonction', 10); // Exécutée après

Le nombre d'arguments

Le nombre d’arguments spécifie combien d’arguments sont passés à la fonction callback. Par défaut, ce nombre est fixé à 1, mais certains hooks peuvent passer plusieurs arguments à la fonction.

Comment savoir combien d’arguments un hook fournit ? Cela dépend du hook en question, et cette information est généralement trouvable dans la documentation de WordPress ou dans le code source.

Par exemple, si un hook fournit plusieurs arguments, tu dois les accepter explicitement dans la fonction que tu attaches avec add_action. Si le hook passe 2 ou 3 arguments et que tu spécifies un nombre d’arguments inférieur, seuls ceux que tu as spécifiés seront acceptés. Si tu ne précises rien, un seul argument sera accepté par défaut.

Comment savoir combien d’arguments sont passés à un hook ?

Pour connaître le nombre d’arguments qu’un hook fournit, vous avez plusieurs options :

  1. Documentation officielle de WordPress :

    • Les hooks les plus courants sont documentés, et la documentation précise le nombre d’arguments que chaque hook passe à sa fonction callback. Par exemple, la page sur le hook the_content précise qu’il passe 1 argument (le contenu).

    Exemple de documentation : The the_content Hook

  2. Examen du code source :

    • Si la documentation n’est pas disponible ou peu claire, vous pouvez aussi consulter le code source de WordPress pour voir comment un hook est implémenté. Si un hook utilise la fonction do_action ou apply_filters, les arguments seront passés après le nom du hook. Exemple :
				
					do_action('init'); // Ce hook ne passe aucun argument
do_action('save_post', $post_ID, $post, $update); // Ce hook passe 3 arguments

Exemple avec plusieurs arguments :

				
					function mon_save_post_perso($post_ID, $post, $update) {
    // Code qui utilise les trois arguments
    if ($update) {
        error_log("Le post $post_ID a été mis à jour.");
    }
}
add_action('save_post', 'mon_save_post_perso', 10, 3);

A propos de do_action

Définition de do_action()

La fonction do_action() dans WordPress est utilisée pour déclencher un hook d’action. Cela permet d’exécuter toutes les fonctions qui ont été attachées à ce hook à l’aide de add_action(). En d’autres termes, avec do_action(), vous dites à WordPress : « À cet endroit du code, je veux que toutes les fonctions associées à ce hook soient exécutées. ». Voici la structure :

				
					do_action( 'nom_du_hook', [$arg1], [$arg2], ... );
  • nom_du_hook : C’est le nom du hook d’action que vous déclenchez.
  • **$arg1, $arg2, …** : (facultatif) Ce sont les arguments supplémentaires que vous souhaitez passer aux fonctions attachées à ce hook. Ces arguments seront transmis à chaque fonction associée via add_action()`.

Exemple pratique

Imaginons que vous souhaitiez permettre aux autres développeurs de faire quelque chose chaque fois qu’un utilisateur se connecte à votre site WordPress. Vous pouvez utiliser do_action() pour créer un hook personnalisé dans le code de connexion de l’utilisateur.

Voici un exemple d’utilisation de do_action() :

				
					function mon_propre_hook_connexion_utilisateur( $user_id ) {
    // Ici, nous déclenchons le hook 'connexion_utilisateur_perso'
    do_action( 'connexion_utilisateur_perso', $user_id );
}

Dans cet exemple, le hook connexion_utilisateur_perso est déclenché chaque fois que mon_propre_hook_connexion_utilisateur() est appelé, et il transmet l’ID de l’utilisateur connecté ($user_id) aux fonctions associées.

Ensuite, d’autres développeurs (ou vous-même) peuvent utiliser add_action() pour attacher des fonctions à ce hook personnalisé :

				
					function envoyer_email_connexion( $user_id ) {
    $user_info = get_userdata( $user_id );
    wp_mail( 'admin@monsite.com', 'Nouvelle connexion', $user_info->user_login . ' vient de se connecter.');
}
add_action( 'connexion_utilisateur_perso', 'envoyer_email_connexion' );

Dans cet exemple :

  • Vous créez un hook d’action personnalisé avec do_action('connexion_utilisateur_perso', $user_id).
  • Puis, vous attachez une fonction (envoyer_email_connexion) à ce hook avec add_action(). Cette fonction sera exécutée chaque fois que le hook sera déclenché, ici pour envoyer un email quand un utilisateur se connecte.

Voici comment cela fonctionne :

  1. do_action() crée un point d’ancrage (un hook) à un endroit précis du code.
  2. Cette fonction (dans l’exemple mon_propre_hook_connexion_utilisateur( $user_id )) doit être appelée quelque part dans le code lorsque l’utilisateur se connecte (ou dans tout autre contexte approprié).

Si cette fonction n’est jamais appelée dans le cycle de vie de votre application, alors le hook connexion_utilisateur_perso ne sera jamais exécuté et les fonctions attachées à ce hook ne seront pas lancées.

Exemple complet avec un appel :

  1. Créez et déclenchez le hook : Vous appelez mon_propre_hook_connexion_utilisateur( $user_id ) lorsque l’utilisateur se connecte (ou à tout autre moment où cela est pertinent).

				
					function mon_propre_hook_connexion_utilisateur( $user_id ) {
    // Déclencher le hook
    do_action( 'connexion_utilisateur_perso', $user_id );
}

// Appel de la fonction lors de la connexion de l'utilisateur
// Cet appel devrait être fait, par exemple, après la vérification de la connexion
mon_propre_hook_connexion_utilisateur( get_current_user_id() );

Ajoutez une action à ce hook : Ensuite, vous attachez une fonction (comme l’envoi d’un email) au hook personnalisé connexion_utilisateur_perso pour effectuer une action lorsque ce hook est déclenché  :

				
					function envoyer_email_connexion( $user_id ) {
    $user_info = get_userdata( $user_id );
    wp_mail( 'admin@monsite.com', 'Nouvelle connexion', $user_info->user_login . ' vient de se connecter.');
}
add_action( 'connexion_utilisateur_perso', 'envoyer_email_connexion' );

Laisser un commentaire

WP-CODES 2024 – Tous droits réservés