WP_REST_Request::get_url_params()

Définition : WP_REST_Request::get_url_params() récupère les paramètres extraits du chemin d’une route REST WordPress. Elle permet de lire les identifiants associés à des segments dynamiques déclarés dans le routage.

Comprendre et utiliser

À quoi sert cette notion ?

Elle sert à identifier la ressource visée sans la confondre avec des options passées en query string ou dans le corps d’une requête.

Fonctionnement technique

Lorsqu’une route contient un groupe nommé, par exemple (?P<id>\d+), la valeur capturée est stockée parmi les paramètres d’URL du WP_REST_Request.

Dans quel contexte l’utiliser ?

Une route /documents/42 permet de cibler le document numéro 42 pour en consulter le statut.

Étude de cas : application professionnelle

Une route /documents/(?P<id>\d+) doit identifier une fiche par son numéro sans confondre ce numéro avec un filtre de recherche. get_url_params() fournit l’identifiant capturé, tandis que get_query_params() peut transporter des options secondaires. Examiner une requête avec id=42 dans le chemin et page=2 dans la query string permet de visualiser cette séparation. Une expression régulière mal conçue peut refuser un chemin avant même la callback. Tester les identifiants valides, manquants, négatifs et non numériques pour confirmer la logique du routage.

Exemple technique commenté

Cet extrait est destiné à un fichier PHP chargé par WordPress, idéalement dans un plugin local de test. Il ne doit pas être placé dans l'éditeur de contenu. Avant exécution, vérifier que les objets et variables mentionnés existent dans le contexte et que les permissions nécessaires sont définies.

<?php
// Dans une callback de route comportant (?P<id>\d+).
$params = $request->get_url_params();
$id     = isset( $params['id'] ) ? absint( $params['id'] ) : 0;

Décryptage du code et résultat attendu

Le code lit seulement les valeurs extraites du chemin. Le groupe nommé doit déjà avoir été défini lors de register_rest_route().

Exercice guidé pour vérifier la notion

Créer deux URL de test avec des identifiants différents et comparer get_url_params() à get_query_params().

Précautions et limites

Ne pas déduire une autorisation de la présence de l’identifiant : une permission_callback doit encore vérifier les droits sur la ressource.

À ne pas confondre

Les URL params proviennent du chemin de route ; les query params proviennent de la partie ?clé=valeur.

Diagnostic avancé

Une erreur 404 sur un identifiant alphanumérique peut venir d’une expression régulière de route trop restrictive, avant même l’exécution de la callback.