Pourquoi le résultat affiché à l’écran ne correspond-il ni à ce qu’attendait l’auteur du thème, ni à ce qu’attendait l’auteur de l’extension, alors que chacun a bien accroché son propre add_filter() sur le même hook the_content, l’un dans le functions.php du thème, l’autre dans une extension installée pour gérer les tableaux de contenu ? Lequel des deux filtres s’applique en dernier, et pourquoi ?
La réponse ne dépend jamais de l’ordre dans lequel les fichiers sont chargés par WordPress, ni du fait que le thème ou l’extension ait été installé en premier. Elle dépend uniquement d’un paramètre souvent oublié dans l’appel à add_filter() : la priorité.
Le paramètre de priorité, troisième argument d’add_filter()
La signature complète de add_filter() accepte quatre paramètres : le nom du hook, le callback, la priorité et le nombre d’arguments acceptés. Quand la priorité n’est pas précisée, WordPress applique une valeur par défaut de 10 :
// Thème : functions.php
add_filter( 'the_content', 'theme_ajouter_encadre', 10 );
// Extension : plugin-tableaux.php
add_filter( 'the_content', 'plugin_transformer_tableaux', 10 );
Ici, les deux callbacks partagent la même priorité 10. Dans ce cas précis, WordPress les exécute dans leur ordre d’enregistrement effectif, c’est-à-dire dans l’ordre où les appels à add_filter() ont été exécutés au moment du chargement de la page — ce qui dépend de l’ordre de chargement des fichiers contenant ces appels, pas de l’ordre d’installation du thème ou de l’extension.
Forcer un ordre précis avec une priorité différente
Pour garantir qu’un filtre s’exécute après tous les autres, il suffit de lui attribuer une priorité plus élevée que 10, par exemple 20 ou 999 selon la marge de sécurité souhaitée :
add_filter( 'the_content', 'theme_ajouter_encadre', 20 );
À l’inverse, une priorité plus basse, comme 5, garantit une exécution plus précoce, avant les filtres restés à leur valeur par défaut. Il n’existe pas de limite haute ou basse imposée par le cœur : seule la cohérence entre les priorités choisies compte.
Diagnostiquer l’ordre réel avec Query Monitor
L’extension Query Monitor affiche, dans son panneau dédié aux hooks, la liste complète des callbacks accrochés à un hook donné pour la requête en cours, classés dans leur ordre d’exécution réel avec leur priorité affichée à côté de chacun. C’est le moyen le plus rapide de vérifier, sans ajouter de error_log() temporaire, quel filtre s’exécute avant l’autre et à quelle priorité chacun est réellement enregistré.
Le piège des callbacks anonymes qui se marchent dessus
Quand le thème et l’extension utilisent tous les deux une fonction anonyme (function () { ... }) plutôt qu’une fonction nommée, il devient impossible de retirer l’un des deux filtres avec remove_filter(), faute de référence exploitable vers le callback. Un thème qui a besoin de neutraliser un filtre ajouté par une extension gagne donc à connaître le nom exact de la fonction ou de la méthode enregistrée par cette extension, information généralement disponible dans sa documentation ou son code source.
Deux filtres à la même priorité qui produisent un résultat imprévisible ne sont presque jamais en conflit à cause d’un bug : ils appliquent simplement des transformations successives dans un ordre que personne n’a explicitement choisi.
Retirer un filtre indésirable plutôt que d’en ajouter un troisième
Face à un filtre d’extension qui produit un rendu indésirable, la tentation consiste souvent à ajouter un troisième filtre correctif par-dessus les deux premiers. Une solution plus propre, quand la fonction ou la méthode fautive est identifiable, consiste à la retirer directement avec remove_filter(), en indiquant exactement la même priorité que celle utilisée lors de son ajout :
remove_filter( 'the_content', array( 'Plugin_Tableaux', 'transformer' ), 10 );
Si la priorité indiquée dans remove_filter() ne correspond pas exactement à celle utilisée lors de l’ajout, le retrait échoue silencieusement, sans message d’erreur, et le filtre reste actif.
En résumé
La priorité d’un add_filter(), souvent laissée à sa valeur par défaut par habitude, détermine à elle seule l’ordre d’exécution entre un thème et une extension accrochés au même hook. Avant de chercher un conflit de configuration compliqué, une simple lecture des priorités déclarées, complétée par un passage dans Query Monitor, suffit généralement à comprendre pourquoi un contenu ne s’affiche pas comme prévu.
