Laravel HTTP Client

Tempo de leitura: 4 minutos

O Laravel HTTP Client é uma wrapper elegante e fluida em torno da popular biblioteca Guzzle HTTP, fornecendo uma API intuitiva para realizar requisições HTTP e interagir com serviços externos. Essencialmente, ele simplifica tarefas como a definição de cabeçalhos, o envio de dados JSON e a manipulação de respostas, sendo a ferramenta padrão no Laravel para comunicações server-to-server.

1. 📤 Realizando Requisições Básicas

A Facade Http é o ponto de entrada para todas as requisições.

A. Requisições Simples (GET)

O método get() realiza uma solicitação GET. O objeto $response retornado é rico em métodos úteis para inspeção.

PHP

use Illuminate\Support\Facades\Http;

$response = Http::get('https://api.example.com/users');

// Acessando o corpo da resposta como array PHP
$users = $response->json(); 

// Acessando o status da resposta
$status = $response->status(); // 200, 404, etc.

// Verificando se a resposta foi um sucesso (status 2xx)
if ($response->successful()) {
    // ...
}

B. Outros Métodos HTTP (POST/PUT/DELETE)

Para enviar dados em métodos que modificam recursos, use os métodos correspondentes, passando um array de dados. O Laravel, por padrão, envia esses dados como form parameters.

PHP

// Requisição POST, enviando 'title' e 'body'
$response = Http::post('https://api.example.com/posts', [
    'title' => 'Meu novo post',
    'body' => 'Conteúdo do post'
]);

2. 📝 Personalizando e Configurando Requisições

O HTTP Client usa uma interface fluida, permitindo encadear métodos de configuração antes do método HTTP final.

Método	Função	Exemplo
`withHeaders()`	Define cabeçalhos HTTP personalizados.	`Http::withHeaders(['X-Custom' => 'value'])`
`withQuery()`	Adiciona query parameters (parâmetros de URL).	`Http::withQuery(['sort' => 'desc'])`
`withToken()`	Adiciona um cabeçalho `Authorization: Bearer <token>`.	`Http::withToken('seu_jwt')`
`timeout()`	Define o tempo máximo de espera pela resposta (em segundos).	`Http::timeout(3)`

A. Envio de Dados JSON

Para que os dados sejam serializados em JSON e o cabeçalho Content-Type: application/json seja enviado, use o método json() no lugar de post()/put().

PHP

$response = Http::withToken('token-api-service')->post('https://api.service.com/users', [
    'name' => 'Jane Doe',
    'email' => '[email protected]'
]);
// Se o status for 4xx ou 5xx, lança uma exceção no final
$response->throw()->json();

B. Failsafe: Tentativas e Tempo Limite

Você pode configurar o cliente para tentar a requisição novamente em caso de falha (erro 5xx ou timeout):

PHP

// Tenta 3 vezes, esperando 100ms entre as tentativas
$response = Http::retry(3, 100)->get('https://api.flaky.com/data');

3. 🧪 Testing e Faking

Uma das grandes vantagens do Laravel HTTP Client é a facilidade de mockar (simular) as respostas das APIs externas, tornando os testes unitários rápidos e isolados.

Simulação (Faking)

O método fake() intercepta chamadas HTTP e retorna respostas pré-definidas.

PHP

use Illuminate\Support\Facades\Http;

// 1. Simula todas as chamadas HTTP (para qualquer URL)
Http::fake([
    // Se a requisição for para esta URL...
    'api.example.com/users/*' => Http::response(['data' => ['id' => 1, 'name' => 'Mocked User']], 200),
    
    // Simula falha para outras chamadas
    '*' => Http::response(null, 500)
]);

// 2. O código executa normalmente, mas usa a resposta simulada
$response = Http::get('https://api.example.com/users/123');
// $response->json() retornará ['data' => ['id' => 1, 'name' => 'Mocked User']]

4. 📢 Eventos do Cliente HTTP

O HTTP Client dispara eventos em momentos cruciais, permitindo que você injete lógica (como logging ou métricas) sem modificar o código da requisição.

Evento	Quando é Disparado	Uso Típico
`RequestSending`	Imediatamente antes de enviar a requisição.	Logging de requisições de saída, adicionar cabeçalhos dinâmicos.
`ResponseReceived`	Após receber a resposta.	Logging de respostas, monitoramento de latência.

A. Registrando um Listener de Evento

Você registra o Listener no EventServiceProvider para o evento RequestSending (ou ResponseReceived):

PHP

// app/Providers/EventServiceProvider.php
protected $listen = [
    'Illuminate\Http\Client\Events\RequestSending' => [
        \App\Listeners\LogOutgoingRequests::class, // Seu Listener
    ],
];

B. Implementação do Listener

O objeto do evento contém a instância da requisição, permitindo inspecioná-la:

PHP

// App\Listeners\LogOutgoingRequests.php
use Illuminate\Http\Client\Events\RequestSending;
use Illuminate\Support\Facades\Log;

class LogOutgoingRequests
{
    public function handle(RequestSending $event)
    {
        // Loga a URL e o corpo (se houver) da requisição
        Log::info('Requisição Externa Enviada', [
            'method' => $event->request->method(),
            'url' => $event->request->url(),
            'body_size' => strlen($event->request->body()),
        ]);
    }
}

✅ Conclusão Laravel HTTP Client

Laravel HTTP Client: É a ferramenta definitiva no Laravel para interações com APIs. Sua interface fluente, aliada a recursos como withToken, timeout e retry, simplifica requisições complexas. A funcionalidade de Http::fake() é um game-changer para testes. Por fim, o sistema de Eventos oferece uma forma desacoplada de monitorar e personalizar o comportamento das requisições externas.

Mas antes de dominar o Laravel, se for o seu caso, toda jornada tem um início. Vamos entender quais são os conhecimentos básicos necessários para aproveitar ao máximo este poderoso framework. Para iniciar seus estudos no Laravel, você precisará dominar as seguintes tecnologias: