WP REST API Intern și personalizare

În partea anterioară a seriei, am aflat despre crearea, actualizarea și ștergerea conținutului de la distanță prin API-ul WP REST. Aceasta ne permite să creăm aplicații independente de platformă, care funcționează perfect cu un back-end de tip WordPress, oferind o experiență bogată utilizatorului.

În partea curentă a seriei, vom examina intervalele WP REST API și modul în care acestea lucrează împreună pentru a acționa API-ul. După aceasta, vom învăța să modificăm răspunsurile serverului pentru ca obiectivele implicite să includă câmpuri personalizate.

Pentru a fi specific, în articolul curent, vom:

aflați despre clasele și metodele interne ale API-ului WP REST
modificați răspunsul serverului pentru obiectivele implicite
aflați cum puteți face câmpurile personalizabile editabile

Deci, haideți să începem să aruncăm o privire asupra internelor API-ului WP REST.

Clasele și metodele interne ale API-ului WP REST

Clasele din API-ul WP REST pot fi împărțite în următoarele două categorii:

Cursuri de infrastructură: Acestea sunt clasele fundamentale responsabile de organizarea API-ului. Nu efectuează transformări de date.
Clase de punct final: Aceste clase sunt responsabile pentru efectuarea operațiunilor CRUD pe resurse precum postări, pagini, utilizatori, comentarii etc..

Să aruncăm o privire la clasele individuale ale fiecăreia dintre cele două categorii de mai sus.

Clasele de infrastructură

Cele trei clase de infrastructură care împreună alimentează API-ul REST sunt următoarele:

WP_REST_Server
WP_REST_Request
WP_REST_Response

WP_REST_Server

Aceasta este clasa de bază a WP REST API care implementează serverul REST înregistrând rute, servind cereri și pregătindu-se răspunsuri. Formează datele care trebuie transmise clientului și în caz de eroare pregătește eroarea prin includerea codului de eroare și a corpului mesajului. De asemenea, verifică autentificarea.

Am lucrat destul de mult cu / Wp-json pentru a verifica toate capabilitățile și rutele suportate pentru un site. Metoda get_index (), care este responsabil pentru recuperarea indexului site-ului, este, de asemenea, situat în această clasă.

Pentru a răspunde solicitărilor și pentru a pregăti răspunsurile, WP_REST_Server clasa utilizează WP_REST_Request și WP_REST_Response clase, respectiv.

WP_REST_Request

WP_REST_Request clasa implementează obiectul cererii pentru WP REST API. Conține datele din cerere ca antetele și corpul de solicitare și este transmisă funcției de apel invers de către WP_REST_Server clasă. De asemenea, verifică dacă parametrii care sunt transmiși de-a lungul cererii sunt valabili și efectuează dezinfecția datelor atunci când este necesar.

WP_REST_Response

WP_REST_Response clasa, așa cum implică și numele, implementează obiectul de răspuns. Acesta conține date necesare, cum ar fi codul de stare a răspunsului și organismul de răspuns.

Să luăm acum o privire la clasele de parametri.

Clasa punctelor finale

Clasele de punct final din WP REST API sunt responsabile pentru efectuarea operațiunilor CRUD. Aceste clase includ WP_REST_Posts_Controller, WP_REST_Taxonomies_Controller, WP_REST_Users_Controller, etc. Toate aceste clase de parametri extinde o singură clasă abstractă WP_REST_Controller care oferă un model consistent pentru modificarea datelor.

WP_REST_Controller clasa include metode cum ar fi get_item (), create_item (), update_item (), Sterge articolul(), etc, pentru efectuarea operațiunilor CRUD. Aceste metode trebuie să fie suprascrise de subclasele prin implementarea abstractizării proprii pentru recuperarea, crearea, actualizarea și modificarea datelor.

Puteți găsi mai multe despre aceste clase și despre metodele lor interne în documentația oficială.

După ce am aflat despre clasele interne ale API-ului WP REST, să aruncăm o privire asupra modului în care putem modifica răspunsurile serverului pentru ca obiectivele implicite să includă câmpuri personalizate.

Modificarea răspunsurilor serverului

În secțiunea anterioară, am analizat clasele și metodele interne pe care se bazează API-ul. Împreună, aceste clase și metode conduc API-ul în ansamblul său și oferă o modalitate dezvoltatorilor de a extinde API-ul pentru a ține cont de diferite scenarii și cazuri de utilizare.

API-ul WP REST expune datele într-un mod previzibil. Acestea includ diverse resurse, cum ar fi postări, mesaje postate, pagini și utilizatori, împreună cu proprietățile lor standard. Dar aceste date nu pot fi întotdeauna conforme nevoilor fiecărui site sau utilizator WordPress. Prin urmare, API-ul WP REST oferă o modalitate de modificare a datelor pe care serverul le întoarce pentru fiecare dintre rutele implicite.

register_rest_field () metoda oferă o modalitate de a adăuga sau de a actualiza câmpurile în răspunsul pentru un obiect. Cu toate acestea, modificarea unui câmp dintr-un răspuns nu este niciodată încurajată de API, deoarece ar putea introduce probleme de compatibilitate pentru clienții care se așteaptă la un răspuns standard de la server. Deci, dacă trebuie să modificați un câmp, trebuie să luați în considerare duplicarea câmpului cu valoarea dorită.

În mod similar, ștergerea unui câmp implicit este extrem de descurajată din cauza faptului că un client îl așteaptă. Dacă aveți nevoie de o submulțime mai mică a răspunsului returnat de server, ar trebui să creați contexte suplimentare în plus față de contextele implicite, cum ar fi vedere sau Editați | ×.

Cu toate acestea, putem adăuga în siguranță un câmp la răspunsul returnat de server pentru unul sau mai multe obiecte. Aceste câmpuri pot conține orice valoare care variază de la meta post sau utilizator la orice altă valoare arbitrară.

În secțiunea următoare, vom colabora cu register_rest_field () metoda de adăugare a câmpurilor personalizate la răspunsul returnat de server pentru post obiect.

Lucrul cu `register_rest_field ()` Metodă

După cum sa menționat anterior, register_rest_field () metoda poate fi utilizată pentru adăugarea sau actualizarea câmpurilor în răspunsul returnat de server. Această metodă acceptă trei argumente:

$ object_type
atribut $
$ args

$ object_type argumentul poate fi un șir sau un matrice care conține numele tuturor obiectelor pentru care vrem să adăugăm câmpul. Aceste obiecte pot fi post, termen, cometariu, utilizator, etc Dacă trebuie să adăugăm un câmp personalizat unui tip de post personalizat, atunci $ object_type argument ar fi numele tipului de post.

atribut $ argument este numele câmpului personalizat. Acest nume ar apărea în răspunsul serverului ca o cheie împreună cu valoarea sa.

$ args array este o matrice asociativă care poate conține următoarele trei chei:

$ get_callback
$ update_callback
$ schemă

Valorile primelor două chei sunt numele metodelor folosite pentru a obține sau actualiza valoarea câmpului personalizat. Ultimul $ schemă cheie definește metoda sau variabila care este utilizată pentru a defini schema pentru câmpul personalizat.

Toate cheile de mai sus sunt opționale, dar dacă nu sunt adăugate, capacitatea nu va fi adăugată. De exemplu, dacă definiți $ get_callback cheie, dar nu și $ update_callback , funcția de recuperare va fi adăugată, dar funcția de actualizare nu va fi adăugată. Dacă omiteți $ get_callback cheie, câmpul nu va fi adăugat la răspuns.

register_rest_field () metoda funcționează prin modificarea $ wp_rest_additional_fields variabil. Această variabilă de câmpuri deține câmpuri înregistrate după tipurile de obiecte care trebuie returnate în răspunsul de către server. Ori de câte ori un câmp este înregistrat de către register_rest_field () metoda, se adaugă la $ wp_rest_additional_fields variabil. Cu toate acestea, modificarea $ wp_rest_additional_fields variabil manual este puternic descurajat.

Adăugarea câmpurilor personalizate la răspuns

După ce ne-am familiarizat cu register_rest_field () , putem modifica acum răspunsul pentru post obiect. Un caz tipic de utilizare ar fi adăugarea unui câmp de nume afișat autor, care este de obicei necesar atunci când se înregistrează postări pe o pagină index. Întrucât răspunsul standard nu include acest câmp, putem folosi register_rest_field () metodă de includere în răspuns.

Începem prin crearea unui plugin simplu. Deci, creați un nou folder numit odihnă-răspuns-modificator în tine / Wp-content / plugins director. Creați un spațiu gol index.php fișier și lipiți în următoarea definiție plugin:

register_rest_field () metoda ar trebui să fie înregistrată în rest_api_init acțiune. Prin urmare, vom crea o funcție numită bs_add_custom_rest_fields () și legați-o la rest_api_init cârlig:

Rețineți că etichetele de deschidere PHP nu sunt necesare aici, dar le-am inclus astfel încât sintaxa să fie evidențiată corect.

În interiorul bs_add_custom_rest_fields () funcția, putem folosi register_rest_field () metoda pentru a include un câmp pentru numele autorului:

bs_add_custom_rest_fields () // schema pentru câmpul bs_author_name $ bs_author_name_schema = array ('description' => 'Numele autorului postului', 'type' => 'string', 'context' => array ); // înregistrarea câmpului 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);

Așa cum am menționat în secțiunea anterioară, primul argument în register_rest_field () metoda este numele obiectului pentru care modificăm răspunsul. Deoarece trebuie să modificăm răspunsul pentru post obiect, trecem la fel ca primul argument.

Al doilea argument din codul de mai sus este numele câmpului care va apărea în răspuns. Este întotdeauna o bună practică de a prefixa numele unui câmp personalizat în răspuns, pentru a vă asigura compatibilitatea maximă față și că nu va fi suprascrisă în viitor de alte pluginuri. Prin urmare, trecem bs_author_name în al doilea argument ca atribut $ din câmpul personalizat.

Al treilea și ultimul argument din codul de mai sus este o matrice pentru metodele de retur și schema. Această matrice deține numele metodelor de retur pentru recuperarea și actualizarea câmpului personalizat în $ get_callback și $ update_callback chei, respectiv. Noi trecem bs_get_author_name funcționează ca metodă de retur de apel invers. Vom defini această funcție în scurt timp.

Pentru $ update_callback cheie, trecem nul deoarece acesta este un câmp numai pentru citire și nu este necesar să actualizăm numele autorului pentru o postare.

Pentru $ schemă cheie, trecem printr-un matrice numită $ bs_author_name_schema. Această matrice deține diferite proprietăți pentru câmp, cum ar fi tipul de date, contextul și descrierea.

Singurul lucru pe care trebuie să-l definim este acum bs_get_author_name () funcție care va acționa ca $ get_callback pentru domeniul nostru personalizat. Mai jos este codul pentru această funcție:

/ ** * Callback pentru preluarea numelui autorului * @param array $ object Obiectul curent post * @param string $ field_name Numele câmpului * @param WP_REST_request $ cerere Cererea curenta * @ retur string Numele autorului * / funcția bs_get_author_name ($ object, $ field_name, $ request) returnează get_the_author_meta ('display_name', $ object ['author']);

$ get_callback metoda primește trei argumente pentru următoarele:

$ obiect: Obiectul curent. În cazul nostru, este postul curent. $ FIELD_NAME: Se adaugă numele câmpului personalizat. cerere $: Obiectul cererii.

Noi folosim $ autor proprietate a $ obiect argument care deține id-ul autorului postului. Și folosind get_the_author_meta () funcția, vom prelua și returna numele afișat al autorului pentru postarea curentă.

Acum, când câmpul este înregistrat, putem trimite un câmp OBȚINE cererea către / Wp / v2 / mesaje pentru a vedea dacă funcționează corect:

Iată răspunsul din Postman:

Acest câmp personalizat nou înregistrat va apărea, de asemenea, în răspunsul la server, împreună cu schema acestuia, atunci când trimitem un mesaj OPȚIUNI cererea către / Wp / v2 / mesaje traseu: Prin urmare, un câmp personalizat pentru proprietatea nume autor a fost înregistrat cu succes. Dar acest câmp este numai pentru citire, deoarece nu îl putem actualiza prin trimiterea unui mesaj POST cerere. În secțiunea următoare, vom înregistra un câmp editabil pentru numărul de afișări postate. Înregistrarea unui câmp editabil Vom înregistra acum un câmp personalizat pentru numărul de vizualizări postare. Ne vom ocupa doar de înregistrarea reală a câmpului cu WP REST API, lăsând implementarea pentru creșterea numărului de numărătoare. Mai jos este codul pentru bs_post_views înregistrarea în câmpuri personalizate împreună cu schema sa: // schema pentru câmpul bs_post_views $ bs_post_views_schema = array ('description' => 'Post count count', 'type' => 'integer', 'context' => array ('view', 'edit')); // înregistrarea câmpului 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_schema); Codul este similar cu cel pe care l-am scris în secțiunea anterioară, cu excepția faptului că include acum o metodă de apel invers bs_update_post_views pentru $ update_callback cheie. Această funcție este responsabilă pentru actualizarea valorii câmpului. $ context proprietate în $ bs_post_views_schema schema array include două valori pentru vedere și Editați | ×. Includerea valorii de editare în $ context argumentul asigură că bs_post_views câmpul este returnat în răspunsul server după ce a fost actualizat. Metodele de preluare și actualizare a apelurilor de apel sunt următoarele: / ** * Callback pentru preluarea numărului de vizualizări postate * @param array $ object Obiectul curent post * * string param $ field_name Numele câmpului * @param WP_REST_request $ request Cererea curenta * @return integer Numar vizualizari numar * / functie bs_get_post_views ($ object, $ field_name, $ request) retur (int) get_post_meta ($ object ['id'], $ field_name, true); / ** * Callback pentru actualizarea numărului de vizualizări ale postărilor * @param mixed $ value Count views views * @param object $ object Obiectul din răspuns * @param string $ field_name Numele câmpului curent * @return bool | int * / funcția bs_update_post_views (valoarea $, $ object, $ field_name) if (! $ value ||! is_numeric ($ value)) return; întoarcere update_post_meta ($ object-> ID, $ field_name, (int) $ value); Codul este destul de simplu pe măsură ce utilizează get_post_meta () și update_post_meta () metodele de recuperare și actualizare a valorilor. bs_get_post_views () metoda primește pentru prima dată valoarea meta pentru bs_post_views cheia meta și o aruncă într-un întreg înainte de ao returna. Metoda de apel invers a intrat $ update_callback primește trei argumente pentru următoarele: valoarea $: Noua valoare pentru câmp. $ obiect: Obiectul curent din răspuns. $ FIELD_NAME: Numele câmpului actualizat. În bs_update_post_views () , verificăm mai întâi dacă valoarea trecută nu este goală și este o valoare numerică. Dacă nu, ne întoarcem fără să facem nimic. Dacă valoarea este numerică, o transmitem către update_post_meta () funcția care o salvează în baza de date după ce a introdus-o într-un număr întreg valid. După ce ați înregistrat câmpul cu succes, să îl testați prin trimiterea unui mesaj OBȚINE cerere: $ GET / wp / v2 / postări Mai jos este un exemplu de răspuns pentru solicitarea de mai sus: După cum putem vedea în imaginea de mai sus, valoarea curentă a bs_post_views câmpul este 0 pentru o anumită postare. Acest lucru se datorează faptului că get_post_meta () metoda returnează un șir gol, deoarece nu a putut găsi o valoare meta pentru bs_post_views cheia meta și turnarea unui șir gol într-un număr întreg în PHP are ca rezultat 0. Putem actualiza bs_post_views prin trimiterea unui mesaj POST cererea către / Wp / v2 / posturi / punct final. Organismul JSON pentru solicitare este după cum urmează: "bs_post_views": 4050 Dacă cererea are succes, serverul returnează a - OK codul de stare împreună cu obiectul obiect actualizat care include și bs_post_views camp: bs_post_views câmpul personalizat este actualizat acum. Rețineți că am trimis un corp JSON de-a lungul cererii pentru actualizarea câmpului. Organismul JSON a inclus numele câmpului-bs_post_views-cu o valoare intreg 4050. Dacă încercăm să trimitem o valoare non-numerică, să zicem „abc1234“, câmpul nu va fi actualizat deoarece avem o verificare a condiției pentru o valoare numerică în bs_update_post_views () metoda de retur. Mai jos este codul sursă complet pentru plugin: 'Numele autorului postului', 'type' => 'string', 'context' => array ('view')); // înregistrarea câmpului 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); // schema pentru câmpul bs_post_views $ bs_post_views_schema = array ('description' => 'Post count count', 'type' => 'integer', 'context' => array ('view', 'edit')); // înregistrarea câmpului 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_schema); / ** * Callback pentru preluarea numelui autorului * @param array $ object Obiectul curent post * @param string $ field_name Numele câmpului * @param WP_REST_request $ request Cererea curenta * @return string Numele autorului * / funcția bs_get_author_name ($ object, $ field_name, $ request) returnează get_the_author_meta ('display_name', $ object ['author']); / ** * Callback pentru preluarea numărului de vizualizări postate * @param array $ object Obiectul curent post * @param string $ field_name Numele câmpului * @param WP_REST_request $ request Cererea curenta * @return integer Numar vizualizari count * / funcția bs_get_post_views ($ object, $ field_name, $ request) retur (int) get_post_meta ($ object ['id'], $ field_name, true); / ** * Callback pentru actualizarea numărului de vizualizări ale postărilor * @param mixed $ value Count views views * @param object $ object Obiectul din răspuns * @param string $ field_name Numele câmpului curent * @return bool | int * / funcția bs_update_post_views (valoarea $, $ object, $ field_name) if (! $ value ||! is_numeric ($ value)) return; întoarcere update_post_meta ($ object-> ID, $ field_name, (int) $ value); Asta e tot pentru modificarea răspunsurilor serverului pentru punctele finale implicite API. Abia am zgâriat suprafața pentru modificarea API-ului REST deoarece oferă o flexibilitate mult mai mare decât modificarea răspunsurilor serverului. Aceasta include adăugarea de suport pentru tipul de conținut particularizat prin controlere personalizate și spații de nume și înregistrarea rutelor personalizate pentru expunerea și modificarea datelor. Vom încerca să acoperim aceste subiecte avansate în articolele viitoare. Doar începutul… Aici încheiem călătoria noastră de a ne introduce pe WP REST API. În această serie am abordat concepte de bază precum metodele de autentificare și recuperarea, crearea și actualizarea datelor. În această ultimă parte a seriei, am analizat pe scurt clasele interne ale WP REST API și apoi am învățat să modificăm răspunsurile serverului pentru obiectivele implicite. Nu a fost niciodată scopul acestei serii de a acoperi fiecare aspect al WP REST API - de fapt, nu poate fi realizat într-o singură serie. Dar, mai degrabă, scopul acestei serii a fost să vă aducem la curent cu acest nou plus fantastic și să vă încurajați să jucați și să experimentați pe cont propriu. Sper că ați găsit această serie îndeplinind obiectivul final. Cod