API WP REST internes et personnalisation

Dans la partie précédente de la série, nous avons appris à créer, mettre à jour et supprimer du contenu à distance via l’API WP REST. Il nous permet de créer des applications indépendantes de la plate-forme qui fonctionnent de manière transparente avec un back-end propulsé par WordPress, offrant une expérience riche à l'utilisateur..

Dans la partie actuelle de la série, nous examinerons les composants internes de l'API WP REST et la manière dont ils fonctionnent ensemble pour l'activer. Nous apprendrons ensuite à modifier les réponses du serveur pour que les ordinateurs d'extrémité par défaut incluent des champs personnalisés..

Pour être précis, dans le présent article, nous allons:

en savoir plus sur les classes et méthodes internes de l'API WP REST
modifier la réponse du serveur pour les ordinateurs d'extrémité par défaut
apprendre à rendre les champs personnalisés modifiables

Commençons donc par jeter un coup d'œil sur les composants internes de l'API WP REST..

Classes et méthodes internes de l'API WP REST

Les classes de l'API WP REST peuvent être divisées en deux catégories:

Classes d'infrastructure: Ce sont les classes fondamentales responsables de la consolidation de l'API. Ils n'effectuent aucune transformation de données.
Classes d'extrémité: Ces classes sont responsables de l'exécution d'opérations CRUD sur des ressources telles que des publications, des pages, des utilisateurs, des commentaires, etc..

Jetons un coup d'oeil aux classes individuelles de chacune des deux catégories ci-dessus.

Classes d'infrastructure

Les trois classes d'infrastructure qui alimentent l'API REST sont les suivantes:

WP_REST_Server
WP_REST_Request
WP_REST_Response

WP_REST_Server

Il s'agit de la classe principale de l'API WP REST qui implémente le serveur REST en enregistrant les itinéraires, en répondant aux demandes et en préparant les réponses. Il formate les données à transmettre au client et en cas d'erreur, il prépare l'erreur en incluant le code d'erreur et le corps du message. Il vérifie également l'authentification.

Nous avons beaucoup travaillé avec le / wp-json index endpoint pour la vérification de toutes les fonctionnalités et des routes prises en charge pour un site. La méthode get_index (), qui est responsable de la récupération de l'index du site, est également situé dans cette classe.

Pour répondre aux demandes et préparer les réponses, le WP_REST_Server la classe utilise le WP_REST_Request et WP_REST_Response classes respectivement.

WP_REST_Request

le WP_REST_Request La classe implémente l'objet de requête pour l'API WP REST. Il contient des données de la requête telles que les en-têtes et le corps de la requête, et est transmis à la fonction de rappel par le WP_REST_Server classe. Il vérifie également si les paramètres transmis lors de la demande sont valides et procède à la désinfection des données, le cas échéant..

WP_REST_Response

le WP_REST_Response class, comme son nom l'indique, implémente l'objet de réponse. Il contient les données nécessaires telles que le code d'état de la réponse et le corps de la réponse..

Voyons maintenant les classes d'extrémité.

Classes d'extrémité

Les classes de points de terminaison de l'API WP REST sont responsables de l'exécution des opérations CRUD. Ces cours comprennent WP_REST_Posts_Controller, WP_REST_Taxonomies_Controller, WP_REST_Users_Controller, etc. Toutes ces classes de points de terminaison étendent une seule classe abstraite WP_REST_Controller qui fournit un modèle cohérent pour modifier les données.

le WP_REST_Controller classe comprend des méthodes telles que obtenir l'article(), create_item (), update_item (), effacer l'article(), etc., pour effectuer des opérations CRUD. Ces méthodes doivent être remplacées par des sous-classes en implémentant leur propre abstraction pour extraire, créer, mettre à jour et modifier des données..

Vous pouvez trouver plus d'informations sur ces classes et leurs méthodes internes dans la documentation officielle.

Après avoir étudié les classes internes de l'API WP REST, voyons comment modifier les réponses du serveur pour les noeuds finaux par défaut afin d'inclure des champs personnalisés..

Modification des réponses du serveur

Dans la section précédente, nous avons examiné les classes internes et les méthodes sur lesquelles l'API est construite. Ensemble, ces classes et méthodes pilotent l'API dans son ensemble et offrent aux développeurs un moyen d'étendre l'API pour qu'elle prenne en compte différents scénarios et cas d'utilisation..

L'API REST WP expose les données de manière prévisible. Cela inclut diverses ressources telles que les publications, les méta de publication, les pages et les utilisateurs, ainsi que leurs propriétés standard. Mais ces données ne peuvent pas toujours être conformes aux besoins de chaque site ou utilisateur WordPress. Par conséquent, l’API REST WP fournit un moyen de modifier les données renvoyées par le serveur pour chacun des itinéraires par défaut..

le register_rest_field () La méthode fournit un moyen d'ajouter ou de mettre à jour des champs dans la réponse pour un objet. Toutefois, l'API n'encourage jamais la modification d'un champ à partir d'une réponse, car cela pourrait entraîner des problèmes de compatibilité pour les clients qui attendent une réponse standard du serveur. Donc, si vous avez besoin de changer un champ, vous devriez envisager de le dupliquer avec la valeur souhaitée.

De même, la suppression d'un champ par défaut est fortement déconseillée car un client peut l'attendre. Si vous avez besoin d'un plus petit sous-ensemble de la réponse renvoyée par le serveur, vous devez créer des contextes supplémentaires en plus des contextes par défaut tels que vue ou modifier.

Nous pouvons toutefois ajouter en toute sécurité un champ à la réponse renvoyée par le serveur pour un ou plusieurs objets. Ces champs peuvent contenir n’importe quelle valeur allant de la méta post ou user à toute autre valeur arbitraire..

Dans la section suivante, nous travaillerons avec le register_rest_field () méthode pour ajouter des champs personnalisés à la réponse renvoyée par le serveur pour la poster objet.

Travailler avec le `register_rest_field ()` Méthode

Comme mentionné précédemment, le register_rest_field () Cette méthode peut être utilisée pour ajouter ou mettre à jour des champs dans la réponse renvoyée par le serveur. Cette méthode accepte trois arguments:

$ object_type
attribut $
$ args

le $ object_type L'argument peut être une chaîne ou un tableau contenant les noms de tous les objets pour lesquels nous souhaitons ajouter le champ. Ces objets peuvent être poster, terme, commentaire, utilisateur, etc. Si nous devons ajouter un champ personnalisé à un type de publication personnalisé, la $ object_type l'argument serait le nom du type de message.

le attribut $ argument est le nom du champ personnalisé. Ce nom apparaîtrait dans la réponse du serveur en tant que clé avec sa valeur..

le $ args array est un tableau associatif pouvant contenir les trois clés suivantes:

$ get_callback
$ update_callback
$ schéma

Les valeurs des deux premières clés sont les noms des méthodes utilisées pour obtenir ou mettre à jour la valeur du champ personnalisé. Le dernier $ schéma key définit la méthode ou la variable utilisée pour définir le schéma du champ personnalisé.

Toutes les clés ci-dessus sont facultatives, mais si elles ne sont pas ajoutées, la capacité ne sera pas ajoutée. Par exemple, si vous définissez le $ get_callback clé mais pas la $ update_callback clé, la fonctionnalité de récupération sera ajoutée mais la fonctionnalité de mise à jour ne sera pas ajoutée. Si vous omettez le $ get_callback clé, le champ ne sera pas ajouté à la réponse.

le register_rest_field () méthode fonctionne en modifiant la $ wp_rest_additional_fields variable. Cette variable de tableau contient les champs enregistrés par types d'objet à renvoyer dans la réponse par le serveur. Chaque fois qu'un champ est enregistré par le register_rest_field () méthode, il est ajouté à la $ wp_rest_additional_fields variable. Cependant, en modifiant le $ wp_rest_additional_fields variable manuellement est fortement déconseillée.

Ajout de champs personnalisés à la réponse

Après s'être familiarisé avec le register_rest_field () méthode, nous pouvons maintenant modifier la réponse pour la poster objet. Dans ce cas, un cas typique d'utilisation serait l'ajout d'un champ de nom d'affichage d'auteur, qui est généralement nécessaire lors de la publication de publications sur une page d'index. Comme la réponse standard n'inclut pas ce champ, nous pouvons utiliser le register_rest_field () méthode pour l'inclure dans la réponse.

Nous commençons par créer un plugin simple. Alors créez un nouveau dossier nommé modificateur de réponse au repos dans ton / wp-content / plugins annuaire. Créer un vide index.php déposer et coller dans la définition de plugin suivante:

le register_rest_field () la méthode doit être enregistrée dans le rest_api_init action. Par conséquent, nous créons une fonction nommée bs_add_custom_rest_fields () et le lier à la rest_api_init crochet:
Notez que les balises PHP d'ouverture  ne sont pas requis ici, mais je les ai inclus pour que la syntaxe soit surlignée correctement.
À l'intérieur de bs_add_custom_rest_fields () fonction, nous pouvons utiliser le register_rest_field () méthode pour inclure un champ pour le nom de l'auteur:
function bs_add_custom_rest_fields () // schéma du champ bs_author_name $ bs_author_name_schema = tableau ('description' => 'nom de l'auteur de l'article', 'type' => 'chaîne', 'contexte' => tableau ('vue') ) // enregistrement du champ bs_author_name register_rest_field ('post', 'bs_author_name', array ('get_callback' => 'bs_get_author_name', 'update_callback' => null, 'schema' => $ bs_author_name_schema); 
Comme mentionné dans la section précédente, le premier argument de la register_rest_field () méthode est le nom de l'objet pour lequel nous modifions la réponse. Puisque nous devons modifier la réponse pour le poster objet, on passe le même que le premier argument.
Le deuxième argument du code ci-dessus est le nom du champ qui apparaîtra dans la réponse. Il est toujours recommandé de préfixer le nom d'un champ personnalisé dans la réponse afin d'assurer une compatibilité maximale avec la transmission et d'éviter que celui-ci ne soit remplacé à l'avenir par d'autres plug-ins. Par conséquent, nous passons bs_author_name dans le deuxième argument en tant que attribut $ du champ personnalisé.
Le troisième et dernier argument du code ci-dessus est un tableau pour les méthodes de rappel et le schéma. Ce tableau contient le nom des méthodes de rappel pour la récupération et la mise à jour du champ personnalisé dans le répertoire. $ get_callback et $ update_callback touches respectivement. Nous passons le bs_get_author_name fonctionne comme méthode de rappel de récupération. Nous définirons cette fonction sous peu.
Pour le $ update_callback clé, on passe nul puisqu'il s'agit d'un champ en lecture seule et qu'il n'est pas nécessaire de mettre à jour le nom de l'auteur pour un message.
Pour le $ schéma clé, nous passons un tableau nommé $ bs_author_name_schema. Ce tableau contient diverses propriétés pour le champ, telles que le type de données, le contexte et la description..
La seule chose que nous devons définir maintenant est la bs_get_author_name () fonction qui agira comme le $ get_callback méthode pour notre champ personnalisé. Ci-dessous le code pour cette fonction:
/ ** * Rappel pour récupérer le nom de l'auteur * @param tableau $ objet L'objet de publication en cours * * @param chaîne $ nom_zone Le nom du champ * @param WP_REST_request $ request La demande en cours * @ chaîne de retour Le nom de l'auteur * / function bs_get_author_name ($ object, $ field_name, $ request) return get_the_author_meta ('display_name', $ object ['author']); 
le $ get_callback méthode reçoit trois arguments pour les éléments suivants:
  $ object: L'objet actuel. Dans notre cas, c'est le post actuel.
  $ field_name: Le nom du champ personnalisé ajouté.
  $ request: L'objet requête.
 
Nous utilisons le $ auteur propriété du $ object argument qui contient l'identifiant de l'auteur du message. Et en utilisant le get_the_author_meta () fonction, nous récupérons et renvoyons le nom complet de l'auteur pour le message en cours.
Maintenant que le champ est enregistré, nous pouvons envoyer un OBTENIR demande au / wp / v2 / posts route pour voir si cela fonctionne correctement:
Voici la réponse dans Postman:
Ce champ personnalisé nouvellement enregistré apparaîtra également dans la réponse du serveur, avec son schéma, lorsque nous enverrons un message. OPTIONS demande au / wp / v2 / posts route:
Par conséquent, un champ personnalisé pour la propriété de nom d’auteur a été enregistré avec succès. Mais ce champ est en lecture seule car nous ne pouvons pas le mettre à jour en envoyant un message. POSTER demande. Dans la section suivante, nous allons enregistrer un champ modifiable pour le nombre de vues de publication..
Enregistrement d'un champ éditable
Nous allons maintenant enregistrer un champ personnalisé pour le nombre de vues de publication. Nous ne traiterons que de l'enregistrement réel du champ avec l'API WP REST, en laissant de côté l'implémentation permettant d'incrémenter le nombre..
Ci-dessous le code pour bs_post_views enregistrement de champ personnalisé avec son schéma:
// schéma du champ bs_post_views $ bs_post_views_schema = array ('description' => 'Nombre de vues postées', 'type' => 'entier', 'context' => array ('view', 'edit')); // enregistrement du champ bs_post_views register_rest_field ('post', 'bs_post_views', array ('get_callback' => 'bs_get_post_views', 'update_callback' => 'bs_update_post_views', 'schema' => $ bs_post_views_sch)
Le code est similaire à celui que nous avons écrit dans la section précédente, à la différence qu’il inclut maintenant une méthode de rappel. bs_update_post_views pour le $ update_callback clé. Cette fonction est responsable de la mise à jour de la valeur du champ.
le $ contexte propriété dans le $ bs_post_views_schema tableau de schéma comprend deux valeurs pour vue et modifier. Inclusion de la valeur d'édition dans le $ contexte argument assure que le bs_post_views le champ est renvoyé dans la réponse du serveur après sa mise à jour.
Les méthodes de rappel et de mise à jour sont les suivantes:
/ ** * Rappel pour récupérer les vues de publication comptent * @param tableau $ objet Objet de publication actuel * @param chaîne $ nom_zone Nom du champ * @param WP_REST_request $ request Demande actuelle * @return entier Nombre de vues de publication * / fonction bs_get_post_views ($ object, $ field_name, $ request) return (int) get_post_meta ($ object ['id'], $ field_name, true);  / ** * Rappel pour la mise à jour des vues de publication compte * @param mixte $ valeur Comptage de publication des observations * @param objet $ objet Objet de la réponse * @param chaîne $ nom_zone Nom du champ actuel * @return bool | int * / fonction bs_update_post_views ($ value, $ object, $ field_name) if (! $ value ||! is_numeric ($ value)) return;  return update_post_meta ($ object-> ID, $ champ_nom, (int) $ valeur); 
Le code est assez simple car il utilise la get_post_meta () et update_post_meta () méthodes pour récupérer et mettre à jour les valeurs respectivement.
le bs_get_post_views () La méthode récupère d'abord la méta valeur pour le bs_post_views clé méta et le convertit en un entier avant de le renvoyer.
La méthode de rappel passée dans $ update_callback reçoit trois arguments pour les éléments suivants:
  $ valeur: La nouvelle valeur du champ.
  $ object: Objet actuel de la réponse.
  $ field_name: Le nom du champ en cours de mise à jour.
 
dans le bs_update_post_views () méthode, nous vérifions d’abord si la valeur transmise n’est pas vide et est une valeur numérique. Sinon, on rentre sans rien faire.
Si la valeur est numérique, nous la passons à update_post_meta () fonction qui l’enregistre dans la base de données après le typage en un entier valide.
Après avoir enregistré le champ avec succès, testons-le en envoyant un OBTENIR demande:
$ GET / wp / v2 / posts
Vous trouverez ci-dessous un exemple de réponse à la demande ci-dessus:
Comme on peut le voir dans l’image ci-dessus, la valeur actuelle de bs_post_views le champ est 0 pour un article donné. C'est parce que le get_post_meta () La méthode retourne une chaîne vide puisqu'elle n'a pas pu trouver de méta-valeur pour le bs_post_views la méta-clé et la transtypage d'une chaîne vide en un entier en PHP ont pour résultat 0.
Nous pouvons mettre à jour le bs_post_views terrain en envoyant un POSTER demande au / wp / v2 / posts / point final. Le corps JSON de la demande est le suivant:
"bs_post_views": 4050
Si la requête aboutit, le serveur renvoie un message. 200 - OK code de statut avec l'objet post mis à jour qui comprend également le bs_post_views champ:
le bs_post_views le champ personnalisé est maintenant mis à jour.
Notez que nous avons envoyé un corps JSON avec la demande de mise à jour du champ. Le corps JSON incluait le nom du champ-bs_post_views-avec une valeur entière de 4050. Si nous essayons d'envoyer une valeur non numérique, disons "Abc1234", le champ ne sera pas mis à jour car nous avons une condition de vérification pour une valeur numérique dans le bs_update_post_views () méthode de rappel.
Vous trouverez ci-dessous le code source complet du plugin:
 'Nom de l'auteur du message', 'type' => 'chaîne', 'contexte' => array ('view')); // enregistrement du champ bs_author_name register_rest_field ('post', 'bs_author_name', array ('get_callback' => 'bs_get_author_name', 'update_callback' => null, 'schema' => $ bs_author_name_schema); // schéma du champ bs_post_views $ bs_post_views_schema = array ('description' => 'Nombre de vues postées', 'type' => 'entier', 'context' => array ('view', 'edit')); // enregistrement du champ bs_post_views register_rest_field ('post', 'bs_post_views', array ('get_callback' => 'bs_get_post_views', 'update_callback' => 'bs_update_post_views', 'schema' => $ bs_post_views_sch)  / ** * Rappel pour récupérer le nom de l'auteur * @param tableau $ objet L'objet de publication en cours * * @param chaîne $ nom_zone Le nom du champ * @param WP_REST_request $ request La demande en cours * @ chaîne de retour Le nom de l'auteur * / function bs_get_author_name ($ object, $ field_name, $ request) return get_the_author_meta ('display_name', $ object ['author']);  / ** * Rappel pour récupérer les vues de publication comptent * @param tableau $ objet Objet de publication actuel * @param chaîne $ nom_zone Nom du champ * @param WP_REST_request $ request Demande actuelle * @return entier Nombre de vues de publication * / fonction bs_get_post_views ($ object, $ field_name, $ request) return (int) get_post_meta ($ object ['id'], $ field_name, true);  / ** * Rappel pour la mise à jour des vues de publication compte * @param mixte $ valeur Comptage de publication des observations * @param objet $ objet Objet de la réponse * @param chaîne $ nom_zone Nom du champ actuel * @return bool | int * / fonction bs_update_post_views ($ value, $ object, $ field_name) if (! $ value ||! is_numeric ($ value)) return;  return update_post_meta ($ object-> ID, $ champ_nom, (int) $ valeur); 
C’est tout pour la modification des réponses du serveur pour les noeuds finaux d’API par défaut. Nous avons à peine effleuré le sujet de la modification de l'API REST, car elle offre beaucoup plus de flexibilité que la simple modification des réponses du serveur. Cela comprend l'ajout de la prise en charge du type de contenu personnalisé via des contrôleurs et des espaces de noms personnalisés, ainsi que l'enregistrement des itinéraires personnalisés pour l'exposition et la modification des données. Nous allons essayer de couvrir ces sujets avancés dans de futurs articles.
Juste le commencement…
Nous concluons ici notre parcours de présentation à l’API WP REST. Dans cette série, nous avons abordé des concepts de base tels que les méthodes d'authentification et la récupération, la création et la mise à jour de données. Dans cette dernière partie de la série, nous avons brièvement examiné les classes internes de l'API WP REST, puis appris à modifier les réponses du serveur pour les noeuds finaux par défaut..
L'objectif de cette série n'a jamais été de couvrir tous les aspects de l'API WP REST. En fait, cela ne peut jamais être réalisé en une seule série. Mais au contraire, le but de cette série était de vous familiariser avec ce nouvel ajout fantastique et de vous encourager à jouer et à expérimenter vous-même. J'espère que vous avez trouvé cette série remplissant son objectif ultime.




		
			
	   
	




Code