Ajouter des Filtres et Actions à son plugin

En programmation événementielle, nous avons l’habitude d’employer des écouteurs qui nous permettent d’intercepter tous types d’événements. Qu’ils soient utilisateurs, ou système, comme un clic, un survol, un chargement, un redimensionnement, etc… bref cela vous parle.

Et bien du coté de WordPress c’est un peu pareil, et nous allons user de hooks (crochetage) qui vont nous permettre d’intercepter tous types d’événements propres à WordPress. Qu’il s’agisse de la génération de contenu, de la mise en place du menu, de l’écriture d’un commentaire, d’un enregistrement dans la base… bref… tout est sous contrôle, et, sous écoute.

Filtres et Actions… mais encore ?

Ces hooks vont pouvoir ‘crocheter’ les événements de deux manières distinctes, soit au travers de filtres, soit au travers d’actions. Il existe une troisième possibilités très spécifique qui se focalise sur l’activation, la désactivation ou la désinstallation d’un élément. Adam R Brown a listées toutes ces actions et filtres sur son site All plugin hooks in WordPress 4.4.

Dit de manière succincte et rapide voyons de plus près la distinction à faire entre actions et filtres. Les actions permettent d’intercepter des événements généraux au sein de WordPress comme lors de l’écriture dans une table, l’affichage d’un contenu, l’envoie d’un mail…, et d’y ajouter nos propres actions et lignes de code devant être exécutées à ce moment là.

Alors que les filtres s’immiscent au sein même de ces actions, au niveau plus précis du traitement des données échangées, en recevant une valeur, et en pouvant, ou non, agir dessus, comme remplacer des caractères, récupérer des données, rechercher une donnée en particulier, etc… avant de la retransmettre.

C’est bien beau, mais c’est abstrait, non ?

Afin de ne pas rendre cet article indigeste de part un aspect qui se voudrait trop théorique, je vous propose que nous travaillions sur un plugin… simple à ajouter à notre bac à sable et facile à tester en temps réel. Ajouter et activer le plugin Birnou/WP-Activate-Debug ou son homologue afin d’accéder à la fonction write_log() qui sera employée lors des tests de fonctionnements. Si vous le souhaitez, vous pouvez récupérer l’ensemble des fichiers nécessaires pour suivre cet article sur le github, Birnou/WP-Actions-and-Filters. Sinon créez un plugin, activez le, et, ajoutez lui le code au fur et à mesure que nous avançons dans l’article.

Quelques mots sur les fonctionnalités!

Au cours de ces quelques tests nous allons explorer les divers emplois de chacun des hooks, mettre en évidence les divers paramètres nécessaires et faire ressortir certaines alternatives qui peuvent nous être parfois utiles.

Parmi les deux listes d’Actions et de Filtres, ce n’est pas le choix qui manque. Donc, peu importe notre sélection, tous s’emploieront de la même manière et réagiront identiquement. Côté actions, optons pour la prise en compte de l’affichage des composantes de la page get_header() et get_footer(). Prenons soin d’écrire footer en premier et ensuite header… nous changerons l’indice de priorité afin de rétablir l’ordre. En ce qui concerne les filtres, c’est du pareil au même, à ceci prêt que la fonction nous renvoie la chaîne intercepté en cours de traitement, par exemple the_title, nous renverra le titre, the_excerpt le résumé, the_content le contenu et ainsi de suite tout en pouvant agir dessus. Par exemple jouons sur the_title et modifions le.

<?php
    function pem_get_footer(){
        write_log( 'affichage du footer');
    }
    function pem_get_header(){
        write_log( 'affichage du header');
    }
    add_action( 'get_footer', 'pem_get_footer',10 );
    add_action( 'get_header', 'pem_get_header',8 );

    function pem_the_title($arg) {
        $tmp = 'Modification à la volée ====> '.$arg;
        return $tmp;
    }
    add_filter('the_title', 'pem_the_title');
?>

Affichez un article dans votre navigateur et ouvrez également le fichier erreurs.log qui a du apparaître à la racine de wp-content. Que constatons nous ?

L’ordre de traitement des fonctions footer / header, respecte bien l’indice de priorité du fait que les messages sont bien écrit dans l’ordre attendu, aux détriment de celui d’apparition dans le fichier code source. Et ensuite tous les titres de contenu dans la page sont précédés par la chaîne ‘Modification à la volée ====> ‘.

Les arguments, et leurs significations

Nous avons vu qu’il suffit d’user de add_action() ou add_filter() et d’ajouter les paramètres nécessaires. Il y a quatre paramètres à renseigner :

• Le nom du hook, qu’il s’agisse d’une action ou d’un filtre
• La fonction à interpellé lors de l’interception du hook. Il est important de penser à utiliser une fonction usant d’un préfixe qui vous est propre afin d’éviter toute collision avec une fonction ayant le même nom. Par exemple, lors de génération de code pour Puce et Média, pem_ est placé devant chaque nom de fonction.
  Si la fonction appelée se situe au sein d’une classe, il faut alors utilisé un tableau contenant deux valeurs array(l’instance de la classe, la méthode).
• L’indice de priorité, optionnel, qui par défaut vaut 10, peut être défini afin de mieux contrôler l’ordre d’exécution. Si vous souhaitez que cet appel se fasse en dernier, il est préférable d’user de PHP_INT_MAX. Cependant si deux appels se font sur un même indice de priorité, l’ordre d’apparition dans le code sera retenu.
• De manière optionnelle le nombre d’arguments attendus par la fonction peut être spécifié, par défaut la valeur est de 1.

Les trois premiers arguments ont été mis en application dans les tests précédents. Procédons donc à un autre type de test… afin de pouvoir explorer ce dernier argument, le quatrième, concernant le nombre de paramètres passés à la fonction. Mais pour cela, introduisons une paire de fonctions supplémentaires, apply_filters() et do_action().

Ces deux fonctions permettent d’invoquer les hooks en relation, en dehors des invocations naturelles, et également de pouvoir leur transmettre un certains nombres de paramètres. Je dis un certain nombre, car, rappelez vous par défaut le nombre d’arguments attendus est 1, donc si lors de la mise en place du hook, nous n’avons pas modifié cette valeur, un seul paramètre sera récupéré. Pour le mettre en évidence, plaçons une fonction de récupération qui va énumérer les arguments reçus.

<php
    $nb = 1;
    function pem_arguments() {
        $arg_list = func_get_args();
        foreach ($arg_list as $value){
            write_log('-- '.$value);
        }
    }
    add_filter('the_content', 'pem_arguments', 1, $nb);
    apply_filters( 'the_content', 'voilà un nouveau contenu','valeur 1', 'valeur 2','valeur 3' );
?>

Il suffit maintenant de recharger notre page article du bac à sable et de lire le fichier erreurs.log. Deux choses sautent alors aux yeux… d’une part, et bien qu’écrit en second, apply_filters() est exécutée en premier, on va dire que c’est normal du fait que add_filter() est une fonction qui indique à WordPress que l’on souhaite lier une fonction à apply_filters(), donc apply_filter() s’exécute bien en premier lieu. Donc si vous inversez ces deux lignes, vous verrez que seul add_filter() sera exécuté car il écrase le apply_filter() précédent.

Et, d’autre part, on constate que les valeurs ‘valeur 1’, ‘valeur 2’,‘valeur 3’ n’ont pas été transmises puisque le nombre d’arguments attendus équivaut à la valeur $nb soit 1. Effacez le contenu du fichier, erreurs.log, sauvegardez le, modifiez la valeur de $nb à 4 et rechargez la page pilote. Qu’en pense erreurs.log cette fois-ci?

En suivant le même principe d’application, le pendant à add_action() sera do_action() et fonctionnera à l’identique de apply_filter().

Retirer une action ou un filtre ?

En fonction du comportement de l’application, nous pouvons avoir besoin de retirer un hook, il suffit alors d’user des fonctions remove_action() ou remove_filter(), en passsant cette fois-ci le nom du hook, la fonction de rappel et l’indice de priorité. Nous pouvons tout aussi bien retirer tous les hooks en usant de remove_all_actions() et remove_all_filters() et là cette fois ci, simplement le nom du hook et l’indice de priorité pour l’ensemble des retraits.

Il peut être important de vérifier si un hook possède des actions ou des filtres qui lui sont associés. On pourra alors user de has_action() et has_filter()… et sin nous sommes dans une boucle ou au sein même d’un hook, il  est toujours possible de l’identifier grâce à current_filter() qui renverra aussi bine l’info qu’il s’agisse d’une action ou d’un filtre.