Documentazione response http

Questo pacchetto è compatibile con Simfony, Laravel, Lumen, e PHP >=7.2

Si basa su una delle libreria più utilizzate in php ovvero http-foundation. Sono state implementate funzioni aggiuntive per la gestione delle risposte, permettendo al server, di gestire in modo facile ed efficiente:

• Risposte standard HTTP/1.1 con codice e content già di default
• Manipolare il content in modo dinamico e prestante (anche con standard REST)
• Aggiungere al content i link della risposta con standard HATEOAS
• Manipolare facilmente gli headers
• Generare facilmente etag(con un playload code.key.date codificato in base64)
• Gestire le conditional request confrontandole con la risposta
• (Laravel / Lumen) Trait da aggiungere ai modelli per mappare i links della risorsa

Utilizzo

Creazione oggetto risposta

use Ksmosx\Response\RestResponse;

//Costruttore
$response = new RestResponse('Content', 200, array('content-type' => 'text/html'));

//Utilizzando la factory, success 201
$responseFactory = new FactoryResponse();
return $responseFactory->success('Content');

FactoryResponse implementata le risposte http standard utilizzando RestResponse, i metodi a disposizione sono presenti nell'interfaccia FactoryInterface.php

Metodi a disposizione per la gestione della creazione della risposta e del suo oggetto

$response->withContent()  //Aggiunge al content un elemento key:value
->withContents() //Aggiunge al content elementi  
->withLink()     //Aggiunge al content 'links':value con standard HATEOAS di default
->withLinks()    //Aggiunge al content più value nell'elemto 'links' (override disattivato di default)
->withHeader()   //Aggiunge un nuovo header alla risposta 
->withHeaders()  //Aggiunge nuovi headers alla risposta
->withData()     //Alias withContent per l'inserimento nel content 'data':value

Le funzioni sovrastanti sono implementate nella classe RestResponse.php

Proprieta $metadata è un array contente dei valori descrittivi della risposta, essi possono rappresentare e descrivere la risposta, questo può essere utile per risposte in cache o quando vengono serializzate e messe in coda per poi essere usate in altri servizi. ->setProperty() //Recupera la proprietà della risposta (puoi anche recuperare solo una o più key)

 ->getProperty()

Inoltre è possibile recuperare il $content della risposta oppure la proprietà $data

 //Recupera la proprietà content della classe HttpFoundation\Response (puoi anche recuperare solo una o più key)
 ->getContent()

 //Recupera la proprietà data della classe HttpFoundation\JsonResponse (puoi anche recuperare solo una o più key)
 ->getData()

Gestione delle Eccezzioni

Per catturare le eccezioni e restituire una risposta di errore coerente e corretta al client, puoi utilizzare la classe Kosmosx\Response\Exception\Handler, che gestisce le eccezioni e restituisce una risposta json al client

 //Laravel or Lumen
 $this->app->singleton(
    \Illuminate\Contracts\Debug\ExceptionHandler::class,
    \Kosmosx\Response\Laravel\Exceptions\Handler::class
 )
 
 //PHP
 try {
    (new \Kosmosx\Response\Exceptions\Handler())->setExceptionHandler()
 } catch (\Exception $e) {
    //
 }
 
 //RESPONSE
 {
    'error': {
       'message': message value of exception,
       'code': code value of exception,
       'status_code': 4xx,
       'debug': {
          'file': ...,
          'line': ...,
          'trace': ...,    
    }
 }
*l'elemnto debug verrà incluso solo se nel file .env il valore di RESPONSE_DEBUG sarà true.
**l'elemnto status_code verrà incluso solo se l'eccezione è di tipo HttpException, inoltre verranno aggiunti alla risposta anche gli headers dell'eccezione

Classe ErrorsException permette di gesitere le eccezioni implementando metodi per la costruzione del messaggio e altro. È inoltre possibile utilizzare questa classe per estendere le vostre eccezioni ErrorsException.php

Response personalizzata

Per creare una propria classe risposta, con metodi e funzioni personalizzate, vi basta creare una nuova classe

namespace ...;

use Kosmosx\Response\RestResponse; 

class MyResponse extends RestResponse { 
    //your method 
}

Esempi

$users = User::all();  //ex. with laravel
return (new RestResponse())->withData($users);
//or
return (new FactoryResponse())->successData($users);

{ 'data': { {'id':1,'name':'test} {'id':2,'name':'test2}
{'id':N,'name':'testN}
} }

return new RestResponse(['errors'=>'Error Bad Request'],400);
//or
return (new FactoryResponse())->badRequest('Error Bad Request');

{
   'errors': 'Error Bad Request'
}