Client PHP

GraphQL nasce nell'ambito dello sviluppo web, quindi non stupisce che anche per il linguaggio PHP (molto usato dal lato server) esistano librerie
per interagire con questo tipo di servizi. Ne analizziamo una in questa lezione, sfruttandola per dialogare con il servizio di prova
che abbiamo realizzato nel corso della guida. Prendiamo in esame Softonic GraphQL Client e proviamo con
esempi eseguibili anche da riga di comando.

Installazione

Possiamo installare il client PHP sfruttando Composer, il più famoso package manager
per le applicazioni PHP. Questo il comando:

$ composer require softonic/graphql-client

Al termine dell'esecuzione di tale comando, sarà installata la libreria richiesta e le relative dipendenze nella cartella corrente. Il tutto sarà collocato - come di consueto
con Composer - nella cartella vendor, in cui troveremo il file autoload.php. Importando quest'ultimo potremo usare la libreria
nei nostri script:

<?php
	require_once('vendor/autoload.php');
	...
	...
?>

La prima query

Il nostro servizio di prova è una banca dati di proverbi la cui query più immediata permette di richiedere un proverbio a caso tra quelli disponibili:

query{
  proverbioRandom
}

Con essa verrà risposto qualcosa di simile a questo:

{
  "data": {
    "proverbioRandom": "Tra moglie e marito non mettere il dito"
  }
}

Con Softonic GraphQL Client possiamo attuarla via codice seguendo questi passaggi:

• impostazione del client in cui forniremo l'indirizzo del servizio GraphQL da contattare;
• definizione del comando GraphQL che vogliamo sviluppare, ad esempio la query vista poco fa;
• inoltro della query e recupero dei risultati.

Otterremo un oggetto di classe Response (interna a Softonic GraphQL Client) che conterrà sia i dati forniti sia eventuali messaggi di errore.
Ecco un esempio:

// creazione dell'oggetto client
$client = \Softonic\GraphQL\ClientBuilder::build('http://localhost:8888/proverbi');
// definizione di una query come stringa multiriga
$query = <<<'QUERY'
query{
  proverbioRandom
}
QUERY;
// invocazione del client per eseguire la query
$response = $client->query($query);
// estrazione del risultato
$proverbioCasuale=$response->getData()['proverbioRandom'];

Si noti che sull'oggetto di classe Response abbiamo invocato il metodo getData, che estrae i risultati sotto forma di array in modo che in PHP il risultato sia più gestibile. Ogni elemento è etichettato con il nome della proprietà fornita.
Ad esempio, nel nostro caso la query restituisce un proverbio casuale nella proprietà proverbioCasuale e questo sarà il nome anche della chiave dell'array PHP.

Oltre a getData, la classe Response comprende anche getErrors che restituisce la porzione di risposta GraphQL che include eventuali errori. Anche getErrors produce un array come risultato. Per sapere a priori se si sono verificati errori si può anche richiamare il metodo hasErrors che restituisce un valore booleano: vero se si sono verificati errori, falso altrimenti.

Richieste con parametri

Le richieste possono essere personalizzate con dei parametri, un po' come le normali chiamate di funzione. Il servizio di prova, ad esempio, offre una query che riceve in input un numero intero che specifica quanti proverbi dell'elenco devono essere restituiti. Se chiediamo:

query{
  proverbi(quanti: 5)
}

otteniamo:

{
  "data": {
    "proverbi": [
      "Gallina vecchia fa buon brodo",
      "Il mattino ha l'oro in bocca",
      "Tra moglie e marito non mettere il dito",
      "Una mela al giorno toglie il medico di torno",
      "Ai pazzi si dà sempre ragione"
    ]
  }
}

Per replicare ciò con la libreria PHP, possiamo costruire uno script del genere:

// definiamo la query da svolgere
$query = <<<'QUERY'
query($quanti: Int){
  proverbi(quanti:$quanti)
}
QUERY;
// specifichiamo il valore che dovrà assumere il parametro impiegato
$param = [
    'quanti'=> 5
];
// esecuzione della query passando i parametri come secondo argomento
$response = $client->query($query, $param);
// estriamo l'elenco di proverbi dal risultato
$elencoProverbi=$response->getData()['proverbi'];
// stampa del risultato
echo $elencoProverbi[0]

L'esecuzione produrrà la frase seguente:

Gallina vecchia fa buon brodo

Si noti che le variabili coinvolte nella query GraphQL sono state prima dichiarate in query($quanti: Int) e solo successivamente utilizzate nel
corpo della query: proverbi(quanti:$quanti). I valori attuali da utilizzare nella query sono stati definiti nell'array $param e poi coinvolti nell'esecuzione
come secondo argomento del metodo query, $client->query($query, $param).

Mutation

Una mutation può essere inviata in maniera analoga a quanto visto. Quella a disposizione del sistema di prova permette l'inserimento di un nuovo proverbio nella banca dati:

mutation{
  nuovo(nuovo:"Chi la fa l'aspetti")
}

e restituisce il numero aggiornato di frasi presenti nel sistema:

{
  "data": {
    "nuovo": 11
  }
}

Nell'esempio che segue, la mettiamo alla prova coniugandola con le query viste nei paragrafi precedenti. Non faremo altro che cambiare il testo del comando da eseguire passando però i parametri nella medesima maniera:

// definiamo la mutation
$mutation = <<<'MUTATION'
mutation($nuovo: String){
  nuovo(nuovo:$nuovo)
}
MUTATION;
// parametri da passare come argomenti
$param = [
    'nuovo'=> "Chi la fa l'aspetti"
];
// esecuzione del comando
$response = $client->query($mutation, $param);
// messaggio di notifica con la nuova dimensione
echo "Ora i proverbi nel database sono ".$response->getData()["nuovo"].PHP_EOL;
// la query che richiederà i proverbi
$query = <<<'QUERY'
query($quanti: Int){
  proverbi(quanti:$quanti)
}
QUERY;
// specifichiamo un argomento che rispecchia il numero reale di proverbi
$param = [
    'quanti'=> $response->getData()["nuovo"]
];
$response = $client->query($query, $param);
// ciclo che stampa tutti i proverbi estratti
foreach ($response->getData()['proverbi'] as $proverbio)
	echo $proverbio.PHP_EOL;

L'output sarà il seguente:

Ora i proverbi nel database sono 10
Gallina vecchia fa buon brodo
Il mattino ha l'oro in bocca
Tra moglie e marito non mettere il dito
Una mela al giorno toglie il medico di torno
Ai pazzi si dà sempre ragione
Anno nuovo vita nuova
Bacco, tabacco e Venere riducon l'uomo in cenere
Battere il ferro finché è caldo
Buon sangue non mente
Chi la fa l'aspetti

Il valore che indica il numero di proverbi aggiornato è contenuto a sua volta in un array pertanto va recuperato con l'espressione $response->getData()["nuovo"].
Qualora si fosse in difficoltà con l'individuazione della struttura interna della risposta si può ricorrere alla funzione var_dump che fornirà un output illuminante:

object(Softonic\GraphQL\Response)#33 (2) {
  ["data":"Softonic\GraphQL\Response":private]=>
  array(1) {
    ["nuovo"]=>
    int(10)
  }
  ["errors":"Softonic\GraphQL\Response":private]=>
  array(0) {
  }
}

Questo è, ad esempio, il var_dump eseguito sulla risposta della mutation. Come si vede vengono indicati i tipi di dato dei singoli elementi nonché la dimensione degli array presenti.