rest_ensure_response()
Définition : rest_ensure_response() convertit une valeur PHP en objet de réponse REST WordPress lorsque nécessaire. Elle préserve les WP_Error et garantit une forme de retour compatible avec le serveur REST.
Comprendre et utiliser
À quoi sert cette notion ?
Elle simplifie l’écriture de callbacks qui renvoient tantôt des tableaux, tantôt des objets de réponse déjà construits, sans multiplier les tests de type.
Fonctionnement technique
Si la valeur est un WP_Error, la fonction le retourne sans le transformer en succès. Sinon, elle réutilise une réponse compatible ou encapsule les données dans un WP_REST_Response.
Dans quel contexte l’utiliser ?
Un endpoint calcule une synthèse publique et souhaite lui ajouter un en-tête de diagnostic avant retour.
Étude de cas : application professionnelle
Lorsque plusieurs callbacks retournent des types différents, le traitement final peut devenir fragile. Une callback renvoie un tableau, une autre renvoie un WP_REST_Response et une troisième un WP_Error. rest_ensure_response() standardise les réponses positives tout en préservant les erreurs. Écrire trois tests ciblés permet de comprendre cette différence et d’éviter l’hypothèse « tout résultat possède header() ». Les erreurs doivent rester des erreurs, pas devenir des données JSON présentées avec 200. Cet exercice renforce la robustesse des contrôleurs de plugins.
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
$data = array( 'total' => 3 );
$response = rest_ensure_response( $data );
$response->header( 'X-Atolpha-Test', '1' );
return $response;Décryptage du code et résultat attendu
La fonction garantit ici un objet sur lequel header() est disponible. Le code suppose une donnée locale simple ; aucune base de données n’est sollicitée.
Exercice guidé pour vérifier la notion
Rentrer un tableau puis un WP_Error dans une petite fonction de test et inspecter le type du résultat avant d’appeler une méthode.
Précautions et limites
Ne pas appeler les méthodes de réponse sans tenir compte du cas WP_Error si la valeur initiale peut représenter une erreur.
À ne pas confondre
rest_ensure_response() normalise une sortie ; rest_do_request() exécute une requête interne. Les noms proches ne décrivent pas le même rôle.
Diagnostic avancé
Si un code provoque une erreur de méthode inexistante, vérifier que la valeur n’est pas un WP_Error conservé par la normalisation.
Choix d’architecture et déploiement
Employer cette fonction près de la frontière HTTP, non pour masquer les erreurs des couches métier.
