rest_validate_value_from_schema()
Définition : rest_validate_value_from_schema() vérifie une valeur PHP selon un schéma REST pris en charge par WordPress. Elle renvoie true si la valeur est valide, sinon un WP_Error expliquant le problème.
Comprendre et utiliser
À quoi sert cette notion ?
Elle permet de contrôler un type, une longueur, une borne ou une énumération de manière cohérente avec les contrats déclarés pour l’API.
Fonctionnement technique
La fonction évalue la valeur et les contraintes du schéma sans corriger automatiquement l’entrée. C’est pourquoi la validation précède en général la normalisation des données.
Dans quel contexte l’utiliser ?
Un endpoint de suivi n’accepte que les statuts brouillon, en_cours ou termine.
Étude de cas : application professionnelle
Avant de stocker un réglage reçu par API, vérifier son type et les valeurs admises. rest_validate_value_from_schema() fournit une base structurée pour ce contrôle. Pour un statut, définir explicitement l’énumération autorisée plutôt qu’accepter n’importe quelle chaîne. Une série de tests doit couvrir une valeur conforme, une faute de frappe, un nombre et une valeur nulle. Chaque refus doit produire une information utile au client sans dévoiler de données internes. L’autorisation de modifier ce statut reste un contrôle indépendant qui précède l’action réelle.
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
$schema = array( 'type' => 'string', 'enum' => array( 'brouillon', 'en_cours', 'termine' ) );
$result = rest_validate_value_from_schema( 'en_cours', $schema, 'statut' );
if ( is_wp_error( $result ) ) {
return $result;
}Décryptage du code et résultat attendu
L’exemple définit trois valeurs admises. Il obtient true pour en_cours et un WP_Error pour un libellé non reconnu.
Exercice guidé pour vérifier la notion
Changer successivement la valeur en brouillon puis inconnue et examiner le résultat exact de la fonction.
Précautions et limites
Valider ne signifie pas autoriser la modification de la ressource. Le résultat doit être associé aux règles de permission et au contexte.
À ne pas confondre
La validation répond « accepté ou refusé » ; rest_sanitize_value_from_schema() peut convertir ou assainir certaines valeurs.
Diagnostic avancé
Si une validation laisse passer un type incorrect, contrôler les clés type, enum et les restrictions documentées.
Choix d’architecture et déploiement
Valider à la frontière HTTP, puis vérifier les invariants métiers indépendamment de la couche REST.
