register_rest_field()
Définition : register_rest_field() ajoute un champ supplémentaire à la représentation REST d’un type d’objet WordPress. Elle associe ce champ à des callbacks de lecture et éventuellement d’écriture, ainsi qu’à un schéma.
Comprendre et utiliser
À quoi sert cette notion ?
Elle permet d’exposer une donnée calculée ou un champ métier sans modifier directement les tables du Core.
Fonctionnement technique
La fonction enregistre un attribut pour un type d’objet, tel que post. La callback de lecture reçoit l’objet préparé et renvoie la valeur ; l’écriture reste optionnelle et doit être protégée.
Dans quel contexte l’utiliser ?
Une API documentaire ATOOLPHA souhaite ajouter un indicateur public indiquant qu’une publication appartient à une sélection éditoriale.
Étude de cas : application professionnelle
Pour afficher un champ calculé dans une réponse d’article, commencer par déterminer s’il dépend de données publiques ou privées. register_rest_field() accepte une callback de lecture et un schéma pour le champ exposé. Créer d’abord un exemple qui renvoie seulement un booléen fictif, puis contrôler sa présence dans la réponse JSON. Si un champ est une métadonnée enregistrée et persistante, les mécanismes de register_post_meta() sont parfois plus appropriés. Ce choix architectural doit être pris avant de développer une callback d’écriture qui reproduirait inutilement le Core.
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
add_action( 'rest_api_init', function () {
register_rest_field( 'post', 'atoolpha_demo', array(
'get_callback' => fn( $object ) => ! empty( $object['id'] ),
'schema' => array( 'type' => 'boolean', 'context' => array( 'view' ) ),
) );
} );Décryptage du code et résultat attendu
Le champ démonstratif signale seulement si l’objet possède un identifiant non vide. Aucun champ privé ni métadonnée réelle n’est exposé.
Exercice guidé pour vérifier la notion
Exposer le champ fictif sur un article test et vérifier sa présence dans la réponse et sa description de schéma.
Précautions et limites
La callback de lecture ne doit pas divulguer des données protégées. Définir un schéma et vérifier les droits pour toute opération d’écriture.
À ne pas confondre
register_rest_field() expose un champ arbitraire ; register_post_meta() avec show_in_rest expose une métadonnée enregistrée selon les mécanismes du Core.
Diagnostic avancé
Si un champ n’apparaît pas, vérifier l’objet cible, le contexte et la présence effective de la callback de lecture.
Choix d’architecture et déploiement
Pour les métadonnées persistantes, préférer les API natives quand elles conviennent ; réserver le champ personnalisé aux données calculées ou à un contrat spécifique.
