Modifier le titre d’un article avant son affichage, ajuster une adresse e-mail d’expédition ou allonger un extrait automatique : dans tous ces cas, WordPress transmet une donnée existante à qui veut bien la retoucher, contrairement à une simple notification d’événement qui ne rend rien.
Différence avec une action
Un filtre s’accroche avec add_filter() et sa fonction de rappel doit impérativement retourner une valeur, même si elle ne la modifie pas :
add_filter( 'the_title', function ( $titre ) {
return '★ ' . $titre;
} );À l’inverse, un « action hook » exécute simplement du code à un moment donné (par exemple envoyer un e-mail), sans transmettre de valeur à retourner : c’est la distinction fondamentale à retenir entre les deux familles de crochets.
Appliquer ses propres filtres
Une extension peut elle-même exposer des points d’extension avec apply_filters(), permettant à d’autres extensions ou au thème de modifier ses données internes sans toucher à son code source.
Pièges fréquents
- Oublier de retourner la valeur dans la fonction de rappel remplace silencieusement la donnée d’origine par
null. - La priorité (troisième argument de
add_filter()) détermine l’ordre d’exécution quand plusieurs filtres s’appliquent au même hook ; la valeur par défaut est 10. - Le quatrième argument précise le nombre de paramètres attendus par la fonction de rappel : l’omettre alors que le filtre transmet plusieurs valeurs revient à ignorer silencieusement les arguments supplémentaires.
- Un même filtre peut recevoir plusieurs fonctions accrochées par des extensions différentes, chacune recevant en entrée la valeur déjà transformée par la précédente dans l’ordre de priorité établi.