Laravel rende le interazioni con le API un gioco da ragazzi sia per gli sviluppatori web principianti che per quelli più esperti. Il client HTTP di Laravel è costruito sulla base del client HTTP Guzzle di PHP per offrire agli sviluppatori un’esperienza più fluida durante le richieste HTTP. Le sue caratteristiche principali includono l’autenticazione, il routing e un’efficace mappatura oggetto-relazionale (ORM).

In questo articolo vedremo come utilizzare il client HTTP di Laravel per effettuare richieste, eseguire il debug delle risposte, creare middleware e macro e altro ancora.

Il client HTTP di Laravel fa il lavoro duro per le API

Guzzle è un semplice client HTTP per PHP. Offre funzionalità per diverse richieste di moduli, tra cui GET, POST, PUT e DELETE oltre a funzionalità di streaming e richieste multipart. Con il client HTTP Guzzle è possibile inviare richieste sincrone e asincrone al server. Inoltre, è dotato di un discreto middleware per personalizzare il comportamento del client.

Il client HTTP di Laravel è un wrapper costruito su Guzzle ma con funzionalità aggiuntive. Include il supporto per la ripetizione delle richieste fallite e alcune funzioni di aiuto con i dati JSON. La maggior parte delle funzionalità dei client HTTP di Laravel sono simili a quelle di Guzzle.

Prerequisiti

Nelle sezioni seguenti impareremo a conoscere meglio il client HTTP di Laravel. Per seguirci, avrete bisogno di:

    • Conoscenza di base di Laravel, PHP e delle API
    • PHP e Composer installati
    • Postman

Come fare richieste

Per capire come utilizzare un client HTTP per effettuare una richiesta, potete sfruttare molte API ospitate, come ReqRes.

Iniziate importando il pacchetto HTTP incluso nella creazione dell’applicazione. All’interno del file App/Http/Controllers/UserController.php, aggiungete il seguente codice, a partire dalla dichiarazione use all’inizio del file e il codice rimanente all’interno della funzione index.

use Illuminate\Support\Facades\Http;
return Http::get("https://reqres.in/api/users?page=2");

Nota: per casi d’uso complessi, è anche possibile inviare la richiesta con le intestazioni utilizzando il metodo withHeaders.

Nello stesso file, create un nuovo metodo post utilizzando il codice seguente:

function post()
{
    $response = Http::withHeaders([
        'Content-Type' => 'application/json',
    ])->post('https://reqres.in/api/users', [
        'name' => 'morpheus',
        'job' => 'leader',
    ]);
    return $response;
}

Quindi aggiungete un percorso per questo metodo all’interno del file routes/web.php:

Route::get('post',[UserController::class,'post']);

Ora è possibile utilizzare Postman per testare questa rotta. Aprite Postman e aggiungete http://127.0.0.1:8000/post come URL, con il tipo di richiesta GET. Una volta cliccato su send, vedrete la seguente risposta:

Fare richieste con Postman
Fare richieste con Postman

Richieste simultanee

Le richieste parallele migliorano significativamente le prestazioni, in quanto rendono possibile recuperare più dati nello stesso periodo. Il client HTTP di Laravel permette di effettuare richieste simultanee utilizzando il metodo pool.

All’interno di App/Http/Controllers/UserController.php, aggiungete il seguente codice:

use Illuminate\Http\Client\Pool;
function concurrent()
{
    $responses = Http::pool(fn (Pool $pool) => [
        $pool->get('https://reqres.in/api/users?page=2'),
        $pool->get('https://reqres.in/api/users/2'),
        $pool->get('https://reqres.in/api/users?page=2'),
    ]);

    return $responses[0]->ok() &&
        $responses[1]->ok() &&
        $responses[2]->ok();
}

Quindi, aggiungete la route di supporto all’interno del file routes/web.php.

Route::get('concurrent',[UserController::class,'concurrent']);

Il browser fornisce la seguente risposta quando il percorso viene visitato:

Richieste simultanee
Richieste simultanee

Macro di richiesta

Le macro di richiesta sono utili quando si interagisce con percorsi API comuni.

Per creare la macro, è necessario definirla all’interno del metodo di avvio del file app/Http/Providers/AppServiceProvider.php utilizzando il codice seguente:

use Illuminate\Support\Facades\Http;
Http::macro('reqres', function () {
    return Http::baseUrl('https://reqres.in/api');
});

Nota: assicuratevi di aggiungere l’istruzione use all’inizio del file.

Quindi, utilizzate la macro all’interno del sito UserController aggiungendo il seguente codice:

function macro()
{
    $response = Http::reqres()->get('/users?page=2');
    return $response;
}

Come si può vedere, poiché la macro è già stata creata, non è necessario aggiungere nuovamente l’URL completo.

Infine, aggiungete una route nel file routes/web.php utilizzando il codice seguente:

Route::get('macro',[UserController::class,'macro']);
Richiesta macro
Richiesta macro

Come decodificare le risposte

Per decodificare una risposta e assicurarsi che una richiesta API sia andata a buon fine, utilizzate il metodo status incluso nel client. Questo metodo ottiene il codice di stato inviato dal server e lo visualizza.

Per verificarlo, sostituite il codice della macro precedente con il codice seguente all’interno del file App/Http/Controllers/UserController.php:

function macro()
{
    $response = Http::reqres()->get('/users?page=2');
    return $response->status();
}

In questo caso, il codice di stato 200 significa che la richiesta è andata a buon fine.

Risposta di decodifica avvenuta con successo
Risposta di decodifica avvenuta con successo

Come testare le API JSON

Laravel dispone di diversi helper per testare le API JSON e le loro risposte. Le funzioni di aiuto includono json, getJson, postJson, putJson, patchJson, deleteJson e così via.

Per capire meglio i test, create uno scenario di prova per il percorso dell’utente GET. Il test di esempio esiste già quando avviate l’applicazione Laravel. All’interno del file tests/Feature/ExampleTest.php, sostituite il codice esistente con il seguente:

<?php
namespace Tests\Feature;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Tests\TestCase;
class ExampleTest extends TestCase
{
    /**
     * A basic test example.
     *
     * @return void
     */
    public function test_example()
    {
        $response = $this->getJson('/users');

        $response->assertStatus(200);
    }
}

Il codice aggiunto recupera i dati JSON nel percorso dell’utente e controlla se il codice di stato è 200 o meno.

Una volta aggiunto il codice di prova, eseguite il seguente comando nel terminale per effettuare i test:

./vendor/bin/phpunit

Una volta completati i test, vedrete che sono stati eseguiti due test, entrambi con esito positivo.

Testare le API JSON
Testare le API JSON

Allo stesso modo, è possibile verificare diversi tipi di richieste e utilizzare altri metodi di aiuto per effettuare test più sofisticati.

Come gestire gli eventi

Laravel offre tre eventi da lanciare quando si tratta di richieste HTTP.

  • RequestSending, che si verifica prima dell’invio della richiesta.
  • ResponseReceived, quando viene ricevuta una risposta.
  • ConnectionFailed, che si verifica quando non viene ricevuta alcuna risposta.

Tutti e tre gli eventi includono la proprietà $request per ispezionare l’istanza Illuminate\Http\Client\Request e ResponseReceived ha un ulteriore $response property. Questi sono particolarmente utili per eseguire azioni dopo un evento. Ad esempio, potreste voler inviare un’email dopo aver ricevuto una risposta positiva.

Per creare un evento e un listener, andate al file app/Providers/EventServiceProvider.php e sostituite l’array listen con il seguente codice.

protected $listen = [
    Registered::class => [
        SendEmailVerificationNotification::class,
    ],
    'Illuminate\Http\Client\Events\ResponseReceived' => [
        'App\Listeners\LogResponseReceived',
    ],
];

Quindi eseguite il seguente comando nel terminale:

php artisan event:generate

Il comando precedente creerà il listener app/Listeners/LogResponseReceived.php. Sostituite il codice di questo file con il codice seguente:

<?php
namespace App\Listeners;
use Illuminate\Http\Client\Events\ResponseReceived;
use Illuminate\Http\Request;
use Illuminate\Http\Response;
use Illuminate\Support\Facades\Log;
class LogResponseReceived
{
    /**
     * Create the event listener.
     *
     * @return void
     */
    public function __construct(Request $request, Response $response)
    {
        Log::channel('stderr')->info($response->status());
    }

    /**
     * Handle the event.
     *
     * @param  \Illuminate\Http\Client\Events\ResponseReceived  $event
     * @return void
     */
    public function handle(ResponseReceived $event)
    {
        
    }
}

Il log informativo del codice di stato viene stampato nel terminale.

Log del terminale che mostra il codice di stato
Log del terminale che mostra il codice di stato

Riepilogo

Che un sito o un’applicazione web siano realizzati da un’organizzazione o da uno sviluppatore indipendente, le API sono fondamentali per il loro successo. Tuttavia, utilizzarle può essere difficile.

Molti framework e librerie promettono di semplificare questo processo, ma Laravel si distingue per la sua attenzione alla semplicità e all’intuitività. Il suo client integrato supporta chiamate API semplici, chiamate API simultanee, macro API, metodi di aiuto per API basate su JSON e molto altro.

Steve Bonisteel Kinsta

Steve Bonisteel è un Technical Editor di Kinsta che ha iniziato la sua carriera di scrittore come giornalista della carta stampata, inseguendo ambulanze e camion dei pompieri. Dalla fine degli anni '90 si occupa di tecnologia legata a Internet.