« developer.wordpress.org » décrit rest_pre_dispatch comme un filtre qui « permet de court-circuiter la répartition normale du serveur REST ». La formulation est sobre, mais la portée du filtre est large : il s’exécute avant l’appel de n’importe quel contrôleur, sur n’importe quelle route, ce qui en fait l’un des points d’extension les plus puissants — et les plus dangereux à mal utiliser — de toute l’API REST de WordPress.
Fonctionnement du filtre
Contrairement aux filtres rest_prepare_{post_type} qui n’agissent que sur un type de contenu précis, rest_pre_dispatch se déclenche pour absolument toutes les requêtes qui transitent par le serveur REST, juste après la résolution de la route mais avant l’exécution du callback associé. Il reçoit trois arguments : la réponse courante (généralement null à ce stade), l’objet WP_REST_Server, et la requête WP_REST_Request en cours de traitement.
Tant que le filtre renvoie null, WordPress poursuit son traitement normal et appelle le contrôleur prévu pour la route. Dès qu’une fonction accrochée à ce filtre renvoie autre chose — un tableau, un objet WP_REST_Response, ou une instance de WP_Error — WordPress considère que la requête est déjà traitée et n’exécute jamais le contrôleur d’origine.
Un cas d’usage : court-circuit de cache
add_filter( 'rest_pre_dispatch', function( $result, $server, $request ) {
if ( 'GET' !== $request->get_method() ) {
return $result;
}
$cle = 'rest_cache_' . md5( $request->get_route() . serialize( $request->get_params() ) );
$cache = get_transient( $cle );
if ( false !== $cache ) {
$reponse = new WP_REST_Response( $cache );
$reponse->header( 'X-Cache', 'HIT' );
return $reponse;
}
return $result;
}, 10, 3 );
Ce filtre vérifie l’existence d’un transient correspondant à la route et aux paramètres de la requête. Si la donnée existe déjà en cache, il construit directement une réponse et la retourne, évitant totalement l’exécution du contrôleur d’origine — y compris les requêtes SQL qu’il aurait déclenchées. Ce genre de court-circuit reste toutefois incomplet sans une logique d’écriture du cache ailleurs, par exemple dans le filtre rest_post_dispatch qui, lui, s’exécute après le contrôleur.
Un autre cas d’usage : permission globale
Pour un projet qui souhaite fermer l’ensemble de son API REST sauf pour quelques routes précises — un scénario fréquent sur un site headless dont le contenu n’est pas destiné au grand public — rest_pre_dispatch permet d’appliquer une vérification unique, sans devoir répéter un permission_callback sur chaque route existante ou à venir :
- Vérifier la route demandée via
$request->get_route() - Laisser passer les routes explicitement autorisées (une liste blanche courte, plus sûre qu’une liste noire)
- Retourner un
WP_Erroravec le statut 401 pour tout le reste
Pièges d’un retour mal formé
Le principal piège de ce filtre tient à sa portée globale : une erreur de logique qui renvoie systématiquement une valeur non nulle, même par accident, casse instantanément toutes les routes REST du site, y compris celles utilisées par l’administration elle-même pour l’éditeur de blocs. Un test conditionnel mal écrit — qui oublie de retourner $result dans la branche par défaut — suffit à provoquer ce genre d’incident, généralement détecté très vite tant l’effet est massif, mais parfois seulement après mise en production si les tests locaux ne couvrent pas l’ensemble des routes concernées.
Autre piège plus subtil : retourner un tableau brut plutôt qu’un objet WP_REST_Response ou WP_Error fonctionne, mais prive la réponse court-circuitée des en-têtes et du statut que le contrôleur d’origine aurait normalement fournis. Pour un court-circuit de cache, cela peut suffire à casser un en-tête Cache-Control attendu par un CDN placé devant l’API.
En résumé
rest_pre_dispatch reste l’un des filtres les plus puissants pour intervenir globalement sur l’API REST de WordPress, que ce soit pour un cache applicatif, une restriction d’accès générale ou un routage personnalisé. Sa portée transversale impose cependant une rigueur particulière : chaque branche du code doit explicitement retourner la valeur d’origine quand elle ne souhaite pas intervenir, sous peine de bloquer silencieusement l’ensemble des routes du site.
