WordPress: Comment utiliser les actions, les filtres et les hooks personnalisés

WordPress: Comment utiliser les actions, les filtres et les hooks personnalisés

Les Hooks sont l’un des outils les plus importants à avoir dans l’arsenal d’un développeur . Ils constituent la base du développement de plugins et de thèmes . Vous pouvez utiliser les nombreux crochets intégrés de pour vous « accrocher » au noyau avec votre code personnalisé et faire ou modifier quelque chose.

Il existe deux types de hooks : Actions et Filtres. Les crochets sont si courants que même Core les utilise lui-même largement. inclut également un moyen pour vous de définir le vôtre crochets personnalisés afin que d’autres développeurs puissent se connecter à votre code.

Apprendre comment fonctionnent les actions, les filtres et les crochets personnalisés est essentiel pour maîtriser le développement .

La première moitié de cet article couvre les bases des hooks et explique comment ils fonctionnent avec plusieurs exemples. Dans la seconde moitié, vous apprendrez comment utiliser des crochets pour personnaliser , créer vos propres crochets personnalisés et les utiliser pour créer vos propres plugins extensibles.

Cela semble excitant ? Plongeons dedans !

Que sont les crochets ?

Une page est assemblée par des tonnes de fonctions et de requêtes de base de données. Le noyau , les plugins et le thème fonctionnent ensemble pour générer des éléments de page tels que du texte, des images, des scripts et des styles. Une fois entièrement assemblés, le navigateur les assemble ensuite et affiche la page.

Les hooks vous permettent de vous « accrocher » à ce processus de construction à certains moments et d’exécuter votre code personnalisé. La fonction principale des hooks est de vous permettre de modifier ou d’ajouter des fonctionnalités à sans toucher aux fichiers principaux.

Une représentation graphique du fonctionnement des Hooks WordPress
Les crochets vous aideront à étendre avec votre propre code

L’API du plugin alimente la fonctionnalité des crochets . Vous utilisez des hooks en appelant certaines fonctions appelées Fonctions de crochet à des instances spécifiques pendant l’exécution de .

En utilisant les fonctions hook, vous pouvez regrouper votre code personnalisé dans un Fonction de rappel et faites-le enregistrer avec n’importe quel crochet. Une fois enregistré, ce rappel s’exécutera partout où se trouve le crochet, vous permettant d’augmenter ou de remplacer les fonctionnalités par défaut de .

La position du hook dans le processus d’exécution du code est un facteur important. Vous en apprendrez plus sur sa signification dans les sections à venir.

Devenez accro à #webdev avec ce guide des crochets . ️Cliquez pour tweeter

Deux types de crochets : actions et filtres

comprend deux types de crochets appelés Actions et Filtres. Les actions vous permettent faire quelque chose à certains points prédéfinis dans le runtime , tandis que les filtres vous permettent modifier toutes les données traitées par et return ce.

Les actions sont définies dans le code comme :

do_action( 'action_name', [optional_arguments] );

le action_name chaîne est le nom de l’action. Vous pouvez spécifier le [optional_arguments] variable pour passer des arguments supplémentaires à la fonction de rappel. Si ce champ n’est pas spécifié, sa valeur par défaut sera vide.

Exemple: le do_action( 'wp_head' ) L’action peut être connectée pour exécuter un code personnalisé à chaque fois que traite l’en-tête du site. Cette action n’a pas d’autres arguments.

Les filtres sont définis dans le code comme :

apply_filters( 'filter_name', 'value_to_be_filtered', [optional_arguments] );

le filter_name string est le nom du filtre, le value_to_be_filtered variable est la valeur qui doit être filtrée et renvoyée, et le [optional_arguments] variable peut passer des arguments supplémentaires, tout comme avec les actions.

Exemple: le apply_filters( 'admin_footer_text' , string $text ) filter peut être accroché pour modifier le texte affiché dans le pied de page admin. À partir de 5.4, sa valeur par défaut affichera la phrase Thank you for creating with . dans le pied de page de la zone d’administration.

Vous apprendrez plus tard à vous connecter aux actions et aux filtres avec de nombreux exemples du noyau .

Une fois accroché, vous pouvez diriger votre code vers faire ou Personnaliser quelque chose sur votre site. Par exemple, vous pouvez utiliser des crochets pour envoyer un e-mail automatisé après la publication d’un article, ou charger des feuilles de style personnalisées pour modifier l’apparence de votre site.

Imaginer s'accrocher à des actions et des filtres comme construire une maison
Les crochets vous aident à interagir avec ou à modifier votre site Web

La façon la plus simple de comprendre les crochets est d’imaginer votre site comme la construction d’une maison.

Les crochets s’apparentent à l’utilisation d’une grue pour déplacer des éléments de construction d’avant en arrière. Les éléments transférés sont les Fonctions de rappel qui incluent votre code personnalisé. Ces éléments (ou fonctions) peuvent vous aider à construire ou à modifier la maison.

Un exemple de connexion à l'action 'wp_head' dans WordPress à l'aide de l'exemple maison
Exemple de connexion à l’action ‘wp_head’ dans

Les fonctions de rappel peuvent être des fonctions PHP normales, des fonctions par défaut ou des fonctions personnalisées définies par vous.

Nous ne pouvons transporter certains articles que sur des supports spécifiques attachés à des crochets particuliers. Ainsi, les actions ne peuvent être accrochées qu’avec Fonctions d’action. De même, les filtres ne peuvent être accrochés qu’avec Fonctions de filtrage.

Bien qu’il soit fastidieux de changer les crochets et les supports sur une grue, le rend très facile en incluant plus de 2 200 types de crochets par défaut.

Un graphique montrant la prolifération des hooks WordPress au fil du temps
5.1 a plus de 2200 crochets natifs (Source : Adam Brown)

Vous pouvez trouver des crochets répartis dans le noyau , vous permettant de puiser dans la position exacte où vous souhaitez vous connecter et exécuter votre code personnalisé.

Les crochets vous permettent de vous « accrocher » au processus de création de page… et vous donnent plus de contrôle sur ce que vous créez.⚡️Cliquez pour tweeter

Crochets vs Actions vs Filtres

Selon le manuel du plugin  :

« Les crochets sont un moyen pour un morceau de code d’interagir/de modifier un autre morceau de code… Il existe deux types de crochets : les actions et les filtres.« 

Il y a une incohérence généralisée avec la façon dont les termes Accrocher, action, et Filtre sont utilisés. Quelques tutoriels et guides les mélangent avec les fonctions qui leur sont associées. L’une des principales raisons pour lesquelles cette confusion existe est la nature complexe du fonctionnement des crochets.

Même lorsque vous regardez attentivement à l’intérieur du noyau , vous constaterez qu’il n’y a pas beaucoup de différence entre l’ajout d’actions et de filtres. Voici le code source de la fonction add_action() du wp-includes/plugin.php déposer:

function add_action( $tag, $function_to_add, $priority = 10, $accepted_args = 1 ) {      
    return add_filter( $tag, $function_to_add, $priority, $accepted_args );
}

le add_action() la fonction appelle simplement le add_filter() fonction et renvoie sa valeur. Pourquoi? Parce qu’ils fonctionnent tous les deux fondamentalement de la même manière, à une différence près.

le apply_filters() La fonction renvoie une valeur qui peut modifier les types de données existants, tandis que la fonction do_action() la fonction ne renvoie rien (valeur NULL en PHP).

Si vous êtes toujours confus, ne vous inquiétez pas ! Une fois que vous aurez terminé la première moitié de cet article, tout sera clair. Nous nous en tiendrons à la terminologie officielle du Codex car elle est claire, précise et universelle.

Pour l’instant, familiarisez-vous avec la routine de crochet illustrée ci-dessous.

Une infographie représentant une « routine de crochet » typique dans WordPress
La routine de crochet : crochets, fonctions de crochet et fonctions de rappel

Décomposons les différences entre les actions et les crochets.

Crochets
ActionsFiltres
Les actions sont utilisées pour exécuter des fonctions personnalisées à un moment spécifique lors de l’exécution de Core.Les filtres sont utilisés pour modifier ou personnaliser les données utilisées par d’autres fonctions.
Les actions sont définies/créées par la fonction do_action( ‘action_name’ ) dans le code .Les filtres sont définis/créés par la fonction apply_filters( ‘filter_name’, ‘value_to_be_filtered’ ) dans le code .
Les actions sont aussi appelées Crochets d’action.Les filtres sont aussi appelés Crochets de filtre.
Les actions ne peuvent être connectées qu’avec des fonctions d’action. Par exemple. add_action(), remove_action().Les filtres ne peuvent être connectés qu’avec les fonctions de filtre. Par exemple. add_filter(), remove_filter().
Les fonctions d’action n’ont pas besoin de passer d’arguments à leurs fonctions de rappel.Les fonctions de filtrage doivent passer au moins un argument à leurs fonctions de rappel.
Les fonctions d’action peuvent effectuer tout type de tâche, y compris modifier le comportement de .Les fonctions de filtrage n’existent que pour modifier les données qui leur sont transmises par les filtres.
Les fonctions d’action doivent return rien. Cependant, ils peuvent echo la sortie ou interagir avec la base de données.Les fonctions de filtrage doivent return leurs changements en sortie. Même si une fonction de filtrage ne change rien, elle doit quand même return l’entrée non modifiée.
Les actions peuvent exécuter presque n’importe quoi, tant que le code est valide.Les filtres doivent fonctionner de manière isolée, afin qu’ils n’aient pas d’effets secondaires indésirables.
Résumé: Une action interrompt le processus d’exécution de code normal pour faire quelque chose avec les informations qu’elle reçoit, mais ne renvoie rien en retour, puis se termine.Résumé: Un filtre modifie les informations qu’il reçoit, les renvoie à la fonction hook appelante et d’autres fonctions peuvent utiliser la valeur qu’il renvoie.

Parfois, vous pouvez utiliser une action ou un filtre pour atteindre le même objectif. Par exemple, si vous souhaitez modifier le texte d’une publication, vous pouvez enregistrer une fonction de rappel avec l’action publish_post et modifier le contenu de la publication lors de son enregistrement dans la base de données.

// define the callback function to change the text
function change_text_callback() { 
    // add the code to change text here
}

// hook in to the 'publish_post' action with the add_action() function
add_action( 'publish_post', 'change_text_callback' );

Ou vous pouvez enregistrer une autre fonction de rappel avec the_content filter pour modifier le contenu de la publication avant qu’il ne soit affiché dans le navigateur.

// define the callback function to modify the text
function change_text_another_callback( $content ) { 
    // add the code to change text here and then return it 
    return $filtered_content;
}

// hook in to 'the_content' filter with the add_filter() function
add_filter( 'the_content', 'change_text_another_callback');

Deux approches différentes avec le même résultat. Savoir quand utiliser l’un plutôt que l’autre est essentiel pour être un bon développeur .

Comment fonctionnent les crochets ?

L’exemple de la maison était suffisamment simple pour comprendre le fonctionnement de base des crochets, mais il ne rend pas compte de la complexité de leur fonctionnement. Plus important encore, les concepts de position et de spécificité du crochet.

Un meilleur exemple serait d’imaginer traiter une page Web comme assembler une voiture. Contrairement à la fabrication d’une voiture, qui prend du temps, l’assemblage d’une page Web est presque instantané.

Un graphique montrant que l'assemblage d'une page Web est similaire à l'assemblage d'un véhicule
Assembler une page Web, c’est comme assembler une voiture

Tout comme une voiture est assemblée pièce par pièce dans une chaîne de montage moderne, une page Web est assemblée élément par élément par le serveur et le client.

Le noyau est comme le moteur de la voiture, le châssis et d’autres éléments essentiels, alimentant la fonctionnalité « de base » du site Web.

Vous pouvez avoir un site Web fonctionnel avec uniquement le noyau , mais où est le plaisir là-dedans ? Vous devez ajouter des fonctionnalités intéressantes au site. C’est là qu’interviennent les plugins et les thèmes , qui utilisent tous deux des hooks de manière intensive.

Dans l’exemple ci-dessus, chaque station numérotée est comme un crochet à l’intérieur du noyau . Il existe deux types de stations, comme les actions et les filtres. Chaque station comprend un type de slot spécifique qui n’accepte que certains outils, apparentés aux fonctions d’action et aux fonctions de filtrage.

Toutes les stations sont placées à intervalles fréquents pour plus de modularité et d’efficacité.

Selon les exigences d’un poste particulier, nous pouvons attacher (ou accrocher) l’outil le plus approprié pour le travail à ce poste spécifique. Ces outils sont comme les fonctions de rappel utilisées pour interagir avec ou modifier .

Certains outils peuvent modifier considérablement le fonctionnement de la voiture, un peu comme les rappels enregistrés pour les actions. D’autres outils ne sont utilisés que pour personnaliser l’apparence de la voiture, comme les rappels enregistrés dans les filtres.

L’utilisation des bons outils aux bonnes stations est cruciale pour construire une voiture de premier ordre. De la même manière, les crochets nous aident à personnaliser en fonction de nos besoins uniques.

Si vous étendez cette analogie, les plugins sont comme ajouter des fonctionnalités automobiles utiles telles que des airbags, une console de divertissement, un système sans clé à distance, etc. (comme ceux-ci pour améliorer les fonctionnalités de WooCommerce). Les thèmes sont analogues à la personnalisation de la partie visuelle de la voiture, comme la conception globale, le travail de peinture, les jantes, etc. (voici comment personnaliser votre thème ).

Où enregistrer les crochets et leurs fonctions ?

Il y a deux manières recommandées d’ajouter des crochets dans :

Pour ce tutoriel, commençons par créer un plugin. Pour ce faire, créez un nouveau dossier dans votre /wp-content/plugins/ annuaire.

Je nomme mon plugin salhooks, mais vous pouvez le nommer comme vous voulez. Conformément aux directives de , vous devez créer un fichier PHP avec le même nom (salhooks.php) dans votre répertoire de plugins.

Ajoutez les champs d’en-tête suivants à votre fichier de plugin pour l’enregistrer avec . Vous pouvez en savoir plus sur les exigences d’en-tête de plugin dans le Codex .

Enregistrez ce fichier puis activez le plugin dans votre tableau de bord . J'utiliserai ce plugin dans une installation locale pour montrer comment fonctionnent les hooks.

En remarque, vous pouvez également modifier les fichiers Core directement pour enregistrer les hooks. Cependant, ce n'est pas recommandé car tout votre code personnalisé sera écrasé chaque fois que vous mettez à jour . Vous ne devriez pas ajouter de crochets dans votre thème parent pour la même raison.

Utiliser les crochets

Un hook en lui-même ne fait rien. Il se trouve juste dans le code, attendant qu'une fonction de crochet l'active. Pour utiliser un hook, vous devez appeler au moins 2 autres fonctions.

Tout d'abord, vous devez enregistrer le hook avec une fonction de hook et y référencer une fonction de rappel. Et puis vous devez définir la fonction de rappel que vous avez mentionnée plus tôt dans la fonction hook. exécutera cette fonction de rappel à chaque fois que le hook est déclenché.

L'ordre dans lequel vous définissez ces fonctions n'a pas d'importance, mais c'est une bonne idée de les placer proches les unes des autres.

Les actions et les filtres ont des fonctions de hook distinctes. À partir de maintenant, appelons-les Fonctions d'action et Fonctions de filtrage. Comme vous le verrez, ils ont leurs propres exigences en matière de syntaxe et de paramètres.

Accrocher une action

Les actions fournissent un moyen d'exécuter votre code personnalisé à un moment particulier de l'exécution de Core, des plugins ou des thèmes.

La fonction d'action add_action()

Vous pouvez enregistrer une fonction de rappel avec une action en suivant ces étapes :

  1. Définir un Fonction de rappel avec votre code personnalisé à l'intérieur. Cette fonction de rappel s'exécutera lorsqu'une action pour laquelle elle est enregistrée est déclenchée pendant l'exécution du code de .
  2. Accrochez votre fonction de rappel à l'action que vous voulez avec le add_action() une fonction. Selon le Codex , la fonction add_action() doit passer au moins deux paramètres :
      • Nom de l'action à laquelle se connecter.
      • Nom de la fonction de rappel qui s'exécutera lorsque l'action sera déclenchée.
  3. le add_action() La fonction accepte également deux paramètres facultatifs pour régler le priority et le number of arguments. Nous discuterons des deux plus tard.

Il est recommandé de nommer les paramètres de votre fonction de rappel aussi près que possible des paramètres passés par la fonction hook.

Regardons un exemple d'utilisation du add_action() une fonction.

// define the callback function, the arguments are optional
function example_callback( $arg1, $arg2 ) {
    // make your code do something with the arguments
}

// hook the callback function to the 'example_action'
add_action( 'example_action', 'example_callback', [priority], [no_of_args] );

// 'priority' and 'number of arguments' are optional parameters

Exemple d'accrochage d'une action

inclut une action intégrée appelée init qui se déclenche une fois que a fini de charger et authentifié l'utilisateur, mais avant que les en-têtes ne soient envoyés. De nombreux plugins utilisent ce crochet comme point de départ pour instancier leur code, car presque toutes les principales fonctionnalités de ont fini de se charger au moment où exécute cette action.

a une action similaire appelée admin_init. Il se déclenche pendant l'initialisation de l'écran d'administration, tandis que le init l'action ne se déclenche qu'une fois le chargement de terminé.

Exécutons un code personnalisé pour echo un message simple lors de l'exécution de init action. Voici comment procéder :

function custom_callback_function(){
    // add your custom code here to do something
    echo 'I will be fired on  initialization';
}
add_action( 'init', 'custom_callback_function' );

Vous pouvez voir le message se répercuter dans le coin supérieur gauche de mon installation locale.

Faire écho à un message à l'aide du crochet d'action init dans WordPress
Pas si joli, mais c'est un bon début !

Recherche d'actions prises en charge par

inclut des actions à chaque fois qu'il fait quelque chose, comme un utilisateur se connectant ou publiant un nouveau message. Vous pouvez trouver une liste complète de toutes les actions exécutées par dans la page Plugin API/Action Reference.

Page de référence des actions de la section API du plugin dans le codex WordPress
Il y a une action pour presque chaque utilisation

Le Codex a divisé toutes les actions qui y sont répertoriées en différentes catégories et les a classées de la première à la dernière dans l'ordre d'exécution de .

Dans la plupart des cas, bon nombre de ces actions ne feront rien car rien n'y est lié. Mais si vous en avez besoin, ils sont là pour vous accrocher.

Vous vous sentez un peu dépassé par toutes les actions ? C'est naturel. Au fur et à mesure que vous gagnerez en expérience et que vous parcourrez le code source de Core, il deviendra plus facile de trouver le crochet parfait pour vos besoins. Effectuez simplement une recherche pour le terme "faire_action" et vous trouverez de nombreuses actions auxquelles vous pouvez vous accrocher.

Paramètres supplémentaires pour add_action()

le add_action() fonction peut accepter deux autres paramètres : un pour régler le priority et l'autre pour régler le number of arguments. Bien qu'ils soient facultatifs, s'ils sont utilisés correctement, ils peuvent être très utiles.

Priorité

Le premier paramètre supplémentaire pris en charge par add_action() la fonction définit le priority. Ce paramètre ne peut être qu'un entier positif. Plus le numéro de priorité est bas, plus la fonction s'exécutera tôt. Sa valeur par défaut est 10 si vous ne le spécifiez pas.

Pour voir comment cela fonctionne, enregistrons trois fonctions de rappel dans le init action, mais chacun avec des priorités différentes.

// priority is set to 9, which is lower than 10, hence it ranks higher
add_action( 'init', 'i_am_high_priority', 9 );

// if no priority is set, the default value of 10 will be used
add_action( 'init', 'i_am_default_priority');

// priority is set to 11, which is higher than 11, hence it ranks lower
add_action( 'init', 'i_am_low_priority', 11 );

Dans les exemples ci-dessus, la fonction de rappel avec le numéro de priorité le plus bas s'exécutera en premier et celle avec le numéro le plus élevé s'exécutera en dernier. Si leurs priorités sont les mêmes, ils seront exécutés dans l'ordre dans lequel vous les enregistrez.

La priorité joue un rôle important lorsqu'un seul hook peut avoir plusieurs fonctions de rappel enregistrées avec lui. Pour éviter des résultats inattendus, vous pouvez définir une priorité pour chaque fonction de rappel, afin qu'elles se déclenchent dans l'ordre que vous souhaitez.

Nombre d'arguments

Par défaut, toute fonction de rappel enregistrée via le add_action() fonction ne recevra qu'un seul argument. Cependant, vous devrez parfois transmettre des données supplémentaires à la fonction de rappel.

Pour cette raison le add_action() La fonction accepte un paramètre facultatif pour définir le nombre d'arguments.

Un bon exemple pour montrer ceci est l'action comment_post. Cette action s'exécute immédiatement après que a ajouté un commentaire à la base de données. Si vous ne définissez pas le number of arguments paramètre, il ne passera qu'une seule valeur à la fonction de rappel, qui dans ce cas sera le comment_ID.

// register the hook with 'priority' and 'number of arguments' parameters
add_action( 'comment_post', 'show_message_function', 10, 3 );

// define the callback function
function show_message_function( $comment_ID, $comment_approved, $commentdata ) {
    // check whether a comment is approved with the second parameter
    if( 1 === $comment_approved ){
        // runs the code only if the comment is approved
    }
}

Si vous définissez le nombre d'arguments paramètre à 3 comme dans l'exemple ci-dessus, la fonction d'action passera trois valeurs : comment_ID, comment_approved, et commentdata.

définit le comment_approved valeur à 1 pour les commentaires approuvés, 0 s'il n'est pas approuvé, et 'pourriel‘ si le commentaire est marqué comme spam.

le commentdata La variable est un tableau qui inclut toutes les données du commentaire, comme le nom de l'auteur du commentaire, son adresse e-mail, son site Web et le contenu du commentaire lui-même. Vous pouvez consulter le Codex pour trouver toutes les paires clé-valeur incluses dans le tableau « commentdata ».

Vous pouvez avoir autant d'arguments que vous le souhaitez, mais la fonction de rappel et le add_action() fonction doit spécifier le même nombre d'arguments.

En passant des paramètres supplémentaires à la fonction de rappel, vous pouvez faire plus avec votre code. Par exemple, vous pouvez vérifier si un commentaire est approuvé ou non et envoyer automatiquement le texte du commentaire à l'administrateur s'il est approuvé. Il n'est pas possible de le faire sans spécifier les arguments supplémentaires car votre fonction de rappel n'aura pas accès au comment_content Les données.

Si vous ne souhaitez pas définir la priorité, mais uniquement modifier le nombre d'arguments, vous devez toujours définir une priorité. Utilisez simplement sa valeur par défaut (c'est-à-dire 10).

Comment Core utilise les actions

Core lui-même utilise bon nombre de ses actions intégrées pour exécuter diverses fonctions.

Prenez l'action wp_head par exemple. Il est déclenché lorsque affiche la section d'en-tête des pages Web (le code qui va entre et ).

Vous pouvez trouver la plupart des fonctions d'action de Core liées au wp_head crochet dans le wp-includes/default-filters.php déposer. J'ai parcouru le code et compilé une liste de tous les add_action() fonctions qui invoquent le wp_head action.

add_action( 'wp_head', 'rest_output_link_wp_head', 10, 0 );
add_action( 'wp_head', '_wp_render_title_tag', 1 );
add_action( 'wp_head', 'wp_enqueue_scripts', 1 );
add_action( 'wp_head', 'wp_resource_hints', 2 );
add_action( 'wp_head', 'feed_links', 2 );
add_action( 'wp_head', 'feed_links_extra', 3 );
add_action( 'wp_head', 'rsd_link' );
add_action( 'wp_head', 'wlwmanifest_link' );
add_action( 'wp_head', 'adjacent_posts_rel_link_wp_head', 10, 0 );
add_action( 'wp_head', 'locale_stylesheet' );
add_action( 'wp_head', 'noindex', 1 );
add_action( 'wp_head', 'print_emoji_detection_script', 7 );
add_action( 'wp_head', 'wp_print_styles', 8 );
add_action( 'wp_head', 'wp_print_head_scripts', 9 );
add_action( 'wp_head', 'wp_generator' );
add_action( 'wp_head', 'rel_canonical' );
add_action( 'wp_head', 'wp_shortlink_wp_head', 10, 0 );
add_action( 'wp_head', 'wp_custom_css_cb', 101 );
add_action( 'wp_head', 'wp_site_icon', 99 );
add_action( 'wp_head', 'wp_no_robots' );

Cela fait beaucoup de fonctions de rappel liées à une seule action. Réglage de la priority ici est crucial pour s'assurer que les fonctions hookées les plus importantes s'exécutent en premier.

Dans l'exemple ci-dessus, le chargement des scripts avec wp_enqueue_scripts() la fonction de rappel est plus importante (priorité = 1) que le chargement des balises méta de l'icône du site avec wp_site_icon() fonction de rappel (priorité = 99).

Autres fonctions d'action

Tandis que add_action() est la fonction d'action la plus utilisée, il y en a beaucoup d'autres qui sont tout aussi utiles. Voyons comment ils fonctionnent tous.

Cette fonction d'action vérifie si une action a été accrochée. Il accepte deux paramètres. Le premier est le nom de l'action. Le deuxième paramètre est facultatif et correspond au nom de la fonction de rappel.

has_action( 'action_name', 'function_to_check' );

Si vous ne spécifiez que le premier paramètre, il renvoie true si quelconque la fonction est liée au action_name paramètre.

Mais si vous spécifiez également le deuxième paramètre, il retournera false si la fonction de rappel spécifiée n'est pas enregistrée dans l'action mentionnée.

S'il trouve la fonction de rappel attachée au crochet d'action, il renverra le priority (un entier) défini pour cette fonction sur ce hook d'action.

Nous avons déjà rencontré cette fonction d'action. l'utilise pour définir toutes ses actions par défaut, permettant à d'autres fonctions de s'y connecter. Tout comme , vous pouvez également utiliser le do_action() pour créer une nouvelle action personnalisée en spécifiant un nouveau nom d'action comme paramètre.

do_action( 'action_name', [argument1], [argument2] );

Le simple fait de déclarer cette fonction ne fera rien en soi. Mais il restera dans le code, en attendant que d'autres fonctions d'action l'activent. Le passage d'arguments supplémentaires est facultatif, mais il est important si vous souhaitez que vos fonctions de rappel les utilisent.

Cette fonction d'action est identique à do_action(), à une différence près. Tous les arguments qui y sont passés doivent être un tableau. Lorsque vous avez beaucoup d'arguments à transmettre ou que vos arguments sont déjà dans un tableau, cette fonction est très utile.

// here's an example array
$arguments_array = array( 'arg_1', 'foo', true, 'arg_4' );

do_action_ref_array( 'example_action', $arguments_array );

Étant donné que les tableaux PHP sont une carte ordonnée, assurez-vous que les arguments que vous transmettez sont dans le bon ordre.

Un exemple d'utilisation de cette fonction d'action est l'action admin_bar_menu. Il peut être connecté pour ajouter, manipuler ou supprimer les différents éléments de la barre d'administration. Tous les éléments de la barre d'administration sont définis comme des éléments d'un tableau.

Si vous souhaitez compter le nombre de fois qu'une action est déclenchée, vous pouvez appeler cette fonction d'action.

did_action( 'action_name' );

Cette fonction renvoie une valeur entière.

le did_action() La fonction est extrêmement pratique lorsque vous souhaitez exécuter une fonction de rappel uniquement la première fois qu'une action est exécutée et plus jamais.

function example_callback_function() {
    if( did_action( 'example_action' ) === 1 ) {
    // checks if the 'example_action' hook is fired once, and only runs then, and never again!
    }
}
add_action('example_action', 'example_callback_function');

Cette fonction d'action supprime une fonction de rappel liée à l'action spécifiée. Par exemple, vous pouvez utiliser cette fonction pour supprimer les fonctions par défaut liées aux actions intégrées et les remplacer par les vôtres.

remove_action( 'action_name', 'function_to_be_removed', [priority] );

Il y a quelques prérequis pour appeler le remove_action() une fonction:

  1. le function_to_be_removed et priority les paramètres doivent être les mêmes que ceux utilisés à l'origine dans le add_action() une fonction.
  2. Vous ne pouvez pas appeler le remove_action() fonctionner directement. Vous devez l'appeler depuis une autre fonction.
  3. Si la fonction de rappel est enregistrée à partir d'un classer, puis le supprimer a d'autres exigences. Vous pouvez consulter la documentation Codex pour plus de détails.
  4. Vous ne pouvez pas supprimer la fonction de rappel avant qu'elle ne soit enregistrée ou après son exécution.

Voici un exemple de la façon dont WooCommerce utilise cette fonction d'action pour supprimer la vignette du produit par défaut sur la page principale de la boutique.

remove_action( 'woocommerce_before_shop_loop_item_title', 'woocommerce_template_loop_product_thumbnail', 10 );

Cette fonction d'action supprime tout ce qui est lié à une action. Le paramètre de priorité est facultatif.

remove_all_actions( 'action_name', [priority] );

N'oubliez pas que cette fonction ne peut pas être appelée à partir de l'action dont vous souhaitez annuler l'enregistrement des fonctions de rappel. Cela provoquerait une boucle infinie. Vous pouvez vous connecter à une action déclenchée plus tôt pour exécuter cette fonction sans aucune erreur.

Cette fonction d'action vérifie si l'action spécifiée est exécutée ou non. Il renvoie une valeur booléenne (true ou false).

// check whether the 'action_name' action is being executed
if ( doing_action( 'action_name' ) ) {
    // execute your code here
}

Vous pouvez laisser le action_name paramètre vide pour vérifier si quelconque l'action est en cours d'exécution. ça reviendra true chaque fois qu'une action est déclenchée.

// check if any action is running and do something
if ( doing_action() ) {
    // the code here is run when any action is fired
}

Actions Exemple 1 : Afficher un message de maintenance aux visiteurs de votre site

Parfois, il est préférable de mettre votre site hors ligne et de créer une page En cours de maintenance. Heureusement, fournit un moyen simple de le faire.

// show a maintenance message for all your site visitors
add_action( 'get_header', 'maintenance_message' );
function maintenance_message() {
    if (current_user_can( 'edit_posts' )) return;
    wp_die( '

Stay Pawsitive!


Sorry, we're temporarily down for maintenance right meow.' ); }

Décomposons le code et passons en revue chaque étape :

  • get_header est une action déclenchée avant le chargement du fichier de modèle d'en-tête du site. C'est une action parfaite à laquelle vous connecter si vous souhaitez interrompre le chargement du site principal.
  • Accrochez-vous au get_header action en utilisant le add_action() fonctionner avec le maintenance_message() fonction de rappel.
  • Définir les maintenance_message() fonction de rappel.
  • current_user_can( 'edit_posts' ) est une fonction de test de capacité de l'utilisateur qui vérifie si l'utilisateur actuel est connecté et peut modifier les messages. Chaque utilisateur enregistré sur un site , à l'exception de ceux ayant des rôles d'abonné, a la possibilité de modifier les publications. Il existe d'autres moyens robustes d'effectuer cette vérification, mais nous nous en tiendrons ici à cette méthode simple.
  • Utilisez la fonction par défaut wp_die() pour arrêter l'exécution de et afficher une page HTML avec un message d'erreur. Vous pouvez utiliser la syntaxe HTML dans le paramètre de message d'erreur pour le formater.

Après avoir enregistré le code dans mon plugin personnalisé, j'ai chargé mon installation locale en mode de navigation privée. le En maintenance la page est un succès !

Affichage d'une page en maintenance aux visiteurs de votre site
Affichage d'un message d'erreur aux visiteurs du site

Le site se charge avec succès si je suis connecté car il réussit le test de capacité de l'utilisateur. Vous pouvez maintenant continuer à travailler sur la réparation de votre site pendant qu'il affiche cette page aux visiteurs réguliers.

Exemple d'actions 2 : masquer les éléments de menu du tableau de bord aux utilisateurs non administrateurs

Si vous gérez un blog multi-auteurs ou gérez un site pour vos clients, vous devrez peut-être masquer certains menus d'administration du tableau de bord pour les utilisateurs non administrateurs. Vous pouvez le faire en vous connectant au admin_menu action.

// remove specific dashboard menus for non-admin users
add_action( 'admin_menu', 'hide_admin_menus' );
function hide_admin_menus() {
    if (current_user_can( 'create_users' )) return;
    if (wp_get_current_user()->display_name == "Salman") return; 
    remove_menu_page( 'plugins.php' ); 
    remove_menu_page( 'themes.php' ); 
    remove_menu_page( 'tools.php' ); 
    remove_menu_page( 'users.php' ); 
    remove_menu_page( 'edit.php?post_type=page' ); 
    remove_menu_page( 'options-general.php' );
}

Voici une procédure pas à pas de l'extrait de code ci-dessus :

  • admin_menu est une action qui est déclenchée avant le chargement du menu d'administration dans la zone du tableau de bord .
  • Accrochez-vous au admin_menu action en utilisant le add_action() fonction en utilisant le hide_admin_menus() fonction de rappel.
  • le hide_admin_menus() fonction de rappel définit la logique du code. Il est exécuté à chaque fois que le admin_menu feux d'action.
  • Dans la fonction de rappel, le current_user_can( 'create_users' ) La fonction vérifie si l'utilisateur connecté est un administrateur. Étant donné que seuls les administrateurs du site ont le create_user capacité, la fonction se termine par un return déclaration si l'utilisateur est un administrateur.
  • La fonction wp_get_current_user() récupère l'objet utilisateur actuel. Avec cette fonction, nous pouvons vérifier si l'utilisateur connecté a un display_name ensemble. Il s'agit d'une ligne facultative, au cas où vous souhaiteriez éviter que certains utilisateurs non-administrateurs ne soient verrouillés en raison de cette fonction de rappel.
  • La fonction remove_menu_page() supprime les menus d'administration de niveau supérieur. Dans l'exemple de code ci-dessus, je supprime les menus d'administration suivants : Plugins, Thèmes, Outils, Utilisateurs, Pages et Options.

Après avoir enregistré le fichier du plugin, voici un instantané du tableau de bord avec un administrateur connecté.

Le tableau de bord WordPress par défaut pour tous les utilisateurs
Le tableau de bord d'administration par défaut

Et voici une capture d'écran du tableau de bord avec un utilisateur non administrateur connecté.

Masquer les menus d'administration sensibles aux utilisateurs non administrateurs à l'aide d'actions
Masquer les éléments de menu d'administration sensibles aux utilisateurs non administrateurs

Cette solution masque uniquement les éléments de menu d'administration spécifiés dans le tableau de bord . Tous les utilisateurs peuvent toujours y accéder en saisissant les URL des menus dans leurs navigateurs.

Pour empêcher certains rôles d'utilisateur d'accéder à des menus spécifiques, vous devez modifier leurs capacités.

Accrocher un filtre

Les filtres permettent à votre code personnalisé de modifier les données utilisées par d'autres fonctions . Contrairement aux actions, les fonctions liées aux filtres doivent renvoyer une valeur.

La fonction de filtre add_filter()

Vous pouvez accrocher une fonction de rappel à un filtre en suivant ces étapes :

  1. Définir un Fonction de rappel qui s'exécutera lorsque déclenchera le filtre. Les fonctions de rappel des filtres doivent avoir au moins un argument spécifié, car tous les filtres transmettent au moins une valeur à leurs fonctions de rappel.
  2. Enregistrez la fonction de rappel dans un filtre avec le add_filter() une fonction. Le filtre se chargera d'appeler la fonction de rappel. Selon le Codex , la fonction add_filter() doit passer au moins deux paramètres :
    • Nom du filtre auquel se connecter.
    • Nom de la fonction de rappel qui s'exécutera lorsque le filtre se déclenchera.
  3. le add_filter() La fonction accepte également deux paramètres facultatifs supplémentaires pour définir le priority et le number of arguments. Ces paramètres fonctionnent de la même manière qu'avec le add_action() une fonction.

Voici un exemple de la façon dont vous pouvez utiliser le add_filter() fonction pour accrocher une fonction de rappel à un filtre.

// define the filter callback function with at least one argument passed
// the number of arguments that you can pass depends on how the filter is defined
function filter_callback_function( $arg1, $arg2 ) {
    // make your code do something with the arguments and return something
    return $something;
}

// now hook the callback function to the 'example_filter'
add_filter( 'example_filter', 'filter_callback_function', [priority], [no_of_args] );

// '10' is the default priority set for the callback function
// and '1' is the default number of arguments passed

Exemple d'accrochage d'un filtre

fournit un filtre appelé login_message pour filtrer le message affiché sur la page de connexion au-dessus du formulaire de connexion. La valeur renvoyée par ce filtre peut avoir un balisage HTML.

Accrochons-nous au login_message filtrer et modifier le message affiché sur l'écran de connexion.

// show a custom login message above the login form
function custom_login_message( $message ) {
    if ( empty( $message ) ) {
        return "

Welcome to Let's Develop by Salman Ravoof! Please log in to start learning.

";     } else {         return $message;     } } add_filter( 'login_message', 'custom_login_message' );

le if-else L'instruction dans la fonction de rappel vérifie si le message de connexion est déjà défini, principalement par un autre plugin ou thème. Dans de tels cas, la fonction de rappel renvoie la valeur d'origine sans modification. C'est une façon d'éviter les conflits avec d'autres plugins ou thèmes.

Vous pouvez voir le message s'afficher au-dessus du formulaire de connexion dans la page de connexion .

Affichage d'un message de connexion personnalisé au-dessus de la zone du formulaire de connexion
Affichage d'un message de connexion personnalisé au-dessus du formulaire de connexion

Vous pouvez styliser tous les éléments de la page de connexion en mettant en file d'attente des feuilles de style personnalisées. Cela vous permettra de personnaliser entièrement votre page de connexion par défaut.

Vous apprendrez à charger des feuilles de style personnalisées à l'aide des actions de la section « Personnaliser la page de connexion avec des crochets ».

Recherche de filtres pris en charge par

Partout où traite ou modifie des données, vous pouvez presque certainement trouver un filtre auquel vous connecter et le modifier. Considérez les filtres comme une interface entre la base de données et le navigateur.

Vous pouvez trouver une liste exhaustive de tous les filtres pris en charge par dans la page Plugin API/Filter Reference.

Page de référence des filtres de la section API du plugin
fournit une variété de filtres auxquels se connecter

Tous les filtres répertoriés ici sont divisés en plusieurs catégories et organisés de haut en bas dans l'ordre d'exécution de .

Si vous souhaitez trouver des filtres auxquels vous accrocher dans le code source de , effectuez une recherche sur le terme "appliquer_filtres” and you’ll get tons of results. The Code Reference is also a great place to search for everything that’s included in , including actions and filters.

How Core Uses Filters

Core itself uses a lot of its built-in filters to modify data used by its various functions.

Consider the the_content filter for example. It filters post content after it’s retrieved from the database and before it’s displayed on the browser.

Just like with actions, you can find most of Core’s filter functions related to the the_content hook in the wp-includes/default-filters.php file.

Here’s a list of all the core add_filter() functions that hook into the the_content filter:

add_filter( 'the_content', 'do_blocks', 9 );
add_filter( 'the_content', 'wptexturize' );
add_filter( 'the_content', 'convert_smilies', 20 );
add_filter( 'the_content', 'wpautop' );
add_filter( 'the_content', 'shortcode_unautop' );
add_filter( 'the_content', 'prepend_attachment' );
add_filter( 'the_content', 'wp_make_content_images_responsive' );
add_filter( 'the_content', 'do_shortcode', 11 ); // AFTER wpautop(). 

Note the priority specified for certain callback functions.

For example, the do_blocks() function parses any dynamic blocks in the post content and re-renders them to be compatible with ’ new block editor. It’s specified a higher priority than the default (10) to make sure that the content is block-ready before the other functions are run.

The convert_smilies() function is set to run at a lower priority as its task is to convert text smileys to image sprites. Having it run in the end after filtering all the post content makes sense.

Fun Fact: Shortcodes are a subset of filters. They take in input from the shortcode, process it, and then return the output back to it. Learn more about shortcodes in this ultimate Shortcodes guide.

Other Filter Functions

While add_filter() is the most used filter function, there are many other helpful filter functions. Let’s discuss them all in depth.

This function checks whether the specified filter is hooked by any function. It accepts two parameters. The first parameter is for entering the filter name. The second parameter is optional and is for entering the name of the callback function.

has_filter( 'filter_name', 'function_to_check' );

If you specify just the first parameter, it’ll return true if the filter_name is hooked by any function.

However, if you specify both the parameters, then it’ll return false if the callback function mentioned isn’t registered with the given filter. If it finds the callback function registered with the filter, then it’ll return the priority (an integer) set for that function on this filter.

One possible application of the has_filter() function is to check whether any filter has been hooked already, and based on that go ahead with code execution.

// check to see if 'the_content' filter has been hooked
if ( ! has_filter( 'the_content' ) {
    // hook the filter if and only if it hasn't been hooked before
    add_filter( 'the_content', 'modify_the_content' );
}

This filter function is like the do_action() action function. Any callback functions hooked to this filter will run wherever this function is in the code.

You can also use this function to create a new custom filter by specifying the filter name and the filter value as parameters.

apply_filters( 'filter_name', 'value_to_filter', [argument1], [argument2] );

Don’t forget to specify any additional arguments if you want to pass them on to your callback functions. Most filters only use one argument, so it’s easy to miss out on defining the additional ones.

This function is like the apply_filters() function, except all the arguments it accepts are bundled up as an array.

// an example array
$arguments_array = array( 'some_value', 'foo', false, 'another_value' );

apply_filters_ref_array( 'example_filter', $arguments_array );

This filter function can be handy when you have many arguments to pass or if all of them are already in an array. Ensure that the arguments inside the array are in the right order.

This filter function retrieves the name of the current filter or action being run. You don’t need to specify any parameters as it runs within the callback function.

Here’s an example of its usage:

function example_callback() {
    echo current_filter(); // 'the_title' will be echoed
    return
}
add_filter( 'the_title', 'example_callback' );

Despite its name, this function can retrieve the name of both actions and filters.

This filter function removes the callback function attached to the specified filter. It’s works exactly like the remove_action() function. You can use it to delete default functions registered with a specific filter, and if necessary replace them with your own functions.

remove_filter( 'filter_name', 'function_to_be_removed', [priority] );

To unhitch a callback function hooked to a filter, the function_to_be_removed et priority parameters must be identical to the arguments used when hooking the callback function.

If the filter has been added from within a class, which is usually the case when they’re added by plugins, then you need to access the class variable to remove the filter.

// access the class variable first, and then remove the filter through it
global $some_class;

remove_filter( 'the_content', array($some_class, 'class_filter_callback') );

Let’s check out a great example of remove_filter() in action.

The WooCommerce plugin uses the wc_lostpassword_url() call function hooked to its lostpassword_url filter to redirect “Lost Your Password?” attempts by users.

It takes any user clicking on that link to a custom frontend page with the URL /my-account/lost-password. Without this filter, it’d take them to the standard login URL at /wp-login.php.

Say you want to reset this functionality and send your users to the default password retrieval page or to a separate page altogether. You can remove this callback function like this:

remove_filter( 'lostpassword_url', 'wc_lostpassword_url', 10 ); 

This filter function removes all the callback functions registered to a filter.

remove_all_filters( 'filter_name', [priority] );

It’s similar to the remove_all_actions() function.

The popular Advanced Excerpts plugin uses this function to remove all default functions hooked to the_excerpt et get_the_excerpt filters. After doing that, it then hooks its own callback function to the filter.

// Ensure our filter is hooked, regardless of the page type 
if ( ! has_filter( 'get_the_excerpt', array( $advanced_excerpt, 'filter_excerpt' ) ) ) {
    remove_all_filters( 'get_the_excerpt' ); 
    remove_all_filters( 'the_excerpt' ); 
    add_filter( 'get_the_excerpt', array( $advanced_excerpt, 'filter_excerpt' ) );
}

This filter function checks whether the filter specified is being executed at the moment.

if ( doing_filter( 'save_post' ) ) {
    // run your code here
}

It returns a boolean value (true ou false).

You should note the difference between this function and the current_filter() function, which returns the name of the filter or action being run (a string).

Filters Example 1: Adding a Profanity Filter for Comments

Managing all the comments on your site can be a cumbersome process. The comment_text filter lets you set up rules to modify the comments before they’re printed on the display.

Comments with dummy profane words which are still uncensored
Unfiltered comments with dummy profanities marked

You can direct to remove any expletives automatically before they’re displayed to your site visitors. Let’s get to it.

// hook into the 'comment_text' filter with the callback function
add_filter( 'comment_text', 'the_profanity_filter' );

// define a callback function to filter profanities in comments 
function the_profanity_filter( $comment_text ) {
    // define an array of profane words and count how many are there 
    $profaneWords = array('fudge', 'darn', 'pickles', 'blows', 'dangit');
    $profaneWordsCount = sizeof($profaneWords);
    
    // loop through the profanities in $comment_text and replace them with '*'
    for($i=0; $i 

Here’s a line-by-line breakdown of the code:

  • comment_text is a filter hook that lets you modify the text of a comment before the browser displays it. You can register your callback function with it to filter its output.
  • le add_filter() function lets you hook into the comment_text filter and attach a callback function to it.
  • the_profanity_filter() is the name of the callback function. It accepts only one parameter, which is a string containing the comment text. Define this custom function with the appropriate code logic.
  • Store all the profane words in a PHP array called profaneWords. You can add as many words as you want to this array. I’m storing the size of this array in the profaneWordsCount variable with the help of sizeof() PHP function.
  • Loop through all the profane words and use PHP’s default str_ireplace() function to replace any of the matching profanities with * symbols. Since this is a case-insensitive string replacement function, you don’t have to worry about capitalization. Check out different ways to perform a search and replace.
  • Use return to output the filtered comment text.

Save the changes to your custom plugin file and reload any post with comments. All the words you’ve included in the profaneWords array should now be replaced with ‘*’ symbols.

Comments with dummy profane words which are all now censored
Censoring profanity in comments with ‘*’ symbols

The original comments will still be available as is in the database. This filter only modifies the comment text before it’s outputted to the frontend.

The original comment stays unaltered in the site backend
The original comment on the site backend

Once you’re hooked into the right filter, you can do a lot of cool stuff with it.

For example, you can also use the comment_text filter to remove any URLs from all the comments (make sure to read this in-depth guide on how to stop spam comments in ).

Or you can hook into the pre_comment_approved filter and mark comments as approved, spam, or thrash based on predefined criteria.

Filters Example 2: Insert Content After a Post

You’ve already seen how uses the_content filter to modify post or page content. Let’s use the same filter to add something at the end of each post.

Let me insert myself here

I'll appear after the post. You can insert anything here. Even HTML. Headers, links, images, scripts, I'll take them all and append it to the end of the post content. You can also give me a class, so you can style me easily with CSS style sheets.

" ; } return $content; }

Understanding the code logic in the above example:

  • the_content filter hook helps you grab the content of the current post and customize it.
  • Use the add_filter() function to hook into the_content filter with the insert_content_below() callback function.
  • Define the callback function by passing the current post’s content as a parameter ($content).
  • Inside the callback function, check that you’re only filtering the content in the main query, which in this case is the post content. If you don’t verify this, sometimes the code will unintentionally filter content from other places such as sidebars and footers.
  • is_main_query() and in_the_loop() conditionals determine whether the query is a main query and happening within the main Loop.
  • is_single() conditional checks whether the query is for a single post.
  • Use PHP’s string concatenation operator ($content . “your additions”) to add extra stuff to the page content.
  • return the filtered comment if all the above conditionals check out. If it doesn’t, then just return the content with no changes.

Save your plugin file, load up any post on your site, and scroll to the end.

Additional content inserted after the post content
Inserting something at the end of the post content

You can use the same logic to add anything to the beginning of all your posts by reversing the position of string concatenation parameters (“your additions” . $content).

Customize the Login Page with Hooks

Let’s use both actions and filters to customize the default login page. I’ll create a new plugin called Sal Custom Login Page to do this. You can find the full source code of this plugin at the end of this section.

The final customized WordPress Login Screen
The final customized login screen

Let’s get started by adding the standard plugin header fields and registering it with .

First, hook into the login_enque_scripts action to enqueue your custom style sheet. Any scripts or styles you enqueue here are included in the header section of your login page.

If you want to load custom scripts and style sheets on your site’s frontend (rather than on the admin backend or login area), then you need to hook into the wp_enqueue_scripts action. You can read more about it in the Codex and Kinsta’s article on how to use wp_enqueue_scripts.

Inside the salhooks_login_stylesheet() callback function, use the wp_enqueue_style() function to load the custom style sheet (sal-custom-login-page-styles.css) placed in the same plugin’s directory. ’ built-in plugin_dir_url( __FILE__ ) function makes it easy to get the URL path (with a trailing slash) of the current plugin’s directory.

I won’t explain the CSS styles applied here, but you can find them all in the source code linked at the end of this section.

// Custom login ERROR message to keep the site more secure
add_filter( 'login_errors', 'salhooks_remove_login_errors', 10 );
function salhooks_remove_login_errors() {
    return 'Incorrect credentials. Please try again!';
}

Next, hook into the login_errors filter to change the error message shown when someone enters incorrect credentials. Filtering the error message will block attackers from guessing your username easily.

// Remove the login form box shake animation for incorrect credentials
add_action( 'login_head', 'remove_login_error_shake' );
function remove_login_error_shake() {
    remove_action( 'login_head', 'wp_shake_js', 12 );
}

Every time someone enters incorrect login credentials, the login form box shakes aggressively. This is an optional step, but I’ve included it to show that you can also remove certain features from the login page.

You’ll learn more about remove_action() et remove_filter() functions in the final section of this article.

// Change the logo and header link above the login form
add_filter( 'login_headerurl', 'salhooks_login_headerurl');
function salhooks_login_headerurl( $url ) {
    $url = 'https://salmanravoof.com';
    return $url;
}

add_filter( 'login_headertext', 'salhooks_login_headertext');
function salhooks_login_headertext( $text ) {
    $text = 'Salman Ravoof';
    return $text;
}

The final step is to change the login header’s URL and text. You can hook into the login_headerurl and login_headertext filters to modify them both.

If you want to build upon this plugin and experiment further, you can download the plugin’s source code and get started.

Hooks List and Resources

It’s hard to memorize all the various hooks has. There are thousands of built-in actions and filters to hook into. Hence, finding an appropriate hook may sometimes feel like a scavenger hunt.

Thankfully, there are various resources you can use to identify the perfect hook for your needs.

The first place to get familiar with hooks is the Codex, particularly its Hooks section in the Plugin Handbook. Here you can find essential information about hooks and links to complete documentation on all actions and filters.

WordPress Hooks section in the Plugin Handbook
Start learning Hooks with the Plugin Handbook

Bookmark these helpful links from the Plugin Handbook to speed up your search:

Both the action reference and the filter reference pages will give you a list of all the hooks that typically run during a specific request.

For example, you can find all the hooks fired when you access an admin page, when you’re dealing with post page attachments, or with categories.

The Codex also includes a handy search tool to find all its functions, hooks, methods, and classes. This page also lists new and updated components in the most recent version of . Head here first if you want to find what’s happening inside .

WordPress Code Reference search tool in WordPress Codex
Search for anything inside here

This index of hooks sorts all the hooks by type, the version they debuted, and if they’re deprecated.

Adam R Brown's WordPress Hooks Index
Adam R Brown’s Hooks Index

Sorting the hooks in order of their appearance will show you that the oldest hooks are still the most used ones. If you’re new to development, getting familiar with these popular actions and filters is the fastest way to catch up.

While this index hasn’t been updated since 5.1, it’s still helpful to skim through all the major hooks.

Still finding it hard to find the hook you want? An online search with the right keyword is always a good way to start. If everything else fails, you can always dig into the code.

Finding Hooks Registered on a Page

As we’ve seen, has tons of hooks available, but not every hook fires on every page. If you can find which actions and filters you can hook into on a particular page, then you’ve won half the battle.

While you can use advanced PHP debugging tools like xdebug and PHPCS to help with this, there are simpler development tools like Debug Bar and Query Monitor which you can run inside .

Debug Bar with Actions and Filters Add-On

Debug Bar is an official plugin that adds a Debug menu to your admin bar. It shows PHP warnings and notices, cache requests, MySQL queries, and other helpful debugging information.

The WordPress Debug Bar WordPress plugin
The Debug Bar plugin

After installing the plugin, you need to add the code snippet below to your site’s wp-config.php file to enable its debugging features.

define( 'WP_DEBUG', true ); // tracks PHP Warnings and Notices
define( 'SAVEQUERIES', true ); // tracks and displays MySQL queries

You should now see the Debug menu option show up in your admin bar. Clicking on it will take you to its dashboard where you can see various queries and caches attached to the page you accessed it from.

Showing the Debug menu in the admin bar
The ‘Debug’ menu in the admin bar

Next, you need to install the Debug Bar Actions and Filters Addon plugin. It’s a handy extension that’ll add two more tabs to your Debug Bar dashboard to display actions and filters triggered on the current request.

Action Hooks panel inside the Debug Bar dashboard
Actions listed in their loading order for the current page

It’ll also list all the functions hooked to them with their priority.

Debug Bar plugin with the Actions and Filters Addon installed
Filters listed with their priority and registered callback functions

You can click on the Debug menu from any page on your site to know all the actions and filters that you can hook into on that page.

Query Monitor

Query Monitor is a powerful developer tools panel for . You can use it to dig into the hooks available on a page and their load order.

Query Monitor WordPress plugin
Query Monitor plugin

Unlike with Debug Bar, you don’t have to install any addons to see the actions and filters triggered on a certain page.

Access Query Monitor from the admin bar
You can access Query Monitor from the admin bar

Query Monitor also gives you more information about where exactly a hook is being fired from.

The Hooks & Actions panel in Query Monitor

In the component column, you can see that most of the hooks are registered from the Core. But some hooks are registered from a theme or plugin. A few hooks may be registered from more than one component.

You can use the hook and component dropdown menus to view only the hooks you need.

Note: Query Monitor uses “Hooks” as a catchall term for both actions and filters, but it calls the registered callback functions as “Actions.” This is technically a wrong definition and can confuse you, so do keep that in mind.

You can do more than just check all the queries and requests with Query Monitor. It also includes advanced features such as listing styles, scripts, languages, Ajax calls, user capability checks, and REST API Calls.

The “all” Hook

has a special hook named ‘all’ that you can hook in to run a callback function for every single hook, regardless of whether it’s registered with them all. It’s useful to debug page crashes or if you want to know when a particular event is happening.

For instance, you can use the all hook like in the example below to echo all the actions being run.

// echo all the actions being run
function debug_helper_function(){
    echo '

' . current_action() . '

'; } add_action( 'all', 'debug_helper_function' );

le debug_helper_function() defined above will run when any action fires. Knowing what the last run action was will give you a better idea of where you need to look into.

Where Are Hooks Stored?

uses the WP_Hook class to implement how hooks work. This core class is used to handle all the inbuilt actions and filters. You can find almost all the code related to this class in the wp-includes/class-wp-hook.php file.

Technically, the WP_Hook class is an array of objects comprising properties such as callbacks, iterations, current_priority, nesting_level, and doing_action. It also defines a lot of useful hook functions which can be called using the WP_Hook methods.

Most developers don’t have to worry much about where stores hooks as long as they stick to the Plugin API guidelines.

There are two types of hooks: actions and filters, and this guide breaks down exactly when (and how!) to use each one 💥Click to Tweet

How to Create Your Custom Hooks

You’ve seen the various hooks provides through its Plugin API. You’ve also looked at how you can use the default hooks to inject your own code into runtime.

If you’re a plugin or theme developer, it’s good practice to provide other developers with a way to interact with your code the same way. Custom hooks let you do exactly that. They allow other developers to extend and modify the functionality of your plugins and themes.

Creating your own actions and filters is fairly simple. You use the same functions Core uses to create hooks. Let’s look at a few examples.

How to Create Custom Actions in

Use the do_action() function to create a custom action hook. Here’s how you do it:

// the position where you insert your action is where it'll run when called
do_action( ' my_unique_custom_action' );
// continue with the rest of your code

Now, other developers can hook into your plugin or theme without modifying the source code. All they have to do is register their callback functions to your plugin’s custom action using the add_action() function.

add_action( 'my_unique_custom_action', 'some_callback_function' );

// define the callback function you mentioned in the above action function
some_callback_function() {
     // this code will run wherever your custom action hook is 
}

Assurez-vous de document your custom hooks thoroughly, explaining what they do in detail. After all, the main use of creating custom hooks is to help other developers interact with your code.

How to Create a Custom Filter in

Use the apply_filters() function to create a custom filter hook. Here’s how you can do it:

$value_to_filter = "I'm a string, but this can be any PHP data type";

// filters modify a value and are typically tied to a predefined variable
apply_filters( 'my_custom_filter', $value_to_filter );

Your custom filter’s parameters should include a unique identifier and a value to filter. Other developers can hook into your custom filter with the add_filter() function and modify the passed value.

add_filter( 'my_custom_filter', 'some_callback_function' );

// define the callback function you mentioned in the above filter function
function some_callback_function( $value_to_filter ) {
    // modify the passed value (or not) 
    return $value_to_filter; // returning a value is a must for filters
}

When you’re defining your custom filter, ensure that it’s not positioned before the value it’s supposed to filter is defined. If you don’t position the filter correctly, the filtered value will get overwritten by the default value afterward.

Custom Hooks Naming Convention

It’s important to choose a unique name for all your custom hooks. Since any plugin or theme can have its own custom hooks, having identical hook names can cause code collisions with unexpected results.

For example, if you name your action send_email, it’s highly likely that other plugin developers may also choose the same term as it isn’t unique enough. If any website installs both yours and the other developer’s plugins, it can cause errors that’ll be hard to trace.

You can prefix all your custom hooks with a common identifier to keep them both simple and unique. So, instead of send_email, you can name it plugin_name_send_email (plugin_name_ is the unique prefix here).

Custom Hooks Demo with an Extensible Plugin

Let’s create an extensible plugin (or a pluggable plugin) that will allow other developers to interact with it using its custom hooks.

I’ll name this plugin Custom Hooks Demo. Its main function is to output a quotation box wherever you insert a shortcode. It’ll include custom actions and filters at the right locations to make it possible for other developers to modify or extend its functionality.

You can refer to my shortcodes guide to learn more about how shortcodes work.

Let’s get started with the extensible plugin.

"; echo $quote_content; echo "

"; echo "― " . $quote_author . ""; echo "
"; // set an action hook to run after you output everything do_action( 'the_ending_custom_action' ); return ob_get_clean(); // get buffer contents, delete the buffer, and then stop buffering }
  • le add_shortcode() function is used to create the custom shortcode. And then you define the shortcode’s callback function with all of this plugin’s functionality.
  • ob_start() is a PHP function that enables output buffering. It’s a super handy feature that instructs PHP to hold onto any output in the server’s buffer memory rather than outputting it right away. You can use it to build complex, readable HTML code in PHP.
  • do_action( 'the_topmost_custom_action' ) defines your first custom action. To make it useful, you need to define it before the plugin outputs anything. Other developers can hook into this custom action to run their code before this custom shortcode prints out anything.
  • Create the variables you want to filter. In this plugin, those variables are $quote_content et $quote_author. They’re both strings in this example, but you can set them to be any PHP data-type (e.g. integer, boolean, array).
  • Use the apply_filters() function to create your custom filters. Since all filters return a value, you can assign the previously defined variables to this filter’s returned value. Other developers can now hook into this filter to modify the default values of the predefined variables.
  • Use echo statements to build your shortcode’s output line-by-line. Since we’ve enabled output buffering, no output will reach the browser right away.
  • do_action( 'the_ending_custom_action' ) defines your last custom action. You need to define it at the very end, but before returning all the buffer contents.
  • ob_get_clean() is an default 3-in-1 PHP function. It’ll retrieve the buffer contents, eliminate all the buffer data, and then stop the output buffering. It’ll return the collected buffer contents as a single concatenated string.

Once saved and activated, adding the [custom_hooks_demo] shortcode to your post content will output a quotation box with the default values.

The original quotation box as outputted by the shortcode defined in the Custom Hooks Demo plugin
The original quotation box using the Custom Hooks Demo plugin

Now, let’s create another plugin called Custom Hooks Demo Extension. It’ll hook into all the custom hooks created by the previous plugin and do or modify something.

WordPress: Comment utiliser les actions, les filtres et les hooks personnalisés
'; } /** * add a button below the shortcut output by hooking into the 'the_ending_custom_action' */ add_action( 'the_ending_custom_action', 'add_button_callback' ); function add_button_callback() { echo '
'; }

As you can see, this extension plugin contains nothing but action and filter functions hooking into the original plugin at the right places to make modifications.

It uses the add_action() et add_filter() functions to register its callback functions with the custom actions and filters created by the original plugin (e.g. the_topmost_custom_action, custom_quote_author).

The modified quotation box after the extension plugin changes the original output
The extension plugin modifies the original quotation box

Custom action hooks allow you to interject your code at the right intervals in the original plugin and run your own scripts. Here, we’re adding an image at the top and a button at the bottom.

Likewise, custom filter hooks let you modify the values of the quote content and its author name. The ultimate outcome is a plugin that’s fully extensible by anyone without modifying its source code.

Working With Custom Hooks from Third-Party Developers

Custom hooks enable individual plugins and themes to have a rich ecosystem of extensible plugins. Consider the WooCommerce plugin. It adds ecommerce functionality to , but it also includes tons of hooks within its code.

WooCommerce Hook Reference
WooCommerce Action and Filter Hook Reference

WooCommerce has hundreds of extensions and plugins that use its hooks to build on its core functionality and make it even better.

You can use these extensions to integrate WooCommerce with Stripe, MailChimp, Salesforce, Zapier, and much more.

WooCommece's page on its most popular extensions
Extensions extend WooCommerce’s functionality

A good practice is to check out the documentation section of popular plugins to see how they implement custom hooks. A few of my top suggestions are Easy Digital Downloads, BuddyPress, Quiz and Survey Master, and Gravity Forms.

When to Use Custom Hooks?

Depending on the theme or plugin you’re creating, and who it’s intended for, you may wonder whether you need to add any custom hooks.

A good rule of thumb when deciding on whether or not to add custom hooks is to check if they offer any extensibility benefits to other developers. If not, then it’s better to hold off until other developers ask you to add them.

You need to be highly certain about adding custom hooks to your plugin or theme. Once it’s released, and if other developers have already used it, you can’t ever change it without breaking backward compatibility.

Removing Callback Functions from Hooks

You’ve already seen examples of how to remove callback functions registered to certain hooks. These callbacks could be registered by plugins, themes, or even Core itself. Let’s look at removing hooked callback functions with more examples.

To remove a callback function from a hook, depending on whether it’s registered to an action or a filter, you need to use the remove_action() ou remove_filter() functions.

One caveat is that you need to call these functions with the identical parameters used to register the callback function. Basically, copy-paste the parameters from their add_action() ou add_filter() functions.

Also, you can remove callback functions only after they’re registered. If you try to remove them before they’re registered, the removal process will fail. You need to get the execution order of the hooks right.

Let’s say you want to remove a callback function registered by a theme that adds bloat to your site (you want a fast site, don’t you?).

function wp_bloated_callback_function() {    
// some code that adds a lot of bloat to the site
}
add_action( 'template_redirect', 'wp_bloated_callback_function', 5 );

For example, the above callback function could load many unnecessary scripts and style sheets. Removing it will give your site a huge performance boost.

However, you need to ensure that the remove_action() function runs only after the template_redirect action. One way to do this is to hook into the after_setup_theme action as it’s triggered after the template_redirect action.

function wp_remove_bloat() {
    // ensure all parameters are identical to the original add_action() function
    remove_action( 'template_redirect', 'wp_bloated_callback_function', 5 );
}

// ensure that remove_action() is called only after add_action()
add_action( 'after_setup_theme', 'wp_remove_bloat' );

le wp_bloated_callback_function() will now unhitch itself from the template_redirect action.

Special Cases for Removing Callback Functions

There’s more to removing callback functions than just disabling them altogether. Sometimes you may need to remove them temporarily, run your code, and then add them again.

For example, the save_post action fires every time the wp_insert_post() et wp_publish_post() functions are called. You can find them both defined in the wp-includes/post.php file.

So, if you have a callback function hooked to the save_post action, and if you call wp_insert_post() ou wp_publish_post() functions within your callback function, the save_post action will fire multiple times.

function some_callback_function( $post_id, $post ) {
    // do something here
    wp_insert_post( [some_array] ); // this function also calls the 'save_post' action
    // maybe do something more
}
add_action( 'save_post', 'some_callback_function', 10, 2 );

A function calling the action which also calls it can create unexpected results. One way to get around this issue is to use the remove_action() function inside your callback function before you call wp_insert_post().

function some_callback_function( $post_id, $post ) {
    // do something here
    
    // remove the callback function from the ‘save_post’ action
    remove_action( 'save_post', 'some_callback_function', 10, 2 );
    
    // now run the wp_insert_post() function
    wp_insert_post( [some_array] );
    
    // add the callback function back to the ‘save_post’ action
    add_action( 'save_post', 'some_callback_function', 10, 2 );
    
    // maybe do something more
}
add_action( 'save_post', 'some_callback_function', 10, 2 );

That’s another practical use of remove_action() ou remove_filter() functions. Digging deeper into the Core will help you understand how you can avoid these situations better.

Bonus Hooks Tutorials

Hooks are one of the most important tools to have in a developer’s arsenal. 💪 Learn the difference between actions and filters (and how to use them) in this guide!Click to Tweet

Résumé

There are multiple advantages of using hooks if you’re a developer.

Not only do hooks allow you to modify or extend the core functionality of , but you can also use them to modify plugins, themes, and let other developers interact with your plugins or themes.

It’s time to get hooked on hooks!


Save time, costs and maximize site performance with:

  • Instant help from hosting experts, 24/7.
  • Cloudflare Enterprise integration.
  • Global audience reach with 29 data centers worldwide.
  • Optimization with our built-in Application Performance Monitoring.

All of that and much more, in one plan with no long-term contracts, assisted migrations, and a 30-day-money-back-guarantee. Check out our plans or talk to sales to find the plan that’s right for you.



All the CMS Templates You Could Ask For.

WordPress: Comment utiliser les actions, les filtres et les hooks personnalisés

2M+ items from the worlds largest marketplace for CMS TemplatesEnvato Market.



WordPress: Comment utiliser les actions, les filtres et les hooks personnalisés

#Comment #utiliser #les #actions #les #filtres #les #hooks #personnalisés