# Quand un hook est filtré par le thème et par un plugin, lequel gagne vraiment

> Deux add_filter() sur le même hook, un thème et une extension, un résultat qui ne correspond à aucun des deux : la réponse tient à la priorité, pas à l'ordre de chargement des fichiers.

- Auteur : WordPress Développement
- Publié le : 2023-09-28
- Mis à jour le : 2023-09-28
- Catégorie : Thèmes
- URL : https://www.wpmoderne.fr/themes/hook-filtre-theme-plugin-priorite-qui-gagne/

## L’essentiel

- La priorité par défaut d'add_filter() est 10 pour tous les appels
- Deux callbacks à la même priorité s'exécutent dans leur ordre d'enregistrement
- Query Monitor affiche tous les callbacks accrochés à un hook donné

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.

> L'essentiel à retenir : La priorité par défaut d'add_filter() est 10 pour tous les appels ; Deux callbacks à la même priorité s'exécutent dans leur ordre d'enregistrement ; Query Monitor affiche tous les callbacks accrochés à un hook donné

## 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.