Como usar o cliente interno do Laravel para interagir com APIs externas

O Laravel torna as interações de API muito fáceis para desenvolvedores web novos e experientes. O cliente HTTP Larvel é construído sobre o cliente HTTP Guzzle do PHP para oferecer aos desenvolvedores uma experiência mais suave ao fazer solicitações HTTP. Seus principais recursos incluem autenticação, roteamento e mapeamento objeto-relacional (ORM) eficaz.

Este artigo explorará o uso do cliente HTTP do Laravel para fazer solicitações, depurar respostas, criar middleware e macros e muito mais.

Laravel HTTP Client faz o trabalho duro para você para APIs

Guzzle é um cliente HTTP simples para PHP. Ele oferece funcionalidade para diferentes solicitações de formulário, incluindo GET , POST , PUT e DELETE junto com os recursos de streaming e solicitações de várias partes. Com o cliente HTTP Guzzle, é possível enviar solicitações síncronas e assíncronas ao servidor. Além disso, também vem com um middleware decente para personalizar o comportamento do cliente.

O cliente HTTP do Laravel é um wrapper construído no Guzzle, mas com funcionalidades extras. Ele inclui suporte para repetir solicitações com falha e algumas funções auxiliares com dados JSON. A maioria das funcionalidades dos clientes Laravel HTTP são semelhantes ao Guzzle.

Pré-requisitos

Nas seções a seguir, você aprenderá mais sobre o cliente HTTP do Laravel. Para acompanhar você vai precisar de:

• Conhecimento básico de Laravel, PHP e APIs
• PHP e Composer instalados
• Carteiro

Como fazer solicitações

Para entender como usar um cliente HTTP para fazer uma solicitação, você pode aproveitar várias APIs hospedadas, como ReqRes.

Comece importando o pacote HTTP incluído ao criar o aplicativo. Dentro do arquivo App/Http/Controllers/UserController.php , adicione o seguinte código, começando com a instrução use no início do arquivo e o código restante dentro da função index.

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

Observação: para casos de uso complexos, você também pode enviar a solicitação com cabeçalhos usando o método withHeaders .

No mesmo arquivo, crie um novo post de método usando o código abaixo:

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

Em seguida, adicione uma rota para ele dentro do arquivo routes/web.php :

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

Agora, Postman pode ser usado para testar esta rota. Abra o Postman e adicione http://127.0.0.1:8000/post como URL, com o tipo de solicitação como GET . Depois de clicar em enviar , você verá a seguinte resposta:

Solicitações Simultâneas

As solicitações paralelas melhoram significativamente o desempenho, pois você pode buscar mais dados no mesmo período. O cliente HTTP do Laravel permite realizar solicitações simultâneas usando o método pool.

Dentro de App/Http/Controllers/UserController.php , adicione o seguinte código:

 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(); }

Em seguida, adicione a rota de suporte dentro do arquivo routes/web.php .

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

O navegador dá a seguinte resposta quando a rota é visitada:

Solicitar macros

As macros de solicitação são úteis ao interagir com caminhos de API comuns.

Para criar a macro, você precisa definir a macro dentro do método boot do arquivo app/Http/Providers/AppServiceProvider.php usando o código abaixo:

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

Nota: Certifique-se de adicionar a instrução de uso no início do arquivo.

Em seguida, use a macro dentro do UserController adicionando o seguinte código:

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

Como você pode ver, como a macro já está sendo criada, não é necessário adicionar a URL completa novamente.

Por último, adicione uma rota no arquivo routes/web.php usando o código abaixo:

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

Como decodificar respostas

Para decodificar uma resposta e garantir que uma solicitação de API seja bem-sucedida, use o método de status incluído no cliente. Este método obtém o código de status enviado do servidor e o exibe.

Para testar isso, substitua o código da macro anterior pelo código abaixo dentro do arquivo App/Http/Controllers/UserController.php :

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

Aqui, o código de status 200 significa que a solicitação foi bem-sucedida.

Como testar APIs JSON

O Laravel possui diversos helpers para testar as APIs JSON e suas respostas. As funções auxiliares incluem json , getJson , postJson , putJson , patchJson , deleteJson e assim por diante.

Para entender melhor o Testing, crie um cenário de teste para a rota do usuário GET . Quando você inicializa o aplicativo Laravel, o Teste de Exemplo já está criado. Dentro do arquivo tests/Feature/ExampleTest.php , substitua o código existente pelo seguinte:

 <?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); } }

O código adicionado busca os dados JSON na rota do usuário e verifica se o código de status é 200 ou não.

Depois de adicionar o código de teste, execute o seguinte comando em seu terminal para executar os testes:

 ./vendor/bin/phpunit

Depois que os testes forem concluídos, você verá que ele executou dois testes, ambos bem-sucedidos.

Da mesma forma, você pode verificar diferentes tipos de solicitações e utilizar outros métodos auxiliares para testes mais sofisticados.

Como lidar com eventos

O Laravel oferece três eventos a serem acionados ao lidar com solicitações HTTP.

• RequestSending , que é antes do envio da solicitação.
• ResponseReceived , que é quando uma resposta é recebida.
• ConnectionFailed , que é quando nenhuma resposta é recebida.

Todos os três eventos incluem a propriedade $request para inspecionar a instância Illuminate\Http\Client\Request e ResponseReceived tem uma $response property . Estes são particularmente úteis para executar ações após um evento. Por exemplo, você pode querer enviar um e-mail depois de obter uma resposta bem-sucedida.

Para criar um evento e um ouvinte, navegue até o arquivo app/Providers/EventServiceProvider.php e substitua a matriz de escuta pelo seguinte código.

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

Em seguida, execute o seguinte comando no seu terminal:

 php artisan event:generate

O comando acima criará o ouvinte app/Listeners/LogResponseReceived.php . Substitua o código desse arquivo pelo código abaixo:

 <?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) { } }

O registro de informações do código de status é impresso no terminal.

Resumo

Independentemente de um site ou aplicativo da Web ser feito por uma organização ou um desenvolvedor independente, as APIs são a chave para seu sucesso. No entanto, usá-los pode ser difícil.

Muitos frameworks e bibliotecas prometem simplificar esse processo, mas o Laravel se destaca pelo foco na simplicidade e facilidade de uso. Seu cliente integrado oferece suporte a chamadas de API fáceis, chamadas de API simultâneas, macros de API, métodos auxiliares para APIs baseadas em JSON e muito mais.