Guide : Tout sur les Hooks dans WordPress
Vous a-t-on déjà dit que la solution à votre problème est que vous devez «vous accrocher» à quelque chose pour faire votre travail ou l’utiliser add_filtersans vraiment comprendre pourquoi cela gâche tout? Les crochets constituent la base de WordPress et fournissent des thèmes et des plugins un moyen d’interagir ou modifier le code. Dans cet article, nous décrirons ce que sont les crochets, comment ils fonctionnent et comment nous pouvons les utiliser.
Que sont les crochets ?
Au fur et à mesure que WordPress parcourt son code (depuis le début du chargement des classes, du chargement des plugins, du chargement du thème, de la requête pour la requête en cours et enfin du rendu du HTML), il passe par un tas de "points de contrôle" ; crochets. Lorsqu’un crochet est rencontré, WordPress arrête ce qu’il fait – et vérifie s’il y a des fonctions (dans le thème, le plugin ou WordPress lui-même) enregistrées pour s’exécuter sur ce crochet. S’il y en a, WordPress exécutera toutes ces fonctions, puis continuera là où il s’est arrêté.
Cela permet aux plugins, aux thèmes et à WordPress lui-même de "s’accrocher" à certains points pour ajouter, par exemple, des feuilles de style dans la <head>balise du thème, modifier la façon dont WordPress interroge les publications ou simplement modifier le contenu de la publication s’il le souhaite.
Il existe deux types de crochets; actions et filtres. Ils fonctionnent de manière assez similaire les uns aux autres, mais à une exception près que nous examinerons de plus près ci-dessous.
Actions et filtres
Pour vous accrocher à une action ou à un filtre, vous devez définir le crochet (par son nom) que vous souhaitez utiliser et définir un rappel – qui est le nom de la fonction que vous souhaitez exécuter. Dans la plupart des cas, les crochets fournissent des paramètres ou des variables qui sont pertinents pour le crochet.
Les actions sont simplement des "points de contrôle" dans l’exécution de WordPress, où vous pouvez effectuer une tâche ou faire écho à quelque chose. Dans de rares cas, vous pouvez modifier un objet (fourni dans les paramètres), de sorte que toutes les exécutions suivantes fonctionnent avec cet objet modifié.
Les filtres servent à modifier une variable ou une sortie. Tous les crochets de filtre fourniront la variable que vous pouvez modifier comme premier paramètre et vous permettront de la modifier ou de renvoyer quelque chose de différent.
WordPress exécute de nombreux crochets, mais vous pouvez créer les vôtres dans votre plugin ou votre thème. Cela permet aux développeurs d’étendre et de modifier votre code ; par exemple modifier un plugin via un thème, ou modifier le thème parent via le thème enfant.
De nombreuses fonctions de WordPress, généralement utilisées pour imprimer des publications, sont également des filtres ou des actions. Par exemple, la fonction the_title()imprime le titre du message, mais c’est aussi un filtre.
Voyons comment nous nous y accrochons dans la pratique.
S’accrocher aux actions
Pour vous accrocher à une action, vous utilisez la méthode add_action(). Au minimum, il nécessite deux paramètres ; le nom du crochet et le rappel ; le nom de la fonction que vous souhaitez exécuter. Vous pouvez éventuellement fournir la priorité comme troisième paramètre et définir le nombre d’arguments qui seront transmis à votre fonction de rappel. Nous verrons les deux paramètres optionnels plus tard, mais pour l’instant, voici un exemple de add_action:
add_action('init', 'my_function_name');
function my_function_name() {
// Do your stuff
}Le premier paramètre à add_actionest le nom de l’action ; dans ce cas init, qui est un crochet WordPress assez courant qui se produit lors de l’initialisation. Le deuxième paramètre est votre rappel, dans ce cas le nom de la fonction que nous souhaitons exécuter. Ensuite, tout ce que vous avez à faire est de définir une fonction avec ce nom et d’y ajouter votre code.
Vous pouvez également utiliser des fonctions anonymes où vous définissez la fonction à l’intérieur add_actionau lieu de fournir un nom de fonction, comme ceci ;
add_action('init', function() {
// Do your stuff
});De nombreux développeurs préfèrent cette méthode car cela évite le risque de redéfinir une fonction PHP portant le même nom.
Si vous devez exécuter une fonction définie dans une classe PHP, vous devez fournir un tableau comme paramètre de rappel ; où le premier élément est l’objet de classe et le deuxième élément est le nom de la fonction :
class MyClass {
public function __construct() {
add_action('init', [$this, 'myFunctionName']);
}
public function myFunctionName() {
// Do your stuff
}
}Accrochage aux filtres
Pour s’accrocher à un filtre, on utilise la fonction add_filter(). Comme pour les actions ci-dessus, le premier paramètre est le nom du filtre et le second est votre rappel. Vous pouvez éventuellement fournir la priorité comme troisième paramètre et le nombre d’arguments comme quatrième. Voici un exemple de add_filter:
add_filter('the_title', 'my_function_name');
function my_function_name($title) {
// Do your stuff
return $title;
}Dans l’exemple ci-dessus, nous nous accrochons au filtre the_title(qui imprime le titre du message) et dit à WordPress d’exécuter notre fonction. Tous les filtres fourniront toujours un argument ; la variable à modifier. Dans ma fonction, je l’ai nommé $titlecar je sais qu’il contient le titre du message. À l’intérieur de la fonction, je peux la modifier ou remplacer complètement la variable. Il est important de se rappeler que dans les filtres, vous devez toujours renvoyer la variable. Si vous ne renvoyez rien dans votre fonction de rappel, la variable se vide. Si j’ignorais l’instruction de retour dans l’exemple ci-dessus, aucun titre de message ne ferait écho nulle part.
L’argument variable et la règle de retour de quelque chose dans votre fonction de rappel sont pratiquement la seule différence entre les filtres et les actions. Tout le reste fonctionne de la même manière. Vous pouvez suivre les exemples de fonctions et de classes anonymes indiqués pour les actions ci-dessus pour les filtres, ainsi que les paramètres facultatifs priorité et nombre d’arguments ; que nous examinerons ensuite.
Priorité
Le troisième paramètre (facultatif) de add_actionet add_filterest un entier qui définit la priorité de votre fonction de rappel. Ceci est utile dans les cas où il y a plusieurs fonctions (pas nécessairement de vous dans votre thème ou plugin, rappelez-vous que WordPress lui-même utilise ses propres crochets), et vous devez décider laquelle exécuter en premier.
Si aucune priorité n’est fournie, la valeur par défaut est 10. Plus la priorité est faible, plus il est exécuté tôt, et plus la priorité est élevée, plus il est exécuté tard. Vous ne pouvez pas fournir une priorité négative.
Imaginez plusieurs fonctions de rappel enregistrées dans init. Si aucune priorité n’a été fournie pour plusieurs rappels, WordPress les exécutera dans l’ordre dans lequel ils ont été trouvés (par exemple dans functions.phpou votre code de plugin).
add_action('init', 'my_function_name');
add_action('init', 'my_second_function_name');
add_action('init', 'my_third_function_name', 12);
add_action('init', 'my_fourth_function_name', 1);Ce serait l’ordre dans lequel WordPress exécutera les rappels ci-dessus :
my_fourth_function_name(priorité 1)my_function_name(priorité 10)my_second_function_name(priorité 10, mais apparaît plus tard dans le code)my_third_function_name(priorité 12)
Nombre d’arguments
Habituellement, les crochets fournissent des données supplémentaires qui sont pertinentes et utiles pour les fonctions de rappel. Par exemple, l’action save_post(s’exécute chaque fois qu’un article est mis à jour) fournit deux arguments possibles ; l’ID de publication et l’objet de publication. Celles-ci sont utiles pour les opérations que vous devez généralement exécuter sur ce crochet (par exemple, si vous souhaitez enregistrer une méta de publication, vous avez besoin de l’ID de publication).
Si aucun nombre d’arguments n’a été fourni pour une action ou un filtre, la valeur par défaut est 1. C’est pourquoi vous n’avez pas besoin de définir 1 add_filterpour accéder à la variable à laquelle le filtre est accroché. Les actions, cependant, ne peuvent transmettre aucun argument même si le nombre d’arguments est défini sur 1 par défaut.
Regardons un exemple de définition du nombre d’arguments et comment nous y accédons dans notre fonction de rappel :
add_action('save_post', 'my_function_name', 10, 2);
function my_function_name($post_id, $post) {
// Do your stuff
}Dans l’exemple ci-dessus, nous disons à WordPress de transmettre deux arguments à notre fonction de rappel. N’oubliez pas que nous devons définir la priorité comme troisième paramètre, nous définissons donc généralement la valeur par défaut, qui est 10. Quant à notre fonction de rappel, nous pouvons maintenant définir le même nombre d’arguments que nous avons demandé, dans l’exemple ci-dessus, c’était 2.
Si nous avions dans l’exemple ci-dessus défini le nombre d’arguments sur 1, seul le premier argument de notre fonction de rappel serait rempli. La seconde, $post, serait indéfinie.
Que se passe-t-il si nous avons besoin de données qui n’ont pas été transmises dans le hook ?
C’est entièrement au développeur qui a créé le crochet de définir quels arguments peuvent être passés. Cela signifie que vous ne pouvez pas simplement forcer les arguments que vous souhaitez ou dont vous avez besoin dans votre fichier add_actionou add_filter. Heureusement, dans la plupart des cas, nous avons des alternatives pour obtenir les variables dont nous avons besoin. Si vous vous connectez à une action ou à un filtre où vous savez que certaines variables globales doivent être définies, vous pouvez accéder à ces variables globales dans votre fonction de rappel. En outre, WordPress propose toute une gamme de balises conditionnelles que vous pouvez utiliser dans vos fonctions accrochées (à l’exception des tout premiers crochets qui se produisent avant que WordPress ne définisse ces balises conditionnelles)
Regardons un exemple d’accès aux variables globales. Le filtre the_titlefournit l’ID de publication comme argument facultatif, auquel nous pouvons accéder en le définissant comme argument acceptable ;
add_filter('the_title', 'my_function_name', 10, 2);
function my_function_name($title, $post_id) {
if ($post_id == 1) {
return 'First post ever!';
}
return $title;
}Cependant, nous pouvons obtenir le même résultat en;
Si vous savez qu’une variable globale est définie par le point d’exécution du hook, vous pouvez la définir comme globale dans votre fonction de rappel et accéder aux données à partir de là. Par exemple, définir global $wp_querydans l’exemple ci-dessus vous donnerait également accès à l’objet wp_query complet dans le rappel de votre fonction.
Les balises conditionnelles WordPress sont extrêmement utiles. À moins que vous ne soyez accroché à un crochet qui survient très tôt dans l’exécution de WordPress, ils sont disponibles. Il existe des balises conditionnelles pour vérifier à quelle page (modèle) vous vous trouvez, si vous êtes dans un menu ou une boucle de publication, et bien plus encore. Par exemple, lors de la modification de la requête post à l’aide du crochet pre_get_posts, il est très utile de s’assurer que votre code ne s’exécute que dans certains cas. Par exemple;
add_action('pre_get_posts', 'my_function_name');
function my_function_name($query) {
if (!is_admin()) {
// Do your stuff
}
}Étant donné que le hook pre_get_postss’exécute à la fois dans l’administrateur et le frontend, nous pouvons utiliser une balise conditionnelle pour nous assurer que notre code n’affecte que la requête frontend.
Créer vos propres crochets
Vous pouvez définir vos propres actions et filtres. Si vous êtes un développeur de thèmes ou de plugins, vous êtes encouragé à le faire, afin de permettre aux autres de modifier votre code sans changer le code source.
Enregistrez une action avec do_action()et enregistrez un filtre avec apply_filters().
Le do_action()nécessite un minimum de 1 paramètre ; le nom du crochet. Gardez à l’esprit que le nom du crochet doit être unique (ne l’appelez pas, par exemple init, car il s’agit d’un crochet principal de WordPress). Placez le do_action()où vous voulez que le crochet apparaisse. Par exemple, vous pouvez placer le crochet dans votre thème header.php, juste après le corps pour définir un crochet où les développeurs peuvent générer des scripts ou d’autres contenus.
Vous pouvez ajouter autant de paramètres do_actionque vous le souhaitez après le nom du crochet. Essayez de garder à l’esprit ce dont les développeurs de données auraient besoin dans vos crochets, qui ne sont pas facilement accessibles autrement.
Le apply_filters()nécessite un minimum de 2 paramètres ; le nom du hook et la variable sur laquelle vous enregistrez le filtre. Par exemple, votre thème peut inscrire un filtre autour de certaines classes HTML pour permettre aux développeurs de modifier ou d’en ajouter :
Comme pour les actions, vous pouvez ajouter autant de paramètres apply_filtersque vous le souhaitez après les deux paramètres obligatoires.
Conclusion et ressources utiles
Avec cela, j’espère que vous avez acquis une solide compréhension de la façon dont WordPress exécute la plupart de son code, comment vous pouvez modifier le code et comment vous, en tant que développeur, pouvez également permettre à d’autres développeurs d’apporter des modifications à votre code.