Pour un débutant, comprendre les filtres WordPress peut paraître un peu compliqué à appréhender. Nous allons tenter de vous expliquer ces mécanismes très simplement.
Comprendre les filtres WordPress, pour quoi faire ?
Pour faire simple, les filtres permettent d’ajouter, ajuster ou modifier des données à différents moments de leur cycle de vie. Vite un exemple ! Supposons que vous souhaitiez ajouter l’expression ” – sur mon petit blog” à tous les titres de vos articles (sans jamais ajouter vraiment l’expression à un titre lui-même, de sorte que vous puissiez modifier cette expression à volonté en 3 secondes). Les filtres entrent en action ! Voici donc quelques explications pour comprendre les filtres WordPress :
Différence entre add_filter() et apply_filters()
add_filter(): vous l’utilisez pour dire “Quand WordPress fait [quelque chose] (ex : afficher un titre), exécute cette fonction pour modifier ce [quelque chose].”apply_filters(): WordPress l’utilise pour “Appliquer les modifications que les développeurs ont ajoutées viaadd_filter().”
1- Add_filter sur un hook WordPress
// Fonction qui modifie le titre
function wp_codes_modifie_titre($titre) {
return $titre . ' - sur mon petit blog';
}
// Ajout du filtre pour modifier le titre sur le hook WordPress 'the_title'
add_filter('the_title', 'wp_codes_modifie_titre');
Explication :
- Le hook the_title : Ce hook est utilisé par WordPress avant d’afficher le titre d’un article.
- La fonction wp_codes_modifie_titre() : Cette fonction ajoute ” – Mon Blog” à la fin de chaque titre.
- add_filter(‘the_title’, …) : On attache notre fonction au hook the_title pour qu’elle soit exécutée à chaque fois que WordPress prépare à afficher un titre.
add_ et apply_filter() en 1 seul exemple
// Ajoutons "- Mon Blog" à chaque titre d'article
function wp_codes_modifie_titre($titre) {
return $titre . ' - Mon Blog';
}
// On attache notre fonction de modification au filtre 'the_title'
add_filter('the_title', 'wp_codes_modifie_titre');
// À un moment, WordPress applique tous les filtres ajoutés à 'the_title'
$titre = 'Mon Article';
$titre_modifie = apply_filters('the_title', $titre);
// Affiche le titre modifié
echo $titre_modifie; // Résultat : "Mon Article - Mon Blog"
Dans cet exemple, tous vos titres (articles et pages) vont devenir “Mon Article – Mon Blog”. Pas très utile ni très malin, n’est ce pas ? Bon, c’est pour l’exemple. Nous pouvons ajouter des conditions dans la fonction. Par exemple, si nous voulions ne l’appliquer qu’aux articles et pas aux pages, nous écririons :
function wp_codes_modifie_titre($titre) {
if (is_singular('post')) { // Appliquer seulement aux articles
return $titre . ' - Mon Blog';
}
return $titre; // Ne rien changer pour les autres types de contenu
}
// Attacher la fonction au filtre 'the_title'
add_filter('the_title', 'wp_codes_modifie_titre');
Variante : appliquer ce filtre à une catégorie précise d’articles :
function wp_codes_modifie_titre($titre) {
// Vérifie que c'est un article et qu'il est dans la catégorie "Tutos WP"
if (is_singular('post') && has_category('Tutos WP')) {
return $titre . ' - Tutos WP-Codes';
}
return $titre;
}
// On attache notre fonction au filtre 'the_title'
add_filter('the_title', 'wp_codes_modifie_titre');
Priorité et arguments des filtres WordPress
Vous pouvez définir plusieurs filtres sur le même hook. Dans ce cas, la priorité entre en jeu : un nombre qui définit dans quel ordre les filtres sont appliqués (plus le nombre est bas, plus le filtre est exécuté tôt).
Exemple avec plusieurs filtres sur le même hook :
// Ajoute un texte au début du titre
function wp_codes_ajout_debut_titre($titre) {
return 'Important: ' . $titre;
}
// Ajoute un texte à la fin du titre
function wp_codes_ajout_fin_titre($titre) {
return $titre . ' - Mon Blog';
}
// Ajout des filtres avec différentes priorités
add_filter('the_title', 'wp_codes_ajout_debut_titre', 5); // Priorité 5
add_filter('the_title', 'wp_codes_ajout_fin_titre', 10); // Priorité 10
//dans cet exemple, un article ayant pour titre "Comprendre WordPress"
//s'affichera "Important: Comprendre WordPress - Mon Blog"
Revenons sur apply_filter
- apply_filters() est une fonction interne à WordPress qui applique les filtres que vous ou d’autres développeurs avez ajoutés via add_filter().
- En fait, apply_filters() est rarement utilisé directement par les développeurs de thèmes ou plugins dans un contexte simple, car WordPress l’utilise déjà à l’intérieur de son propre code.
Dans notre exemple avec les titres, vous n’avez pas besoin de l’utiliser directement parce que WordPress appelle lui-même apply_filters() quand il affiche les titres.
Exemple pour comprendre apply_filters()
Imaginons que vous codiez un plugin ou une fonction personnalisée et que vous souhaitiez donner la possibilité à d’autres développeurs (ou à vous-même) de modifier une donnée avant qu’elle ne soit affichée ou utilisée. C’est là que vous utiliseriez apply_filters().
Exemple pratique
Disons que vous développez une fonction qui calcule un prix avec des taxes. Vous souhaitez laisser la possibilité à d’autres développeurs de modifier ce prix final via un filtre. Nous allons donc créer un filtre qui n’existe pas dans WordPress et nous l’appellerons “wp_codes_modifie_prix” :
function calculer_prix($prix_base) {
// Calcul du prix avec taxe de 20%
$prix_avec_taxe = $prix_base * 1.20;
// créer et appliquer le filtre pour permettre à d'autres développeurs de modifier ce prix
$prix_modifie = apply_filters('wp_codes_modifie_prix', $prix_avec_taxe);
return $prix_modifie;
}
Ce que fait apply_filters(‘wp_codes_modifie_prix’, $prix_avec_taxe) :
- ‘wp_codes_modifie_prix’ est le nom du filtre que vous définissez. Ce n’est pas un filtre qui existe déjà dans WordPress. En appelant apply_filters() avec ce nom, vous créez en fait un “point de filtrage” où d’autres développeurs (ou vous-même) peuvent s’accrocher pour modifier la valeur que vous passez en paramètre (ici, $prix_avec_taxe).
- apply_filters() prend deux paramètres ici :
- Le premier est le nom du filtre que vous inventez, dans ce cas, ‘wp_codes_modifie_prix’. Ce nom permettra à d’autres développeurs (ou vous-même) de l’utiliser avec add_filter() pour attacher leur propre fonction au filtre.
- Le second est la valeur que vous voulez passer à travers ce filtre, ici c’est $prix_avec_taxe. Cette valeur pourra être modifiée par toutes les fonctions qui se sont attachées à ce filtre via add_filter().
Donc, ce que vous faites ici, c’est donner la possibilité à d’autres développeurs d’intervenir et de modifier le prix avant qu’il ne soit renvoyé par votre fonction calculer_prix().
Comment d’autres développeurs peuvent utiliser ce filtre
Maintenant que vous avez créé un point de filtrage avec ‘wp_codes_modifie_prix’, un autre développeur (ou vous-même dans un autre endroit du code) peut s’accrocher à ce filtre avec add_filter pour modifier la valeur du prix.
Exemple pratique
Un autre développeur pourrait vouloir appliquer une réduction, par exemple, sur ce prix. Voici comment il le ferait en utilisant add_filter avec le nom du filtre que vous avez défini (‘wp_codes_modifie_prix’).
// Fonction qui applique une réduction de 10% sur le prix
function wp_codes_reduction($prix) {
return $prix * 0.90; // Applique une réduction de 10%
}
// On attache cette fonction au filtre 'wp_codes_modifie_prix'
add_filter('wp_codes_modifie_prix', 'wp_codes_reduction');
Explication de ce code
L’utilisation de add_filter(‘wp_codes_modifie_prix’, ‘wp_codes_reduction’) signifie que chaque fois que apply_filters(‘wp_codes_modifie_prix’, $prix) est appelé quelque part dans le code (comme dans votre fonction calculer_prix()), WordPress va appliquer la fonction wp_codes_reduction() pour modifier la valeur du prix.
Dans ce cas, le prix calculé initialement avec la taxe sera réduit de 10 % avant d’être renvoyé.
Résultat final
Si vous appelez calculer_prix(100) dans votre plugin, le prix sera d’abord calculé avec la taxe : 100 * 1.20 = 120. Ensuite, le filtre ‘wp_codes_modifie_prix’ sera appliqué et, si quelqu’un a attaché la fonction wp_codes_reduction(), le prix passera de 120 à 108 (réduction de 10 %). Le résultat final renvoyé sera donc 108.
Conclusion : comprendre les filtres WordPress
‘wp_codes_modifie_prix’ est le nom que vous attribuez au filtre que vous créez. apply_filters()applique ce filtre à la valeur $prix_avec_taxe et renvoie une valeur potentiellement modifiée. D’autres développeurs (ou vous-même) peuvent utiliser add_filter() avec ce nom de filtre pour modifier la valeur du prix dans des situations spécifiques, sans avoir à toucher au code original.
Cela rend votre code plus modulaire et extensible, car d’autres peuvent intervenir sans modifier la logique de base. Pour ce qui veulent aller plus loin voici des informations complémentaires pour comprendre les filtres WordPress :
