Un guide des crochets WordPress

Publié: 2021-07-19

Le système de crochets peut sembler intimidant pour les non-initiés, mais c'est l'une des meilleures choses à propos de WordPress. Ce guide vous aidera à comprendre les principes fondamentaux des crochets et comment les utiliser, en fournissant des exemples d'utilisation et des conseils supplémentaires.

Pourquoi utiliser des crochets ?

Au cas où vous ne le sauriez pas déjà, c'est une très mauvaise idée de modifier les fichiers principaux dans WordPress (WP). Mis à part les risques de sécurité, vos modifications seront écrasées à chaque mise à jour de WP ! Il en va de même pour les plugins et les thèmes.

Bien sûr, vous pouvez suivre chaque mise à jour et ré-implémenter vos modifications. Vous pouvez également percer une ruche pour obtenir le miel. Cela peut sembler pratique, mais vous risquez de vous faire piquer tôt ou tard.

En termes simples, vous devez utiliser des hooks car ils compensent les risques de modification des fonctionnalités de base .

En ce sens, l'importance des crochets ne peut pas être surestimée . Ils sont la clé de l'extensibilité de WP et la pierre angulaire de ses écosystèmes de plugins et de thèmes. Vous vous éviterez bien des maux de tête en apprenant les bases et en les utilisant bien.

Que sont-ils?

Vous pouvez considérer les hooks comme des événements qui se produisent tout au long de la séquence de chargement WP. Lorsque WP rencontre un hook, il déclenche toutes les fonctions attachées à ce hook avant de continuer.

Vous pouvez ainsi tirer parti des hooks pour ajouter des fonctionnalités ou modifier des variables dans WP . Vous pouvez utiliser les crochets existants et en ajouter de nouveaux. Vous pouvez retirer les crochets dont vous n'avez pas besoin. Vous pouvez frapper le même crochet plus d'une fois, en donnant la priorité à chaque fonction comme bon vous semble. C'est un système très flexible, limité uniquement par les crochets disponibles et les données qu'ils exposent.

Comment travaillent-ils?

Vous ajoutez une ou plusieurs fonctions à un hook. D'autres fonctions peuvent également être ajoutées par votre thème, vos plugins ou WP lui-même. Lorsque WP se charge, il rencontre le crochet. Il vérifie une liste de toutes les fonctions associées au crochet. WP exécute toutes ces fonctions par ordre de priorité . Une fois cela fait, il reprend le chargement de tout après le crochet.

À quoi ressemblent-ils?

L'ajout d'une fonction à un hook ressemble à ceci :

add_action( $hook_name, $function_name, $priority, $arguments );

$hook_name est le nom du crochet que vous souhaitez cibler

$function_name est le nom de la fonction que vous souhaitez ajouter à ce hook

$ priorité est un nombre entier indiquant le 'priorité s in $ hook_name' $ function_name de file d'attente s. Plus le nombre est faible, plus la priorité est élevée. À partir de 1, ce nombre peut être aussi élevé que vous le souhaitez (dans les limites du système), mais il est peu probable qu'il dépasse 40. La valeur par défaut est 10.

$arguments est un entier indiquant le nombre d'arguments que vous utilisez dans la fonction. Cela doit correspondre au nombre d'arguments passés à la fonction. La valeur par défaut est 1.

Supprimer une fonction d'un hook est presque la même:

remove_action( $hook_name, $function_name, $priority );

Le $function_name et $priority doivent correspondre à leurs valeurs d'origine de la fonction add_action correspondante, sinon ils ne seront pas supprimés !

Types de crochet

Il existe deux principaux types de crochets : les crochets à action et les crochets à filtre . Ils sont similaires à bien des égards – add_action() et son homologue add_filter() sont tous deux appelés de la même manière. La différence réside dans la fonction par laquelle vous passez :



// Exécuter du code

add_action( 'où_faire_la_chose', 'faire_la_chose' );

fonction do_the_thing() {

// Effectue une action requise pour faire la chose

}
		




// Changer une variable

add_filter( 'la_chose', 'change_la_chose' );

function changer_la_chose( $chose ) {

// Filtrez $chose et changez ce dont vous avez besoin, puis…


renvoie $chose ;

}

Notez que dans le second exemple, le premier argument passé à la fonctio n est la valeur étant modifiée. Tout argument supplémentaire serait uniquement à des fins utilitaires et ne serait pas renvoyé via le hook.

Vous avez peut-être remarqué que j'ai omis $priority et $arguments . C'est parce que les valeurs par défaut sont correctes. Si cela peut aider, ce qui précède est essentiellement le même que :



// Exécuter du code

add_action( 'où_faire_la_chose', 'faire_la_chose', 10, 1 );

// Changer une variable

add_filter( 'la_chose', 'change_la_chose', 10, 1 );

Ce sont bien sûr des exemples artificiels, mais ils illustrent la principale différence entre les deux : les filtres servent à changer les variables, les actions servent à ajouter du code.

Exemples moins artificiels

Disons que vous souhaitez que WP envoie une notification par e-mail lorsqu'un nouvel utilisateur s'inscrit sur votre site. En vous référant au codex WP, vous trouvez le crochet d'action user_register . Cela vous fournit une variable $user_id , que vous pouvez utiliser pour obtenir les détails de l'utilisateur. wp_mail() gère le reste :



add_action( 'user_register', 'notify_on_user_registration' );

function notify_on_user_registration( $user_id ) {


// Récupère l'utilisateur

$user = get_user_by( 'id', $user_id );


// Préparer le sujet et le corps de l'e-mail

$subject = « Inscription d'un nouvel utilisateur » ;

$message = "Un nouvel utilisateur {$user->first_name} {$user->last_name} s'est enregistré.";


// Envoyer l'email

wp_mail( '[email protected]', $sujet, $message );

}

Et si vous souhaitez rediriger les utilisateurs vers votre page d'accueil lors de la connexion ? Vous y parvenez facilement avec le hook login_redirect , qui fournit l'URL vers laquelle les utilisateurs sont redirigés par défaut :



add_filter( 'login_redirect', 'redirect_user_on_login' );

fonction redirect_user_on_login( $redirect_to ) {

return home_url();

}

Peu de temps après avoir ajouté cela, vous réalisez rapidement qu'en tant qu'administrateur, vous souhaitez être redirigé directement vers le tableau de bord WP au lieu de la page d'accueil. Pas de problème - il vous suffit de modifier le crochet pour qu'il fonctionne uniquement pour les administrateurs :



add_filter( 'login_redirect', 'redirect_user_on_login', 10, 3 );

function redirect_user_on_login( $redirect_to, $request, $user ) {

// Changer l'URL de connexion sauf si l'utilisateur est un administrateur

if ( isset( $user->roles ) && is_array( $user->roles ) ) {

if ( in_array( 'administrateur', $user->rôles ) ) {

renvoie $redirect_to; // Rediriger les administrateurs vers la valeur par défaut (zone d'administration)

}

}
		




renvoie $redirect_to;

}

Notez que $priority et $arguments sont entrés en jeu !

Puisque vous avez besoin d'accéder au troisième argument du hook pour vérifier le niveau de l'utilisateur, vous devez afficher 3 arguments ; vous passez une valeur de 3.

La valeur $priority de 10 est la même que par défaut, bien sûr, mais elle est spécifiée afin d'atteindre la valeur $arguments dont vous aviez besoin ci-dessus.

Créer vos propres crochets

Le pouvoir de créer des crochets personnalisés est entre vos mains ! Les fonctions fournies par WP ressemblent à ceci :

do_action( $hook_name, $arg_1, $arg_2 … $arg_n );

apply_filters( $hook_name, $arg_1, $arg_2 … $arg_n );

Encore une fois, ils sont en quelque sorte similaires. Les deux fonctions acceptent un nom - c'est ici que vous nommez le crochet. Tous les arguments suivants sont les mêmes arguments mis à la disposition des fonctions que vous ajoutez à ce hook. apply_filters() doit avoir au moins un argument supplémentaire (l'argument étant filtré), mais tous les autres sont facultatifs.

Par exemple, si vous souhaitez injecter un script d'analyse juste avant votre balise body d'ouverture, mais que vous ne voulez pas transformer header.php en désordre :



<?php do_action( 'before_body_tag' ); ?;>

</head>

<corps>

Ensuite, vous pouvez ajouter autant de scripts que vous le souhaitez :



add_action( 'before_body_tag', 'add_analytics_custom' );

fonction add_analytics_custom() {

// Les balises <script> et le code d'analyse vont ici

}

apply_filters() fonctionne légèrement différemment. Comme indiqué ci-dessus, les filtres sont utilisés pour modifier les valeurs. Puisque les filtres renvoient une valeur, vous affectez votre appel apply_filters() à une variable :



<?php $text = apply_filters( 'call_to_action_text', 'A propos de nous' ); ?>

<a href="<?php echo get_permalink( 'à propos' ); ?>"class="bouton cta">

<?php echo $text; ?>

</a>


// Alternativement, vous pouvez faire écho directement au résultat de apply_filters()

<a href="<?php echo get_permalink( 'à propos' ); ?>"class="bouton cta">

<?php echo apply_filters( 'call_to_action_text', 'A propos de nous' ); ?>

</a>

Ensuite, vous pouvez modifier la variable filtrée si nécessaire :



add_filter( 'call_to_action_text', 'change_call_to_action_text' );

fonction change_call_to_action_text( $text ) {

if ( is_front_page() ) {

$text = 'En savoir plus';

}


renvoie $texte ;

}

Les inconvénients

Aucun système n'est parfait et les crochets ne font pas exception. En ce qui concerne les crochets de base, vous devez généralement vous contenter de ce qu'on vous donne. Très occasionnellement, vous rencontrerez des situations où un crochet n'est pas à l'endroit le plus pratique pour vous. Il n'y a pas grand-chose à faire lorsque cela se produit, alors voyez-le comme une opportunité de trouver une solution créative !

De plus, étant donné que les crochets peuvent exister n'importe où dans la structure de répertoires WP, il est parfois difficile de trouver où se déroule une certaine logique. Cela peut être compensé en séparant vos hooks de fonction dans leurs propres fichiers.

Conseils supplémentaires

  • Lors de la création de fonctions pour les hooks, assurez-vous que le nom est unique, sinon un conflit se produira. Il en va de même pour vos noms de crochets et de filtres personnalisés !
  • Utilisez des crochets pour que vos modèles ne soient pas encombrés. Quelques crochets génériques do_action() insérés dans vos modèles peuvent aider à éloigner la logique du balisage (presque toujours une bonne idée).
  • Lorsque vous installez un nouveau plugin, vérifiez les crochets qu'il fournit et réfléchissez à la façon dont vous pourriez les utiliser. Ceci est particulièrement utile pour les moments inévitables où un plugin ne fait pas tout à fait ce que vous voulez.
  • Lors de l'ajout d'une action ou d'un filtre, vous pouvez remplacer le nom de la fonction par la fonction elle-même. Cela peut aider à garder les actions et les filtres autonomes. Les fonctions ajoutées de cette façon ne peuvent pas être supprimées à l'aide de remove_action() ou remove_filter() , alors soyez prudent !


add_action( 'où_faire_la_chose', function() {

echo 'La chose est faite.';

}, 10, 1 );
  • Découvrez les autres fonctions liées aux hooks disponibles, telles que did_action() ou has_action() . On ne sait jamais quand le simple fait d'en être conscient sera utile.

Résumé

L'utilisation de crochets est une question d'habitude. Essayez de vous poser deux questions simples à chaque fois que vous travaillez sur votre projet WP :

  1. « Y a-t-il un crochet qui me facilitera la tâche ? »
  2. « Puis-je ajouter un crochet qui me facilitera la tâche à l'avenir ? »

Une fois que vous abordez le développement de WP avec cette attitude, de nombreuses portes s'ouvrent.

Les exemples de ce guide ne sont que la pointe de l'iceberg. Il y a des centaines de crochets dans le noyau WP seul, sans parler de l'énorme bibliothèque de plugins et de thèmes. Jetez un œil à la référence d'action WP et à la référence de filtre pour la liste complète des principaux hooks WP.

Si vous avez besoin d'aide pour votre développement Web, n'hésitez pas à nous contacter.