API WP REST Internals e personalizzazione

Nella parte precedente della serie, abbiamo imparato a creare, aggiornare ed eliminare i contenuti in remoto tramite l'API WP REST. Ci consente di creare applicazioni indipendenti dalla piattaforma che funzionano perfettamente con un back-end potenziato da WordPress, offrendo all'utente un'esperienza ricca.

Nell'attuale parte della serie, daremo un'occhiata agli interni dell'API REST di WP e al modo in cui lavorano insieme per alimentare l'API. Dopodiché, impareremo a modificare le risposte del server per gli endpoint predefiniti per includere campi personalizzati.

Per essere precisi, nel presente articolo, dovremo:

scopri le classi e i metodi interni dell'API REST di WP
modificare la risposta del server per gli endpoint predefiniti
impara come rendere modificabili i campi personalizzati

Iniziamo dando uno sguardo ai componenti interni dell'API REST di WP.

Classi e metodi interni dell'API REST di WP

Le classi nell'API REST di WP possono essere suddivise nelle seguenti due categorie:

Classi di infrastrutture: Queste sono le classi fondamentali responsabili della condivisione dell'API. Non eseguono alcuna trasformazione dei dati.
Classi di endpoint: Queste classi sono responsabili dell'esecuzione di operazioni CRUD su risorse come post, pagine, utenti, commenti, ecc.

Diamo un'occhiata alle singole classi di ciascuna delle due precedenti categorie.

Classi di infrastrutture

Le tre classi di infrastruttura che insieme alimentano l'API REST sono le seguenti:

WP_REST_Server
WP_REST_Request
WP_REST_Response

WP_REST_Server

Questa è la classe principale dell'API REST di WP che implementa il server REST registrando i percorsi, servendo le richieste e preparando le risposte. Formatta i dati da trasmettere al client e, in caso di errore, prepara l'errore includendo il codice di errore e il corpo del messaggio. Controlla anche l'autenticazione.

Abbiamo lavorato parecchio con il / Wp-JSON indice endpoint per il controllo di tutte le funzionalità e percorsi supportati per un sito. Il metodo get_index (), che è responsabile per il recupero dell'indice del sito, si trova anche in questa classe.

Per servire le richieste e preparare le risposte, il WP_REST_Server la classe usa il WP_REST_Request e WP_REST_Response classi rispettivamente.

WP_REST_Request

Il WP_REST_Request class implementa l'oggetto request per l'API REST di WP. Contiene dati dalla richiesta come intestazioni e corpo della richiesta e viene passato alla funzione di callback da WP_REST_Server classe. Controlla inoltre se i parametri trasmessi lungo la richiesta sono validi ed esegue la sanitizzazione dei dati quando necessario.

WP_REST_Response

Il WP_REST_Response classe, come suggerisce il nome, implementa l'oggetto risposta. Contiene i dati necessari come il codice di stato della risposta e il corpo della risposta.

Diamo ora un'occhiata alle classi endpoint.

Classi di endpoint

Le classi endpoint nell'API REST di WP sono responsabili dell'esecuzione delle operazioni CRUD. Queste classi includono WP_REST_Posts_Controller, WP_REST_Taxonomies_Controller, WP_REST_Users_Controller, ecc. Tutte queste classi di endpoint estendono una singola classe astratta WP_REST_Controller che fornisce un modello coerente per la modifica dei dati.

Il WP_REST_Controller la classe include metodi come get_Item (), create_item (), update_item (), cancellare l'oggetto(), ecc., per l'esecuzione di operazioni CRUD. Questi metodi devono essere sovrascritti dalle sottoclassi implementando la propria astrazione per il recupero, la creazione, l'aggiornamento e la modifica dei dati.

Puoi trovare ulteriori informazioni su queste classi e i loro metodi interni nella documentazione ufficiale.

Dopo aver appreso le classi interne dell'API REST di WP, diamo un'occhiata a come possiamo modificare le risposte del server per endpoint predefiniti per includere campi personalizzati.

Modifica delle risposte del server

Nella sezione precedente, abbiamo esaminato le classi e i metodi interni su cui è basata l'API. Insieme, queste classi e questi metodi guidano l'API nel suo complesso e forniscono agli sviluppatori un modo per estendere l'API per tenere conto di diversi scenari e casi d'uso.

L'API WP REST espone i dati in modo prevedibile. Questo include varie risorse come post, post meta, pagine e utenti, insieme alle loro proprietà standard. Ma questi dati non possono sempre essere conformi alle esigenze di ogni singolo sito o utente WordPress. Pertanto, l'API WP REST fornisce un modo per modificare i dati restituiti dal server per ciascuna delle route predefinite.

Il register_rest_field () metodo fornisce un modo per aggiungere o aggiornare campi nella risposta per un oggetto. Tuttavia, la modifica di un campo da una risposta non viene mai incoraggiata dall'API poiché potrebbe introdurre problemi di compatibilità per i client che si aspettano una risposta standard dal server. Quindi, se hai bisogno di cambiare un campo, dovresti considerare di duplicare il campo con il valore desiderato.

Allo stesso modo, l'eliminazione di un campo predefinito è fortemente scoraggiata per il motivo che un cliente potrebbe aspettarselo. Se è necessario un sottoinsieme più piccolo della risposta restituita dal server, è necessario creare contesti aggiuntivi oltre ai contesti predefiniti come vista o modificare.

Tuttavia, possiamo tranquillamente aggiungere un campo alla risposta restituita dal server per uno o più oggetti. Questi campi possono contenere qualsiasi valore che varia da post o meta dell'utente a qualsiasi altro valore arbitrario.

Nella prossima sezione, lavoreremo con il register_rest_field () metodo per aggiungere campi personalizzati alla risposta restituita dal server per il inviare oggetto.

Lavorare con il `register_rest_field ()` Metodo

Come accennato in precedenza, il register_rest_field () metodo può essere utilizzato per aggiungere o aggiornare campi nella risposta restituita dal server. Questo metodo accetta tre argomenti:

$ object_type
$ attributo
$ args

Il $ object_type argomento può essere una stringa o una matrice contenente i nomi di tutti gli oggetti per i quali vogliamo aggiungere il campo. Questi oggetti possono essere inviare, termine, commento, utente, ecc. Se abbiamo bisogno di aggiungere un campo personalizzato a un tipo di messaggio personalizzato, allora il $ object_type argomento sarebbe il nome del tipo di messaggio.

Il $ attributo argomento è il nome del campo personalizzato. Questo nome apparirebbe nella risposta del server come una chiave insieme al suo valore.

Il $ args array è un array associativo che può contenere le seguenti tre chiavi:

$ get_callback
$ update_callback
$ schema

I valori delle prime due chiavi sono i nomi dei metodi utilizzati per ottenere o aggiornare il valore del campo personalizzato. L'ultimo $ schema chiave definisce il metodo o la variabile che viene utilizzata per definire lo schema per il campo personalizzato.

Tutte le chiavi precedenti sono opzionali, ma se non vengono aggiunte, la funzionalità non verrà aggiunta. Ad esempio, se si definisce il $ get_callback chiave ma non il $ update_callback chiave, la funzionalità di recupero verrà aggiunta ma la funzionalità di aggiornamento non verrà aggiunta. Se ometti il $ get_callback chiave, il campo non verrà aggiunto alla risposta.

Il register_rest_field () metodo funziona modificando il $ wp_rest_additional_fields variabile. Questa variabile di matrice mantiene i campi registrati per tipi di oggetto da restituire nella risposta dal server. Ogni volta che un campo è registrato dal register_rest_field () metodo, viene aggiunto al $ wp_rest_additional_fields variabile. Tuttavia, modificando il $ wp_rest_additional_fields variabile manualmente è fortemente scoraggiata.

Aggiunta di campi personalizzati alla risposta

Avendo familiarizzato con il register_rest_field () metodo, ora possiamo modificare la risposta per inviare oggetto. Un tipico caso d'uso qui sarebbe l'aggiunta di un campo del nome di visualizzazione dell'autore, che è comunemente necessario quando si elencano i post in una pagina indice. Poiché la risposta standard non include questo campo, possiamo usare il register_rest_field () metodo per includerlo nella risposta.

Iniziamo creando un semplice plug-in. Quindi crea una nuova cartella chiamata resto-risposta-modificatore nel tuo / Wp-content / plugins directory. Crea un vuoto index.php file e incolla nella seguente definizione di plugin:

Il register_rest_field () il metodo dovrebbe essere registrato nel rest_api_init azione. Quindi, creiamo una funzione chiamata bs_add_custom_rest_fields () e legalo al rest_api_init gancio:
Si noti che i tag PHP di apertura  non sono richiesti qui, ma li ho inclusi in modo che la sintassi sia evidenziata correttamente.
Dentro il bs_add_custom_rest_fields () funzione, possiamo usare il register_rest_field () metodo per includere un campo per il nome dell'autore:
function bs_add_custom_rest_fields () // schema per il campo bs_author_name $ bs_author_name_schema = array ('description' => 'Nome dell'autore del post', 'tipo' => 'stringa', 'contesto' => array ('vista') ); // registrando il campo 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)); 
Come menzionato nella sezione precedente, il primo argomento nel register_rest_field () metodo è il nome dell'oggetto per il quale stiamo modificando la risposta. Dal momento che abbiamo bisogno di modificare la risposta per il inviare oggetto, passiamo lo stesso del primo argomento.
Il secondo argomento nel codice precedente è il nome del campo che apparirà nella risposta. È sempre buona norma anteporre il nome di un campo personalizzato nella risposta per garantire la massima compatibilità diretta e che non venga sovrascritto in futuro da altri plug-in. Quindi, passiamo bs_author_name nel secondo argomento come il $ attributo del campo personalizzato.
Il terzo e ultimo argomento nel codice precedente è un array per i metodi di callback e lo schema. Questo array contiene il nome dei metodi di callback per il recupero e l'aggiornamento del campo personalizzato in $ get_callback e $ update_callback tasti rispettivamente. Noi passiamo il bs_get_author_name funziona come il metodo di richiamata di recupero. Definiremo questa funzione a breve.
Per il $ update_callback chiave, passiamo nullo poiché questo è un campo di sola lettura e non è necessario aggiornare il nome dell'autore per un post.
Per il $ schema chiave, passiamo un array chiamato $ bs_author_name_schema. Questo array contiene varie proprietà per il campo come il tipo di dati, il contesto e la descrizione.
L'unica cosa che dobbiamo definire ora è la bs_get_author_name () funzione che agirà come il $ get_callback metodo per il nostro campo personalizzato. Di seguito è riportato il codice per questa funzione:
/ ** * Richiamata per il recupero del nome dell'autore * @param array $ oggetto L'oggetto post corrente * @param stringa $ campo_name Il nome del campo * @param WP_REST_request $ richiesta La richiesta corrente * @return stringa Il nome dell'autore * / function bs_get_author_name ($ object, $ field_name, $ request) return get_the_author_meta ('display_name', $ object ['author']); 
Il $ get_callback il metodo riceve tre argomenti per quanto segue:
  $ oggetto: L'oggetto corrente. Nel nostro caso, è il post corrente.
  $ field_name: Il nome del campo personalizzato da aggiungere.
  $ request: L'oggetto richiesta.
 
Stiamo usando il $ autore proprietà del $ oggetto argomento che contiene l'id dell'autore del post. E usando il get_the_author_meta () funzione, recuperiamo e restituiamo il nome visualizzato dell'autore per il post corrente.
Ora che il campo è registrato, possiamo inviare un OTTENERE richiesta al / WP / V2 / messaggi percorso per vedere se funziona correttamente:
Ecco la risposta in Postman:
Questo campo personalizzato appena registrato apparirà anche nella risposta del server, insieme al suo schema, quando inviamo un OPZIONI richiesta al / WP / V2 / messaggi itinerario:
Quindi un campo personalizzato per la proprietà del nome dell'autore è stato registrato con successo. Ma questo campo è di sola lettura poiché non possiamo aggiornarlo inviando un INVIARE richiesta. Nella sezione seguente, registreremo un campo modificabile per il conteggio delle visualizzazioni dei post.
Registrazione di un campo modificabile
Ora registreremo un campo personalizzato per il conteggio delle visualizzazioni dei post. Ci occuperemo solo della registrazione effettiva del campo con l'API WP REST, tralasciando l'implementazione per l'incremento del numero di conteggio.
Di seguito è riportato il codice per bs_post_views registrazione del campo personalizzata insieme al suo schema:
// schema per il campo bs_post_views $ bs_post_views_schema = array ('description' => 'Post views count', 'type' => 'integer', 'context' => array ('view', 'edit')); // registrando il campo 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));
Il codice è simile a quello che abbiamo scritto nella sezione precedente, tranne per il fatto che ora include un metodo di callback bs_update_post_views per il $ update_callback chiave. Questa funzione è responsabile dell'aggiornamento del valore del campo.
Il $ contesto proprietà nel $ bs_post_views_schema lo schema array include due valori per vista e modificare. Inclusione del valore di modifica nel file $ contesto argomento assicura che il bs_post_views il campo viene restituito nella risposta del server dopo che è stato aggiornato.
I metodi di richiamo di recupero e aggiornamento sono i seguenti:
/ ** * La richiamata per il recupero delle visualizzazioni post conta * @param array $ oggetto L'oggetto post corrente * @param stringa $ nome_campo Il nome del campo * @param WP_REST_request $ richiesta La richiesta corrente * @return intero Conteggio visualizzazioni post * / funzione bs_get_post_views ($ object, $ field_name, $ request) return (int) get_post_meta ($ object ['id'], $ field_name, true);  / ** * Richiamata per l'aggiornamento delle visualizzazioni post conteggio * @param mixed $ value Post visualizzazioni count * @param object $ oggetto L'oggetto dalla risposta * @param stringa $ field_name Nome del campo corrente * @return bool | int * / function bs_update_post_views ($ value, $ object, $ field_name) if (! $ valore ||! is_numeric ($ value)) return;  return_post_meta return ($ object-> ID, $ field_name, (int) $ value); 
Il codice è piuttosto semplice in quanto utilizza il get_post_meta () e update_post_meta () metodi per recuperare e aggiornare i valori rispettivamente.
Il bs_get_post_views () metodo recupera prima il valore meta per il bs_post_views meta key e lo inserisce in un intero prima di restituirlo.
Il metodo di callback è passato $ update_callback riceve tre argomenti per quanto segue:
  $ value: Il nuovo valore per il campo.
  $ oggetto: Oggetto corrente dalla risposta.
  $ field_name: Il nome del campo che si sta aggiornando.
 
Nel bs_update_post_views () metodo, per prima cosa controlliamo se il valore che viene passato non è vuoto ed è un valore numerico. Altrimenti, torniamo senza fare nulla.
Se il valore è numerico, passiamo a update_post_meta () funzione che lo salva nel database dopo averlo inserito in un numero intero valido.
Dopo aver registrato il campo con successo, proviamo inviando un OTTENERE richiesta:
$ GET / wp / v2 / posts
Di seguito è riportata una risposta di esempio per la richiesta precedente:
Come possiamo vedere nell'immagine sopra, il valore corrente di bs_post_views il campo è 0 per un determinato post. Questo perché il get_post_meta () il metodo restituisce una stringa vuota poiché non è stato possibile trovare un valore meta per il file bs_post_views meta key e type-casting una stringa vuota in un intero in PHP risulta in 0.
Possiamo aggiornare il bs_post_views campo inviando un INVIARE richiesta al / WP / V2 / messaggi / endpoint. Il corpo JSON per la richiesta è il seguente:
"bs_post_views": 4050
Se la richiesta ha esito positivo, il server restituisce a 200 - OK codice di stato insieme all'oggetto post aggiornato che include anche il bs_post_views campo:
Il bs_post_views il campo personalizzato è ora aggiornato.
Si noti che abbiamo inviato un corpo JSON lungo la richiesta per aggiornare il campo. Il corpo JSON includeva il nome del campo-bs_post_views-con un valore intero di 4050. Se proviamo a inviare un valore non numerico, diciamo “abc1234”, il campo non verrà aggiornato poiché abbiamo una condizione che verifica un valore numerico nel file bs_update_post_views () metodo di callback.
Di seguito è riportato il codice sorgente completo per il plug-in:
 'Nome dell'autore del post', 'tipo' => 'stringa', 'contesto' => array ('vista')); // registrando il campo 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 per il campo bs_post_views $ bs_post_views_schema = array ('description' => 'Post views count', 'type' => 'integer', 'context' => array ('view', 'edit')); // registrando il campo 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));  / ** * Richiamata per il recupero del nome dell'autore * @param array $ oggetto L'oggetto post corrente * @param stringa $ campo_name Il nome del campo * @param WP_REST_request $ richiesta La richiesta corrente * @return stringa Il nome dell'autore * / function bs_get_author_name ($ object, $ field_name, $ request) return get_the_author_meta ('display_name', $ object ['author']);  / ** * La richiamata per il recupero delle visualizzazioni post è conteggiata * @param array $ oggetto L'oggetto corrente corrente * @param stringa $ campo_name Il nome del campo * @param WP_REST_request $ richiesta La richiesta corrente * @return intero Conteggio visualizzazioni post * / function bs_get_post_views ($ object, $ field_name, $ request) return (int) get_post_meta ($ object ['id'], $ field_name, true);  / ** * Richiamata per l'aggiornamento delle visualizzazioni post conteggio * @param mixed $ value Post visualizzazioni count * @param object $ oggetto L'oggetto dalla risposta * @param stringa $ field_name Nome del campo corrente * @return bool | int * / function bs_update_post_views ($ value, $ object, $ field_name) if (! $ valore ||! is_numeric ($ value)) return;  return_post_meta return ($ object-> ID, $ field_name, (int) $ value); 
Questo è tutto per la modifica delle risposte del server per gli endpoint API predefiniti. Abbiamo appena scalfito la superficie per la modifica dell'API REST poiché offre molta più flessibilità rispetto alla semplice modifica delle risposte del server. Ciò include l'aggiunta del supporto per il tipo di contenuto personalizzato tramite controller personalizzati e spazi dei nomi e la registrazione di percorsi personalizzati per l'esposizione e la modifica dei dati. Cercheremo di coprire questi argomenti avanzati in futuri articoli.
Solo l'inizio…
Qui concludiamo il nostro viaggio per presentarci all'API REST di WP. In questa serie, abbiamo trattato concetti di base come i metodi di autenticazione e il recupero, la creazione e l'aggiornamento dei dati. In quest'ultima parte della serie, abbiamo esaminato brevemente le classi interne dell'API REST di WP e poi abbiamo imparato a modificare le risposte del server per gli endpoint predefiniti.
Non è mai stato lo scopo di questa serie coprire ogni aspetto dell'API REST di WP, infatti non può mai essere raggiunto in una singola serie. Piuttosto, lo scopo di questa serie era quello di farti diventare operativo con questa nuova fantastica aggiunta e di incoraggiarti a giocare e sperimentare da solo. Spero che tu abbia trovato questa serie che soddisfa il suo obiettivo finale.




		
			
	   
	




Codice