Si vous développez des sites Web avec WordPress, vous devez forcément, à un moment ou à un autre, faire face aux Hooks de WordPress. Les crochets (hooks) permettent de modifier la manière dont agissent certaines fonctions natives de WordPress. Vous pourriez évidemment modifier directement les fichiers du coeur de WordPress pour satisfaire vos désirs, vos besoins… et ceux de vos clients.
Mais si tel est le cas, vous êtes, au mieux, un mauvais développeur, au pire, un fieffé crétin
Car WordPress vous permet de “détourner” le comportement par défaut de beaucoup de ses fonctions.
Dans la suite de cet article, je vais tenter de vous expliquer en quoi et pourquoi, en tant que développeur, vous devez utiliser les “hooks” de WordPress. Tout d’abord, les crochets (désolé, nous sommes en France, alors essayons, dans la mesure du possible, de parler ou d’écrire Français) sont une excellente illustration de ce que peuvent être les “design patterns” (désolé, mais là, la traduction française est limitative ou trop vague : modèle de conception …)
C’est bien beau tout ça… mais …
Pourquoi les Hooks existent-ils dans WordPress ?
Pour adopter les crochets (hooks), il est vital de bien comprendre leur utilité et la manière dont vous les utiliserez. Commençons par créer une version d’une fonction de WordPress qui existe en standard :
function get_excerpt($text, $length = 150) {
$excerpt = substr($text,$length);
return $excerpt;
}
Cette fonction prend deux paramètres : une chaîne et la longueur à laquelle nous voulons couper. Que se passe-t-il si l’utilisateur veut un extrait 200 caractères au lieu de 150 caractères ? Il lui suffit de modifier le paramètre lorsqu’il utilise la fonction. Aucun problème jusque là.
Si vous utilisez beaucoup cette fonction, vous remarquerez que le paramètre pour le texte est généralement le contenu de l’article et que vous utilisez habituellement 200 caractères au lieu de la valeur par défaut de 150. Ne serait-il pas agréable si vous pouviez configurer les nouveaux paramètres par défaut, afin qu’il ne faille pas ajouter les mêmes paramètres maintes et maintes fois ? En outre, que se passe-t-il si vous voulez ajouter un texte plus personnalisé à la fin de l’extrait ?
C’est le genre de problèmes que les hooks permettent de résoudre. Nous allons jeter un coup d’œil à la façon dont cela fonctionne.
function get_excerpt($text, $length = 150) {
$length = apply_filters("excerpt_length", $length);
$excerpt = substr($text,$length);
return $excerpt;
}
Comme vous pouvez le voir, la longueur par défaut de l’extrait est toujours 150, mais nous avons également appliqué un filtre. Un filtre vous permet d’écrire une fonction qui modifie la valeur de quelque chose — dans ce cas, la longueur de l’extrait. Le nom (ou tag) de ce filtre est excerpt_length, et si aucune fonction n’est attachées à lui, sa valeur restera 150. Nous allons voir comment nous pouvons maintenant utiliser cela pour modifier la valeur par défaut.
function get_excerpt($text, $length = 150) {
$length = apply_filters("excerpt_length");
$excerpt = substr($text,$length);
return $excerpt;
}
function modify_excerpt_length() {
return 200;
}
add_filter("excerpt_length", "modify_excerpt_length");
Tout d’abord, nous ont défini une fonction qui ne fait rien à part retourner un nombre. À ce stade, rien n’utiliser la fonction, et, nous allons donc dire à WordPress que nous voulons ce hook dans le filtre excerpt_length.
Nous avons modifié avec succès la longueur par défaut de l’extrait dans WordPress, sans toucher à la fonction d’origine et sans même avoir à écrire une fonction personnalisée pour générer l’extrait d’un article. Ce sera extrêmement utile, car si vous voulez toujours des extraits de 200 caractères, il suffit d’ajouter ceci comme un filtre une seule fois.
Supposons que vous vouliez ajouter un texte « Read on » à la fin de l’extrait. Nous pourrions modifier notre fonction d’origine pour fonctionner avec un crochet, puis attacher une fonction sur ce hook, comme ceci :
function get_excerpt($text, $length = 150) {
$length = apply_filters("excerpt_length");
$excerpt = substr($text,$length);
return apply_filters("excerpt_content", $excerpt);
}
function modify_excerpt_content($excerpt) {
return $excerpt . "Read on…";
}
add_filter("excerpt_content", "modify_excerpt_content");
Cet hook est placé à la fin de la fonction et permet d’en modifier le résultat final. Cette fois, nous avons aussi passé le résultat que produit la fonction en tant que paramètre de notre hook. La fonction qui nous lie à ce hook recevra ce paramètre.
Tout ce que nous faisons dans notre fonction est de prendre le contenu original de l’extrait ($excerpt ) et d’ajouter de notre texte « Read on » à la fin. Mais si nous choisissons, nous pourrions aussi retourner le texte « Click the title to read this article » qui remplacerait l’extrait entier.
Même si notre exemple est un peu redondant, puisque WordPress dispose déjà d’un meilleur fonctionnement, j’espère que vous avez compris le principe général des hooks. Nous allons étudier plus en profondeur à ce qui se passe avec les filtres, les actions, les priorités, les arguments et les autres options disponibles.
Les filtres et les actions
Les filtres et les actions sont de deux types de hooks. Comme vous l’avez vu dans la section précédente, un filtre modifie la valeur de quelque chose. Une action, plutôt que de modifier quelque chose, appelle une autre fonction à exécuter en complément.
Une action couramment détournée est wp_head. Nous allons voir comment cela fonctionne. Vous avez peut-être remarqué une fonction au bas de la section head de votre site Web, nommé wp_head(). Plonger dans le code de cette fonction, vous pouvez voir qu’il contient un appel à do_action(). Ceci est similaire à apply_filters() ; cela veut dire d’exécuter toutes les fonctions qui sont liées au tag wp_head.
Nous allons mettre une balise meta copyright haut de page de chaque article pour voir comment cela fonctionne.
add_action("wp_head", "my_copyright_meta");
function my_copyright_meta() {
if(is_singular()){
echo "";
}
}
Processus pour utiliser les Hooks de WordPress
Aujourd’hui, les hooks sont mieux documentés de nos jours qu’ils ne le furent dans le passé. Vous pouvez trouver quelques bonnes informations dans le codex, mais le mieux est d’utiliser la bible d’Adam Brown, et/ou de consulter le code source.
Imaginons que vous souhaitez ajouter une fonctionnalité à votre blog qui notifie les auteurs quand leur travail est publié. Pour le faire, vous avez besoin de faire quelque chose quand un article est publié. Essayons de trouver un hook rattaché à la publication d’un article.
Pouvons-nous savoir si nous avons besoin d’une action ou d’un filtre ? Bien sûr que nous le pouvons ! Quand un article est publié, voulons-nous modifier ses données ou faire une action complètement séparée ? La réponse est bien entendu la deuxième possibilité, et nous donc aurons besoin d’une action. Allons sur le site Internet d’Adam Brown dans la section consacrée aux actions et la recherchons “Publish”.
La première chose que vous trouverez est app_publish_post. Cela semble approprié… Cliquons. La page de détails ne nous donne pas beaucoup d’informations (quelquefois elle le fait), cliquez donc sur le lien “View hook in source” correspodant à votre version de WordPress (de préférence la version la le plus récente) dans le tableau. Ce site Internet montre seulement un fragment du code source, mais malheureusement le début de la documentation est coupé, donc il est difficile de savoir si c’est ce que nous avons besoin. Cliquez “View complete file in SVN” pour aller code source complet pour que nous puissions chercher notre hook.
Dans le code source que je consulte, le hook peut être trouvé dans la fonction _publish_post_hook () , qui - selon le commentaire au-dessus – est un “hook pour programmer des pings et des clôtures quand un poste est publié,” ce qui n’est pas vraiment ce dont nous avons besoin.
Avec un peuplus de recherche dans la liste d’actions, vous trouverez le hook de publish_post et c’est celui dont nous avons besoin. La première chose à faire est d’écrire la fonction qui enverra votre message électronique. Cette fonction recevra l’identifiant (ID) de l’article comme argument, que vous pouvez utiliser pour donner des informations dans votre email. La deuxième tâche est d’accrocher cette fonction dans l’action. Regardez le code fini ci-dessous pour les détails.
function authorNotification($post_id) {
global $wpdb;
$post = get_post($post_id);
$author = get_userdata($post->post_author);
$message = "
Hi ".$author->display_name.",
Your post, ".$post->post_title." has just been published. Well done!
";
wp_mail($author->user_email, "Your article is online", $message);
}
add_action('publish_post', 'authorNotification');
Ce processus pourrait sembler un peu compliqué au début et, pour être complètement honnête, il exige vraiment de parcourir la documentation et le code source de WordPress au début, mais au fil du temps vous vous sentirez plus à l’aise avec le système et passerez de moins de moins de temps à chercher
Les priorités
Le troisième paramètre en ajoutant vos actions et filtres est la priorité. Cela désigne fondamentalement l’ordre dans lequel les hooks doivent être exécutés. Nous ne l’avons pas couvert pour l’instant, mais le fait d’attacher des fonctions multiples à un hook est possible. Si vous voulez qu’un courrier électronique soit envoyé à un auteur quand son article est publié et soit également automatiquement posté sur Twitter, cela pourrait être fait par le biais de deux fonctions séparées, chacune attachée au même tag (publish_post).
Les priorités désignent quel hook doit d’abord être exécuté. La valeur implicite est 10, mais cela peut être changé si nécessaire. Cepandant, les priorités ne font pas d’habitude d’énorme différence. Si le courrier électronique est envoyé à l’auteur avant que l’article est posté sur Twitter ou vice et versa, cela ne fera pas une énorme différence.
Dans des cas plus rares, assigner une priorité peut être important. Vous pourriez vouloir remplacer les actions d’autre plugins (être prudents, dans ce cas-là), ou vous pourriez vouloir faire respecter un ordre spécifique.
Les arguments
Le quatrième argument en ajoutant des filtres et des actions spécifie combien d’arguments la fonction utilise. D’habitude le hook lui-même vous l’indique et vous aurez besoin de regarder le code source pour trouver ces informations.
Comme vous savez déjà, vos fonctions sont exécutées quand elles sont appelés par apply_filters () ou do_action (). Ces fonctions auront le tag comme premier argument (c’est-à-dire le nom du hook que vous branchez) et a ensuite les paramètres supplémentaires.
Par exemple, le filtre default_excerpt reçoit deux paramètres, comme on peut le voir dans includes/post.php.
$post->post_excerpt = apply_filters( 'default_excerpt', $post_excerpt, $post );
Les arguments sont bien nommés – $post_excerpt et $post – et donc il est facile de supposer que le premier est le texte de l’extrait et le deuxième est l’objet ‘post’.
function my_filter_test($post_excerpt, $post) {
echo "<pre>";
print_r($post_excerpt);
print_r($post);
echo "</pre>";
}
add_filter("default_excerpt", "my_filter_test");
Nommage des Hooks
Vous vous rappelez quand nous avons regardé l’action publish_post ? En fait, celle-ci n’est plus utilisée ! Elle a été renommée dans la version 2.3 en {$new_status} _ {$post-> post_type}. Avec l’arrivée des types d’articles personnalisés, il était important de rendre le système plus flexible.
Par conséquent, publish_post est le hook correct à utiliser, mais en réalité, vous utiliserez {$new_status} _ {$post-> post_type}.
Déterminer les fonctions qui peuvent être hookées
Pour lister l’ensemble des fonctions de WordPress qui peuvent être “hookées” , référez-vous à cet article : Comment détecter et afficher toutes les fonctions crochetables dans WordPress ?
Créez vos propres Hooks
Une tonne de hooks est disponible dans WordPress, mais rien ne vous empêche de créer ceux dont vous aurez besoin, quelque soit votre projet.
Dans l’exemple ci-dessous, nous allons implémenté une fonctionnalité permettant aux utilisateurs de poster de courts textes de présentation sur la page d’accueil de votre site Web. Nous allons créer une fonction pour qui vérifiera une liste de mots interdits, et qui nous l’accrocherons à la fonction qui ajoute les textes de présentation au mur.
Regardez le code ci-dessous (les explications viennent ensuite) :
function post_blurb($user_id, $text) {
$text = apply_filters("blurb_text", $text);
if(!empty($text)) {
$wpdb->insert('my_wall', array("user_id" => $user_id, "date" => date("Y-m-d H:i:s"), "text" => $text), array("%d", %s", "%s"));
}
}
function profanity_filter($text) {
$text_elements = explode(" ", $text);
$profanity = array("badword", "naughtyword", "inappropriatelanguage");
if(array_intersect($profanity, $text_elements)) {
return false;
}
else {
return $text;
}
}
add_filter("blurb_text", "profanity_filter");
La première chose dans le code est la désignation de la fonction qui ajoute le texte de présentation. Notez que j’ai inclus la fonction apply_filters(), que nous utiliserons pour ajouter détecter les mot interdits (si des mots inappropriés sont présents dans le texte, celui-ci ne sera pas publié).
Ensuite vient notre fonction de vérification des mots interdits. Elle vérifie le texte en tant que paramètre par rapport à un tableau de mots déclarés comme interdits. En utilisant array_intersect(), nous cherchons des éléments du tableau qui se trouvent dans les deux tableaux; ceux-ci seraient alors les mots interdits. S’il y en a, la fonction retourne false (return false; ) sinon, elle retourne le texte original (return $text; ).
La dernière partie du code “accroche” réellement cette fonction à notre script d’ajout de texte de présentation.
Maintenant les autres développeurs peuvent accrocher leurs propres fonctions dans notre script. Ils pourraient construire un filtre anti-spam ou un meilleur filtre de mots interdits.
Conclusion
Avec ce tutoriel nous espérons que vous avez compris l’intérêt d’utiliser les hooks de WordPress. Nous vous avons expliqué ce que sont les actions et les filtres qui vous permettent d’améliorer les fonctions de base de WordPress.
Certes, au départ, il faut du temps pour maitriser les hooks de WordPress. Le plus gros problème est généralement que les gens se perdent dans tous les filtres disponibles ou ont du mal à trouver les paramètres nécéssaires, etc. Mais avec un peu de patience, cela peut être facilement surmonté. Il suffit de commencer à les utiliser, et vous serez un maître sans délai !
Source : WordPress Essentials: The Definitive Guide To WordPress Hooks
Jeu de briques
Snake
Pacman
Bubble