Filtres, Actions et Fonctions : Le hook de la semaine n°0

Filtres, Actions et Fonctions : Le hook de la semaine n°0

À vos marques

Oyez oyez, nous sommes mardi et maintenant comme tous les mardis sur BoiteAWeb, vous retrouverez le hook de la semaine ou la fonction de la semaine, selon les stocks disponibles.

Prêts

Ces articles ont pour but de vous faire découvrir ou redécouvrir un hook ou une fonction afin de parfaire vos développements WordPress, ceci s’inclus dans les bonnes pratiques à adopter.

Partez

Je commence cette suite par le numéro 0 afin de placer un peu les fondations. Inutile de vous parler des hooks filtres et hooks actions si vous ne savez pas ce que c’est. Cette série s’adresse donc aux développeurs déjà experts mais aussi aux développeurs débutants et initiés, apprendre à utiliser une fonction, utiliser le bon hook est une chose excellente dans WordPress, alors c’est parti !

Définition d’un hook

Un hook ou hameçon est un point d’entrée dans une fonction WordPress. En greffant nos propres fonctions sur ces hooks, WordPress exécutera alors notre travail dans SON code, ceci sans avoir besoin de modifier le coeur de WordPress, c’est bien le but premier d’un hook. WordPress est ce qu’il est aujourd’hui grâce aux hooks.

Les hooks sont déclenchés dans un ordre précis lors du chargement de WordPress et est différent entre le front ou back-end.

Il existe 2 types de hooks : Les actions et les filtres.

Le hook Action

Une action est le hook permettant justement d’exécuter notre code dans celui de WordPress. Par exemple, avec le hook "plugins_loaded" je peux mettre à jour une entrée de base de données relative à mon plugin qui vient d’être chargé. Ce hook est l’un des premiers à être déclenché, front et back.

Le hook Filtre

Un filtre est un hook qui retourne une valeur contrairement à une action. Cependant rien ne vous empêche d’exécuter une action aussi dans un filtre (oui je complique déjà). Un filtre peut par exemple servir à modifier la balise TITLE de mes pages avec le hook "wp_title". En réalité, une action est un filtre si on regarde le core :

Une fonction

Les fonctions WordPress sont des fonctions PHP, je ne vous étonne pas. Il existe des fonctions WP qui ont une équivalence en PHP, alors pourquoi utiliser celle de WordPress !? Car la plupart du temps se trouve un hook dedans, rappelez vous que WordPress est ce qu’il est aujourd’hui grâce aux hooks ! Alors ne les esquivons pas.

Aussi parfois la fonction WordPress reprends celle de PHP en ajoutant quelquechose de plus, un peu à sa sauce car WordPress en a besoin. La plupart du temps, je ne peux que recommander d’utiliser la fonction WordPress. Euh, non sauf dans le cas de get_the_ID(); …

Quelques démos de code

Utiliser une action

Je reprends mon exemple du hook "plugins_loaded", c’est le 2ème hook à être déclenché après l’action "muplugins_loaded" qui sert pour les mu-plugins.

Je vais faire en sorte grâce à l’ajout de mon hook de mettre à jour mon plugin + son numéro de version. La fonction baw_my_superplugin_loaded() est donc purement arbitraire, c’est la callback, néanmoins éviter "my_plugin()" qui est trop courant, ajoutez un préfixe (ici baw) et le nom (superplugin) ou initiales (sp) ou numéronyme (s11n) du plugin.

Utiliser un filtre

Même chose je reprends mon exemple du filtre "wp_title". Ce hook se trouve en fin de fonction wp_title() dans le fichier /wp-includes/general-template.php

Grâce à ce filtre nous modifions le titre de la page 404 avec « Vous êtes perdu ? »

Les entrailles d’un hook

On voit donc que pour être utilisé, un hook prends 2 paramètres, en fait il en prends 4 dont les 2 derniers ont une valeur par défaut. Gardez bien en tête les 2 derniers paramètres car ils sont parfois très important, je vais vous l’expliquer. Ces 4 paramètres sont :

  1. Nom du hook
  2. Nom de la fonction de callback
  3. Priorité
  4. Nombre d’arguments

Nom du hook

C’est le nom que vous trouverez dans le core de WordPress ou dans un plugin ou thème. Vous pouvez aussi ajouter les votre dans vos plugins, voyez un peu plus bas « Créer un hook ».

Nom de la fonction de callback

Cette fonction peut être une fonction PHP, WordPress ou faite maison. Si c’est maison, elle se doit d’être unique, ajoutez donc comme dis précédemment au minimum un prefixe. Si par hasard vous avez besoin de retourner un simple « false » ou « true » pour forcer la valeur d’un filtre, sachez que WordPress a intégré des fonctions simples qui sont :
__return_true
__return_false
__return_empty_array
__return_null
__return_zero
Tiens, ces fonctions auraient pû être dans un prochain article « Les fonctions de la semaine », ça sera d’une pierre deux coups !

Priorité

La priorité est parfois floue pour pas mal de monde, on voit des 0, des -1, des 1, des 10, des 99 ou 9999999 … Ok, mais on met quoi en fait !? Et pourquoi !
La priorité est l’ordre dans lequel le filtre sera déclenché. Par défaut la valeur est 10, elle suffit très souvent. Les filtres sont donc joués dans l’ordre croissant. Le fait de mettre « 0 » ne vous assure pas d’être le premier, ni même -1 ou -999999, un autre plugin a peut-être mis la même valeur. Dans le cas d’un égalité (comme pour toutes les fois c’est 10 qui passe) c’est l’ordre d’ajout du filtre dans la queue qui compte.
Même chose pour « 99999… », si vous voulez avoir toutes les chances de passer dernier, utiliser la constante PHP PHP_INT_MAX. Si vous avez un soucis avec un hook qui fait mal son travail, jouez avec le priorité, il y a peut-être un plugin qui passe avant/après vous et ça fait capoter votre travail.
Pour résumer, la priorité est l’ordre de déclenchement de votre filtre, jouée par ordre croissant.

Nombre d’arguments

Par défaut 1 argument est passé dans la fonction passée en callback, si vous avez plus d’un arguments, il suffit alors de noter ici le nombre exact.

J’ai ici 3 arguments, si je veux pouvoir lire $seplocation, je dois donc utiliser 3 en 4ème paramètre, si seul le $title m’interesse, je peux laisse 1 ou vide.

La différence entre les arguments d’une action et ceux d’un filtre est que pour le filtre il faut TOUJOURS renvoyer avec un return le 1er argument, sinon, vous risquez de casser le site, rien que ça.

Devenez acteur, créez un hook !

La création d’un hook est simple, et à mon goût il manque des hooks dans WordPress et dans les plugin !

Créer une action

La création d’une action se fait avec la fonction do_action() comme son nom l’indique, elle « fait l’action ». Elle prends minimum 1 paramètre qui est le nom de l’action. Vous pouvez ajouter dans vos plugins les actions du core de WordPress. Les autres paramètres sont les ceux que vous souhaitez donner au développeur pour faire ses tests etc. Voici comment en créer une :

Mon action s’appelle dummy_action et elle prends 2 paramètres qui sont $foo et $bar.

Petite parenthèse, vous pouvez passer un tableau en paramètre au lieu d’en passer N, dans ce cas, utilisez la fonction do_action_ref_array().

Créer un filtre

La création d’un filtre se fait avec la fonction apply_filters() comme son nom l’indique, elle « applique les filtres ». Elle prends minimum 1 paramètre qui est le nom du filtre. Vous pouvez ajouter dans vos plugins les filtres du core de WordPress. Les autres paramètres sont les ceux que vous souhaitez donner au développeur pour faire ses tests etc. Voici comment en créer un :

Mon filtre s’appelle dummy_filter et il prends 2 paramètres qui sont $foo et $bar.

Petite parenthèse, vous pouvez passer un tableau en paramètre au lieu d’en passer N, dans ce cas, utilisez la fonction apply_filters_ref_array() et souvenez vous que c’est le premier élément du tableau qui sera retourné.

Utilisation de nos hooks

Imaginons ce genre de code :

Super code ! Mais euh … mince j’aurais bien voulu ajouter les .pdf et .zip moi ! Et puis il faudrait avoir un compte connecté pour avoir le droit de télécharger ! Zut !

La solution ? Les hooks ! Cela donnerait :

Nous avons ajouté 2 hooks, l’action file_to_be_downloaded avec en paramètre le fichier $file, puis le filtre allowed_extensions avec en paramètre les extensions $exts.

Il est maintenant possible de jouer avec ça pour modifier le comportement de la fonction.

Obliger le visiteur à être connecté :

Tout simplement …

Maintenant ajoutons les PDF et ZIP :

Hop le support de ces fichiers est maintenant possible dans notre script ! Bravo !

Allez plus loin

Supprimer un hook

Sachez qu’il est aussi possible de supprimer une action ou un filtre, il faut respectivement utiliser remove_action() et remove_filter() en fournissant le nom de l’action ET la fonction associée ET la priorité. Si vous souhaitez supprimer TOUTES les callbacks d’une action ou d’un filtre, utilisez remove_all_actions() et remove_all_filters() en fournissant en paramètres le nom de l’action ET la priorité.

Tester un hook

Vous pouvez tester si une action déclenchera des callbacks ou tester si telle callback est posée sur une action avec la fonction has_action(), même chose pour un filtre avec has_filter() :

ou

Connaître le hook en court

Il est aussi possible de connaître quel est le hook dans lequel nous sommes, ceci avec la fonction current_filter() qui comme son nom ne l’indique pas, fonctionne bel et bien pour un filtre ET une action. Elle nous renvoie le nom du hook courant.

Savoir si une action a déjà été déclenchée

J’aime assez bien celle-ci, elle retourne le nombre de fois que l’action demandée via did_action(). Elle peut donc être utilisée comme un booléen :

Bonus

En bonus, des liens, de la doc et une image retraçant le chargement du core (pas tout dommage), ne soyez pas effrayés ;)

wordpress-core-load-lifecycle[1]Des questions ?

Lire la suite

Vous aimez ? Partagez !


Réagir à cet article

120 caractères maximum