Les hooks (ou en français « crochets ») sont tout simplement l’un des ingrédients qui ont fait le succès de WordPress. Dans ce petit article, nous nous permettons de faire un petit focus sur une fonctionnalité essentielle de WordPress. Une base qui devrait être maîtrisée par toute personne souhaitant apprendre à coder pour WP.
Un hook est une fonction PHP déclarée par les développeurs du cœur de WordPress ou par les développeurs d’extensions et de thèmes afin de permettre d’altérer leur fonctionnement initial. Les hooks sont déclarés à des moments clés de l’exécution du code pour permettre son altération dans le but d’étendre les fonctionnalités prévues initialement.
Un filtre est un type de hook WordPress permettant de remplacer les valeurs de variables utilisées par le cœur WordPress ou par un thème ou une extension. Par exemple, le hook the_title permet de filtrer la fonction the_title() afin d’altérer son rendu, par exemple pour faire précéder le titre d’un article d’une chaîne de caractères.
Une action est un type de hook WordPress permettant d’effectuer un traitement ou d’afficher quelque chose à un moment clé de l’exécution du code de WordPress, d’un thème ou d’une extension. Cela permettra par exemple d’effectuer une modification sur le contenu d’un article au moment de sa publication.
Les hooks, une fonctionnalité essentielle de WordPress
Il existe actuellement plus de 2300 hooks disponibles pour les développeurs et développeuses afin d’étendre ou altérer les fonctionnalités natives du CMS. Autant dire qu’il serait compliqué de tous les lister dans un article.
Cependant, ils sont tous disponibles au sein de DevHub, la documentation technique officielle de WP que j’avais présentée dans l’astuce numéro 6 de ce calendrier de l’avent WordPress 2020.
Voici la liste de tous les hooks triés par ordre alphabétique. Vous pouvez utiliser l’outil de recherche (picto loupe en haut à droite) pour effectuer une recherche plus précise.
Astuce : vous pouvez également utiliser DevHub pour lister les hooks qui sont apparus à partir d’une version spécifique de WordPress. Voici par exemple les hooks apparus sur WP 5.5 et ceux apparus sur WP 5.6.
Quelques exemples d’utilisation de hooks de type « filtre »
De très nombreuses fonctions de WordPress sont filtrables. Par exemple, une fonction telle que the_title() dispose d’un filtre permettant de modifier le rendu de cette fonction qui sert à l’affichage du titre de la publication courante.
Ainsi, on pourra utiliser le filtre the_title pour ajouter un texte avant ou après le titre. Pour cela, nous allons déclarer une fonction chargée de récupérer le titre courant et d’y ajouter un texte, puis de retourner l’ensemble à la fonction native the_title(), chargée de l’affichage du titre.
Nous appliqueront cette fonction via le filtre the_title :
/*
* Cette fonction a pour but de récupérer le titre de la publication courante
* afin d'y ajouter le texte "FAITS DIVERS – " si l'article a été publié dans
* la catégorie "Faits divers" (avec un slug correspondant nommé 'faits-divers').
*/
function who_add_prefix_to_title( $title, $id ) {
if ( in_category( 'faits-divers', $id ) ) {
$title = '[FAITS DIVERS] ' . $title;
}
return $title;
}
/*
* La fonction add_filter() nous permet d'utiliser le hook 'the_title'
* afin d'altérer la valeur retournée par la fonction the_title()
*/
add_filter( 'the_title', 'who_add_prefix_to_title', 10, 2 );Quelques exemples d’utilisation de hooks de type « action »
Les hooks de type « action » sont des crochets placés à des emplacements stratégiques de l’exécution de WordPress et permettent d’ajouter une action spécifique, comme l’ajout d’un contenu, d’un bouton, d’une ressource CSS ou JS, etc.
Pour donner un exemple d’action hook utile, nous pouvons prendre l’exemple de wp_body_open. Ajouté avec la version 5.2 de WordPress, ce hook qui était très attendu par les personnes qui travaillent dans le référencement de sites WordPress permet d’injecter du code HTML juste après l’ouverture de la balise <body> de la page.
Si votre thème est compatible et que vous utilisez une version de WordPress supérieure à 5.2, vous pouvez donc utiliser ce hook pour afficher du code HTML juste après l’ouverture de l’élément <body>. généralement, ce hook est utilisé afin d’afficher les scripts de type Google Tag Manager.
Pour utiliser un crochet d’action, on utilise la fonction WordPress add_action().
Voici un exemple, mis en place dans le fichier functions.php de votre thème enfant :
/*
* Cette fonction a pour but d'insérer un code Google Tag Manager à l'emplacement du hook 'wp_body_open'.
*/
function who_add_custom_body_open_code() {
echo '<noscript><iframe src="https://www.googletagmanager.com/ns.html?id=GTM-VOTRE_ID_GOOGLE_TAG_MANAGER" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>';
}
/*
* La fonction add_action() nous permet d'utiliser le hook 'wp_body_open'
* afin d'ajouter le résultat de notre fonction juste après l'ouverture de
* la balise <body>.
*/
// Add Google Tag code which is supposed to be placed after opening body tag.
add_action( 'wp_body_open', 'who_add_custom_body_open_code' );Créer ses propres hooks WordPress
SI vous développez vos propres thèmes WordPress, vous devriez également vous intéresser à la création de vos propres hooks au sein de vos thèmes. C’est de plus très simple à faire. Voici deux cas concrets, l’un pour créer un hook de type filtre, l’autre pour créer un hook de type action.
Créer un hook de type « filtre » pour son thème ou son extension WordPress
Imaginons qu’à un endroit de votre thème, vous ayez affichez à un emplacement précis un paragraphe de texte. Cela pourrait par exemple être le cas du pied de page de votre site, et d’un ligne indiquant les crédits de votre site :
<p class="credits">Site réalisé avec amour par l’agence Whodunit</p>Vous pourriez permettre la modification de ce paragraphe via un petit hook simple. Pour cela, on va placer le morceau de code HTML ci-dessus à l’intérieur d’une variable PHP :
$credits = '<p class="credits">Site réalisé avec amour par l’agence Whodunit</p>';
echo $credits;Ensuite, on va déclarer et appliquer un filtre à l’aide de la fonction apply_filter. Le premier paramètre de cette fonction permet de donner un nom au filtre, le second paramètre permet de donner la variable à filtrer (ici $credits).
Si le filtre existe et renvoie une valeur pour notre variable $credits, alors il remplacement son contenu. Sinon, la valeur par défaut de $credits sera retournée :
$credits = '<p class="credits">Site réalisé avec amour par l’agence Whodunit</p>';
echo apply_filters( 'who_filter_footer_credits', $credits );Pour utiliser ce filtre et donc modifier ce paragraphe de crédits, les personnes utilisant un thème enfant de votre thème n’auront qu’à utiliser votre filtre who_filter_footer_credits comme dans les exemples vus plus haut dans ce article :
function who_my_custom_footer_credits() {
$credits = '<p class="credits">Site réalisé avec amour par moi-même et pour moi-même</p>';
return $credits;
}
add_filter( 'who_filter_footer_credits', 'who_my_custom_footer_credits', 10 );Pour plus d’information sur la fonction apply_filter(), consultez sa documentation (en anglais)
Créer un hook de type « action » pour son thème ou son extension WordPress
Cela fonctionne un peu comme pour les filtres, mais il s’agit de permettre aux développeuses et développeurs utilisant votre thème ou votre extension de pouvoir injecter du code à un endroit clé de l’exécution de votre code.
Par exemple, dans le pied de page de votre thème, vous pourriez permettre l’affichage d’un paragraphe de texte (ou de tout autre code) juste avant la fermeture de la balise <body>. Dans ce cas, vous pouvez utiliser la fonction do_action(), qui permettra aux gens d’insérer du code à ce endroit là. La fonction do_action() fonctionne sensiblement de la même façon que la fonction apply_filter() :
<p>Voici un paragraphe situé au pied de la page</p>
<?php echo do_action( 'who_before_body_closing_tag' ); ?>
</body>
</html>Pour utiliser cette action afin d’insérer du contenu HTML à cet endroit, les gens n’auront alors plus qu’à utiliser le hook who_before_body que nous avons créé :
function who_display_text_before_body_closing_tag( $should_be_an_array ){
echo '<p>Voici un paragraphe de texte</p>';
}
add_action( 'who_before_body_closing_tag', 'who_display_text_before_body_closing_tag', 10 );Pour plus d’information sur la fonction do_action(), consultez sa documentation (en anglais)
Cette astuce n’a pas vocation à présenter de façon exhaustive les fonctionnement des hooks WordPress, il s’agit avant tout d’une introduction afin de vous aider à un peu mieux connaître le fonctionnement de ce mécanisme de base de WordPress.
Nous n’avons par exemple pas vu la possibilité de passer des variables en paramètres des actions et des filtres. Si cette introduction vous a intéressé, vous pouvez parcourir ces quelques ressources en français sur les hooks WordPress :
- Un autre tuto sur l’utilisation des hooks par Capitaine WP
- Un article très complet de Kinsta
- Identifier les fonctions appelées par certains hooks WordPress, un bel article par Mosaika
Merci à Samy Kantari, Lead Developer de Whodunit, qui a aidé à l’écriture de cette petite astuce technique en compilant il y a quelques temps les ressources nécessaires sur l’intranet de l’agence.
Bonjour, et merci pour vos astuces qui me sont aussi utiles les unes que les autres. J’utilise WP depuis quelques années, mais je commence à travailler avec les hooks depuis peu. Quelque chose qui me perturbe, c’est que certains hooks (save_post, ou le récent wp_after_insert_post – par exemple) sont déclenchés plusieurs fois lors de l’appui sur un bouton, comme “Publier”, ou “mettre à jour”, sur un article. J’ai fait plusieurs recherches, posé une question sur Slack, mais la seule solution trouvée, actuellement, est la création d’un champ meta flag qui me signale que je suis déjà passé par là, et qui bloque les actions aux autres passages. Avez-vous une autre idée ?
Bonjour @Jean-Pol et un grand merci pour ce commentaire 😃
En effet, certains hooks peuvent être utilisés dans un contexte où ils peuvent s’appeler eux-mêmes !
C’est par exemple de cas sur le hook save_post.
Dans ce cas ce qu’il faut faire, c’est retirer le hook au début du traitement puis le remettre en place une fois le traitement effectué :
<?php function ma_fonction( $post_id ){ if ( ! wp_is_post_revision( $post_id ) ){ // Retrait du hook pour éviter qu'il ne boucle remove_action('save_post', 'ma_fonction'); // Traitement wp_update_post( $args ); // Remise en place du hook add_action('save_post', 'ma_fonction'); } } add_action('save_post', 'ma_fonction'); ?>Ah ! Je teste de suite 🙂
Merci pour votre réponse et pour cette série d’astuces !!!! Encore celle d’aujourd’hui, sur les blocs réutilisables, je la mets en place sur mes prochains sites.