Exploitez la puissance des hooks WordPress : les actions et les filtres expliqués

Comme tout CMS, WordPress ne répondra pas toujours à tous vos besoins dès la sortie de la boîte. Puisqu'il est open-source, vous pouvez le pirater pour le rendre conforme aux besoins de votre entreprise, mais à la place, vous pouvez utiliser les crochets de WordPress pour atteindre vos objectifs. Construire avec des crochets est une stratégie gagnante qui permet aux développeurs WordPress de créer à peu près n'importe quelle fonctionnalité de site Web imaginable.

Hooks WordPress : actions et filtres

Les crochets WordPress ne sont pas seulement de puissants outils de personnalisation, ils sont la façon dont les composants WordPress interagissent les uns avec les autres. Les fonctions accrochées gèrent de nombreuses tâches de routine que nous considérons comme faisant partie intégrante de WordPress, telles que l'ajout de styles ou de scripts à une page, ou l'entourage du texte de pied de page avec des éléments HTML. Une recherche dans la base de code de WordPress Core révèle des milliers de crochets dans plus de 700 emplacements. Les thèmes et plugins WordPress contiennent encore plus de crochets.

Avant de sauter dans les crochets et d'explorer la différence entre les crochets d'action et les crochets de filtre, comprenons où ils s'intègrent dans l'architecture de WordPress.

Infrastructure WordPress

Les éléments modulaires de WordPress s'intègrent facilement les uns aux autres, nous pouvons donc facilement mélanger, assortir et combiner :

1. WordPress Core : Ce sont les fichiers nécessaires au fonctionnement de WordPress. WordPress Core fournit une architecture généralisée, le tableau de bord WP Admin, des requêtes de base de données, la sécurité, etc. WordPress Core est écrit en PHP et utilise une base de données MySQL.
2. Thème (ou thème parent) : un thème définit la mise en page et la conception de base d'un site Web. Propulsé par des fichiers PHP, HTML, JavaScript et CSS, un thème fonctionne en lisant la base de données WordPress MySQL pour générer le code HTML qui s'affiche dans un navigateur. Les crochets dans un thème peuvent ajouter des feuilles de style, des scripts, des polices ou des types de publication personnalisés, par exemple.
3. Thème enfant : nous créons nous-mêmes des thèmes enfants pour affiner la mise en page et la conception de base fournies par les thèmes parents. Les thèmes enfants peuvent définir des feuilles de style et des scripts pour modifier les fonctionnalités héritées ou ajouter ou supprimer des types de publication. Les instructions du thème enfant remplacent toujours celles du thème parent.
4. Plugin(s) : Pour étendre les fonctionnalités back-end de WordPress, nous pouvons choisir parmi des milliers de plugins tiers. Les crochets dans un plugin pourraient, par exemple, nous avertir par e-mail lorsqu'un message est publié ou masquer les commentaires soumis par les utilisateurs qui contiennent un langage interdit.
5. Plugin(s) personnalisé(s) : lorsqu'un plugin tiers ne répond pas entièrement aux besoins de l'entreprise, nous pouvons le booster en écrivant un plugin personnalisé en PHP. Ou nous pouvons écrire un nouveau plugin à partir de zéro. Dans les deux cas, nous ajouterions des crochets pour étendre les fonctionnalités existantes.

Étant donné que nous avons accès à la source des cinq couches, pourquoi les hooks sont-ils nécessaires dans WordPress ?

Code de sécurité

Pour suivre l'évolution des technologies, les contributeurs à WordPress Core, les thèmes parents et les plugins publient fréquemment des mises à jour pour atténuer les vulnérabilités de sécurité, corriger les bogues, résoudre les incompatibilités ou proposer de nouvelles fonctionnalités. Comme tout consultant ayant une expérience d'urgence le sait de première main, le fait de ne pas maintenir les composants WordPress à jour peut compromettre ou même désactiver un site.

Si nous modifions directement les copies locales des composants WordPress en amont, nous rencontrons un problème : les mises à jour écrasent nos personnalisations. Comment pouvons-nous contourner cela lors de la personnalisation de WordPress ? Via des crochets, dans le thème enfant et le(s) plugin(s) personnalisé(s).

Codage dans notre thème enfant

Un thème enfant est un espace sécurisé où nous pouvons personnaliser l'apparence de notre thème installé. Tout code ajouté ici remplacera le code comparable dans le parent sans risquer d'être écrasé par une mise à jour.

Lorsqu'un thème enfant est activé, il est lié à un parent désactivé, héritant et présentant les caractéristiques du parent tout en restant non impacté par les mises à jour du parent. Pour ne pas céder à la tentation de modifier un thème, les bonnes pratiques suggèrent d'activer un thème enfant dans le cadre de notre paramétrage.

Écrire des plugins personnalisés

Lorsqu'un plugin est activé, son fichier functions.php s'exécute à chaque appel sur le serveur. WordPress, à son tour, charge et trie les hooks de tous les plugins actifs en fonction de leur priorité et les exécute de manière séquentielle. Pour étendre les fonctionnalités d'un plugin tiers, nous pouvons écrire notre propre plugin WordPress personnalisé.

Où placer nos crochets dans WordPress

Préparation avant la plongée : définitions

Pour éviter de confondre les termes, nous nous en tiendrons à cette terminologie :

• Un crochet est un endroit idéal dans WordPress où les fonctions sont enregistrées pour s'exécuter. Nous pouvons connecter nos fonctions à l'un des nombreux crochets de WordPress et de ses composants ou créer les nôtres.
  • Un crochet d'action exécute des actions.
  • Un crochet de filtre exécute des filtres.
• Une fonction hookée est une fonction de rappel PHP personnalisée que nous avons « accrochée » à un emplacement de hook WordPress. Le type à utiliser dépend si le hook est destiné à autoriser des modifications en dehors de la fonction, par exemple, ajouter directement à la sortie de la page Web, modifier une base de données ou envoyer un e-mail. Ceux-ci sont connus comme des effets secondaires .
  • Un filtre (ou une fonction de filtre ) doit éviter les effets secondaires en ne travaillant que sur, puis en renvoyant une copie modifiée des données qui lui sont transmises.
  • Une action (ou fonction d'action ), en revanche, est destinée à provoquer des effets secondaires. Il n'a pas de valeur de retour.

Avec ces distinctions à l'esprit, nous pouvons commencer notre exploration des crochets.

Abstraction et code propre

Lorsqu'une action ou un filtre est intégré dans un hook, au besoin, nous remplissons les objectifs d'écrire une seule fonction par tâche et d'éviter la duplication de code au sein d'un projet. Par exemple, disons que nous voulons ajouter la même feuille de style à trois modèles de page (archive, page unique et publication personnalisée) dans notre thème. Plutôt que de remplacer chaque modèle dans le parent, puis de recréer chacun dans notre thème enfant, puis d'ajouter des feuilles de style à des sections d'en-tête individuelles, nous pouvons écrire du code dans une seule fonction et l'attacher avec le crochet wp_head .

Nomenclature réfléchie

Évitez de manière proactive les conflits en nommant un thème enfant ou des crochets de plug-in personnalisés de manière unique. Avoir des crochets du même nom dans un seul site est une recette pour un comportement de code involontaire. Les meilleures pratiques prescrivent que nous commencions le nom de notre crochet par un préfixe court et unique (par exemple, les initiales de l'auteur, du projet ou de l'entreprise), suivi d'un nom de crochet descriptif. Par exemple, en utilisant le modèle « project initials plus hook name », pour le projet Fabulous Plugin de Tahir, nous pourrions nommer nos hooks tfp-upload-document ou tfp-create-post-news .

Développement et débogage simultanés

Un crochet unique peut déclencher plusieurs actions ou filtres. Par exemple, nous pourrions écrire une page Web qui contient plusieurs scripts, qui utilisent tous le crochet d'action wp_head pour imprimer du HTML (par exemple, une section <style> ou <script> ) dans la section <head> sur le front-end de la page.

Ainsi, plusieurs développeurs de plugins peuvent faire avancer plusieurs objectifs en parallèle sur un seul plugin, ou diviser le plugin en plusieurs plugins individuels plus simples. Si une fonctionnalité ne fonctionne pas correctement, nous pouvons directement enquêter et déboguer sa fonction accrochée sans avoir à rechercher l'ensemble du projet.

Actions

Une action exécute du code lorsqu'un événement se produit dans WordPress. Les actions peuvent effectuer des opérations telles que :

• Création de données.
• Lecture de données.
• Modification des données.
• Suppression de données.
• Enregistrement des autorisations des utilisateurs connectés.
• Suivi des emplacements et stockage dans la base de données.

Voici des exemples d'événements où des actions peuvent être déclenchées :

• init , après le chargement de WordPress mais avant son envoi d'en-têtes au flux de sortie.
• save_post , lorsqu'un message a été enregistré.
• wp_create_nav_menu , juste après la création réussie d'un menu de navigation.

Une action peut interagir avec une API pour transmettre des données (par exemple, un lien vers une publication sur les réseaux sociaux), mais elle ne renverra pas de données au crochet appelant.

Disons que nous aimerions automatiser le partage de tous les nouveaux messages sur notre site via les médias sociaux. Commencez par parcourir la documentation de WordPress pour trouver un crochet qui peut être déclenché chaque fois qu'un article est publié.

Il n'y a pas de raccourci pour trouver notre hameçon : nous apprendrions par l'expérience ou nous nous pencherions sur les actions répertoriées pour trouver des candidats potentiels. Nous pourrions envisager save_post comme candidat, mais l'exclure rapidement car il se déclencherait plusieurs fois au cours d'une même session d'édition. Un meilleur choix est transition_post_status , qui ne se déclenche que lorsqu'un statut de publication est modifié (par exemple, de draft à publish , de publish à trash ).

Nous irons avec transition_post_status mais affinerons également notre action pour qu'elle ne s'exécute que lorsque le statut de notre publication passe à publish . De plus, en suivant la documentation officielle et les API des différentes plateformes de médias sociaux, nous pouvons intégrer et publier le contenu de notre publication, ainsi qu'une image en vedette :

 <?php function publish_post_on_social_media ( $new_status = NULL, $old_status = NULL, $post_ID = NULL ) { if ( 'publish' == $new_status && 'publish' != $old_status ) { // build the logic to share on social media } } add_action( 'transition_post_status', 'publish_post_on_social_media', 10, 3 ); ?>

Maintenant que nous savons comment utiliser les crochets d'action, il y en a un qui est particulièrement utile, surtout en ce qui concerne le CSS.

Désignation des priorités avec wp_enqueue_scripts

Supposons que nous voulions ajouter la feuille de style de notre thème enfant en dernier, après le chargement de toutes les autres, pour nous assurer que toutes les classes du même nom provenant d'ailleurs sont remplacées par les classes de notre thème enfant.

WordPress charge les feuilles de style dans un ordre par défaut :

1. Thème parent
2. Thème enfant
3. Tous les plugins

Dans cette construction :

 add_action( string $hook_name, callable $callback, int $priority = 10, int $accepted_args = 1)

… la valeur de priority de l'action ajoutée détermine son ordre d'exécution :

• La valeur de priority par défaut pour wp_enqueue_scripts (ou toute action) est "10".
• Une fonction s'exécute plus tôt si nous réinitialisons sa priority à un nombre inférieur.
• Une fonction s'exécute plus tard si nous réinitialisons sa priority à un nombre supérieur.

Pour charger la feuille de style de notre thème enfant en dernier, utilisez wp_enqueue_scripts , une action couramment utilisée par les thèmes et plugins WordPress. Nous n'avons qu'à changer la priorité de l'action wp_enqueue_scripts de notre thème enfant en un nombre supérieur à la valeur par défaut de "10", disons "99":

 add_action( 'wp_enqueue_scripts', 'child_theme_styles', 99 );

En général, nous utilisons des actions lorsque nous ne recherchons pas de valeurs de retour. Pour renvoyer des données au hook appelant, nous devons examiner les filtres.

Filtres

Un filtre nous permet de modifier les données avant qu'elles ne soient traitées pour être affichées dans un navigateur. À cette fin, un filtre accepte la ou les variable(s), modifie la ou les valeur(s) transmise(s) et renvoie des données pour un traitement ultérieur.

WordPress vérifie et exécute tous les filtres enregistrés avant de préparer le contenu pour les navigateurs. De cette façon, nous pouvons manipuler les données avant de les envoyer au navigateur ou à la base de données, selon le cas.

Un de mes clients personnalise les produits qu'il vend en y imprimant des images que les clients fournissent. Ce client utilise le plugin WooCommerce pour gérer le commerce électronique. WooCommerce ne prend pas en charge cette fonctionnalité prête à l'emploi. Par conséquent, j'ai ajouté deux morceaux de code au functions.php de mon client :

1. woocommerce_checkout_cart_item_quantity , répertorié dans la documentation WooCommerce, est un crochet de filtre qui permet aux clients d'ajouter des éléments externes à leurs paniers, avant le paiement.
2. my_customer_image_data_in_cart est un filtre que nous écrirons nous-mêmes et utiliserons pour déclencher woocommerce_checkout_cart_item_quantity chaque fois que WooCommerce prépare un panier à afficher.

En utilisant le modèle suivant, nous pouvons ajouter notre filtre et modifier le comportement par défaut du panier :

 add_filter( 'woocommerce_checkout_cart_item_quantity', 'my_customer_image_data_in_cart', 1, 3 ); function my_customer_image_data_in_cart( $html, $cart_item, $cart_item_key ) { if ( !empty( $cart_item['images_data'] ) ) { // Store image // Get image URL // Modify $html } return $html; }

Nous ajoutons des filtres de la même manière que nous ajoutons des actions. Les filtres fonctionnent de la même manière que les actions, y compris la façon dont les priorités sont traitées. La principale différence entre les filtres et les actions est qu'une action ne renverra pas de données au crochet appelant, mais un filtre le fera.

Crochets d'action et crochets de filtre personnalisés

L'écriture de crochets d'action personnalisés n'étend pas Wordpress Core mais crée simplement de nouveaux points de déclenchement dans notre propre code.

Création de crochets d'action personnalisés

L'ajout d'un crochet personnalisé dans notre thème ou plugin permet à d'autres développeurs d'étendre les fonctionnalités sans modifier notre base de code. Pour ajouter un crochet personnalisé, utilisez la même technique que la base de code WordPress Core elle-même utilise : au point de déclenchement souhaité, nous appelons simplement do_action avec le nom de notre nouveau crochet, en ajoutant éventuellement autant d'arguments que nos rappels pourraient trouver utiles :

 do_action( 'myorg_hello_action', $arg1, $arg2 );

Ce code exécute simplement toutes les fonctions de rappel qui ont été accrochées à notre crochet personnalisé. Notez que l'espace de noms est global, donc, comme suggéré précédemment, ce serait une bonne idée de faire précéder nos noms de hook personnalisés avec une forme abrégée du nom de notre organisation (et éventuellement de notre projet également), d'où le myorg_ ici.

Maintenant que nous avons défini myorg_hello_action , les développeurs peuvent s'y connecter exactement de la même manière que nous avons décrite précédemment pour les crochets intégrés : définissez une fonction, puis appelez add_action() .

À moins que nous ne souhaitions utiliser un nouveau hook de manière purement interne - c'est un moyen utile de structurer notre code, après tout - nous devrons communiquer sa disponibilité en aval, à d'autres membres de notre équipe ou à des utilisateurs externes de notre plugin, via une documentation claire .

Création de crochets de filtre personnalisés

Le modèle de WordPress pour les crochets de filtre personnalisés est le même que celui des crochets d'action, sauf que nous appelons apply_filters() au lieu de do_action() .

Prenons un exemple plus concret cette fois. Supposons que notre plugin crée un menu latéral, qui se compose normalement de quatre éléments. Nous ajouterons un crochet de filtre personnalisé afin que nous (et les développeurs en aval) puissions modifier cette liste d'éléments ailleurs :

 // Text labels of sidebar menu $sidebar_menu = array( "Page One", "Page Two", "Page Three", "Page Four" ); $sidebar_menu = apply_filters( 'myorg_sidebar_menu', $sidebar_menu );

C'est tout — notre hook de filtre personnalisé myorg_sidebar_menu est maintenant prêt à être utilisé dans un plugin qui peut être chargé plus tard ou ailleurs dans celui-ci. Cela permet à quiconque écrit du code en aval de personnaliser notre barre latérale.

Nous ou d'autres développeurs suivrons le même modèle lors de l'utilisation d'un crochet WordPress intégré. En d'autres termes, nous commencerons par définir certaines fonctions de rappel qui renvoient une version modifiée des données qui leur sont transmises :

 function lowercase_sidebar_menu( $menu ) { $menu = array_map( 'strtolower', $menu ); return $menu; } function add_donate_item( $menu ) { $menu = array_push( $menu, 'Donate' ); return $menu; }

Comme pour nos exemples précédents, nous sommes maintenant prêts à raccorder nos fonctions de rappel de filtre à notre crochet personnalisé :

 add_filter( 'myorg_sidebar_menu', 'add_donate_item', 100 ); add_filter( 'myorg_sidebar_menu', 'lowercase_sidebar_menu' );

Avec cela, nous avons accroché nos deux exemples de fonctions de rappel à notre crochet de filtre personnalisé. Les deux modifient maintenant le contenu original de $the_sidebar_menu . Parce que nous avons donné une valeur de priority plus élevée à add_donate_item , il s'exécute plus tard, après l'exécution de lowercase_sidebar_menu .

Les développeurs en aval sont toujours libres d'accrocher plus de fonctions de rappel à myorg_sidebar_menu . Comme ils le font, ils peuvent utiliser le paramètre de priority pour que leurs crochets s'exécutent avant, après ou entre nos deux exemples de fonctions de rappel.

Le ciel est la limite avec des actions et des filtres

Avec des actions, des filtres et des hooks, la fonctionnalité WordPress peut croître à pas de géant. Nous pouvons développer des fonctionnalités personnalisées pour notre site, laissant nos propres contributions aussi extensibles que WordPress. Les crochets nous permettent de respecter la sécurité et les meilleures pratiques alors que nous faisons passer notre site WordPress au niveau supérieur.

Le blog Toptal Engineering exprime sa gratitude à Fahad Murtaza pour son expertise, ses tests bêta et sa révision technique de cet article.