Cliente HTTP - Knowledge of Laravel

Qué es el cliente HTTP

El cliente HTTP de Laravel es una API sencilla que envuelve a Guzzle. A través del facade Http puedes escribir con concisión peticiones HTTP a servicios y APIs externas.

use Illuminate\Support\Facades\Http;

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

Guzzle viene preinstalado, así que puedes empezar a usar el cliente sin configuración adicional.

Peticiones básicas

Petición GET

use Illuminate\Support\Facades\Http;

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

Los parámetros de consulta se pasan como array.

$response = Http::get('https://api.example.com/users', [
    'page' => 1,
    'per_page' => 20,
]);

Petición POST

Los datos se envían por defecto como application/json.

$response = Http::post('https://api.example.com/users', [
    'name' => 'Ana García',
    'email' => '[email protected]',
]);

PUT / PATCH / DELETE

// Petición PUT
$response = Http::put('https://api.example.com/users/1', [
    'name' => 'Ana López',
]);

// Petición PATCH
$response = Http::patch('https://api.example.com/users/1', [
    'email' => '[email protected]',
]);

// Petición DELETE
$response = Http::delete('https://api.example.com/users/1');

Manejo de la respuesta

Métodos como Http::get() devuelven una instancia de Illuminate\Http\Client\Response. El objeto ofrece numerosos métodos para inspeccionar la respuesta.

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

// Cuerpo de la respuesta
$response->body();        // Como cadena
$response->json();        // Convertido en array
$response->json('name');  // Una clave concreta
$response->object();      // Como objeto stdClass
$response->collect();     // Como Collection

// Estado
$response->status();      // Código HTTP (p. ej. 200)
$response->successful();  // true si es 2xx
$response->failed();      // true si es 4xx o 5xx
$response->clientError(); // true si es 4xx
$response->serverError(); // true si es 5xx

// Códigos habituales
$response->ok();           // 200
$response->created();      // 201
$response->noContent();    // 204
$response->notFound();     // 404
$response->unauthorized(); // 401
$response->forbidden();    // 403
$response->unprocessableEntity(); // 422
$response->tooManyRequests();     // 429

Las respuestas JSON también son accesibles como array.

$name = Http::get('https://api.example.com/users/1')['name'];

Opciones de la petición

Cabeceras

$response = Http::withHeaders([
    'X-Api-Version' => '2',
    'Accept-Language' => 'es',
])->get('https://api.example.com/users');

Si quieres indicar que aceptas application/json, acceptJson() es una forma más cómoda.

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

Para las cabeceras CSRF (X-CSRF-TOKEN / X-XSRF-TOKEN) en peticiones AJAX del navegador hacia Laravel, consulta protección CSRF.

Autenticación

Autenticación con Bearer token (la más habitual):

$response = Http::withToken($token)->get('https://api.example.com/me');

Autenticación básica:

$response = Http::withBasicAuth('[email protected]', 'password')
    ->get('https://api.example.com/private');

URL base

Si haces muchas peticiones al mismo host, agrúpalas con baseUrl().

$response = Http::baseUrl('https://api.example.com')
    ->withToken($token)
    ->get('/users/1');

Enviar datos de formulario

Para enviar con application/x-www-form-urlencoded utiliza asForm().

$response = Http::asForm()->post('https://api.example.com/login', [
    'username' => 'ana',
    'password' => 'secret',
]);

Timeouts

// Timeout de respuesta (por defecto 30 s)
$response = Http::timeout(10)->get('https://api.example.com/slow-endpoint');

// Timeout de conexión (por defecto 10 s)
$response = Http::connectTimeout(5)->get('https://api.example.com/endpoint');

Si se supera el timeout se lanza Illuminate\Http\Client\ConnectionException. Es recomendable configurar siempre un timeout en las llamadas a APIs externas.

Reintentos

Puedes configurar reintentos automáticos ante errores puntuales de red o del servidor.

// Hasta 3 reintentos con 100 ms de intervalo
$response = Http::retry(3, 100)->post('https://api.example.com/orders', $data);

Reintentos condicionales (por ejemplo, solo cuando haya error de conexión):

use Illuminate\Http\Client\PendingRequest;
use Throwable;
use Illuminate\Http\Client\ConnectionException;

$response = Http::retry(3, 100, function (Throwable $exception, PendingRequest $request) {
    return $exception instanceof ConnectionException;
})->post('https://api.example.com/orders', $data);

Gestión de errores

Comprobar los errores manualmente

Por defecto, el cliente HTTP de Laravel no lanza excepciones ante respuestas 4xx o 5xx. Compruébalas explícitamente con failed(), clientError(), etc.

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

if ($response->notFound()) {
    // Manejar el 404
}

if ($response->failed()) {
    // Registrar el error, etc.
    logger()->error('API request failed', ['status' => $response->status()]);
}

Lanzar excepciones

Con throw() se lanza Illuminate\Http\Client\RequestException cuando hay errores.

// Lanza excepción si la respuesta es 4xx/5xx
$response = Http::post('https://api.example.com/users', $data)->throw();

// throwIf(): lanza excepción cuando la condición es true (ejemplo independiente)
$response = Http::get('https://api.example.com/users/1');
$response->throwIf($response->status() === 422);

// throwUnlessStatus(): lanza excepción salvo con el código indicado (ejemplo independiente)
$response = Http::post('https://api.example.com/orders', $data);
$response->throwUnlessStatus(201);

throw() devuelve la propia respuesta, por lo que se puede encadenar.

$user = Http::post('https://api.example.com/users', $data)
    ->throw()
    ->json();

Ejemplo de captura de excepciones:

use Illuminate\Http\Client\RequestException;
use Illuminate\Http\Client\ConnectionException;

try {
    $response = Http::timeout(5)
        ->post('https://api.example.com/users', $data)
        ->throw();
} catch (ConnectionException $e) {
    // Timeout o error de conexión
    logger()->error('Connection failed: ' . $e->getMessage());
} catch (RequestException $e) {
    // Error 4xx / 5xx
    logger()->error('API error', ['status' => $e->response->status()]);
}

Peticiones concurrentes

Cuando necesites llamar a varias APIs simultáneamente, utiliza pool() para ejecutarlas en paralelo.

use Illuminate\Http\Client\Pool;
use Illuminate\Support\Facades\Http;

$responses = Http::pool(fn (Pool $pool) => [
    $pool->as('users')->get('https://api.example.com/users'),
    $pool->as('posts')->get('https://api.example.com/posts'),
    $pool->as('comments')->get('https://api.example.com/comments'),
]);

$users    = $responses['users']->json();
$posts    = $responses['posts']->json();
$comments = $responses['comments']->json();

Es mucho más rápido que hacerlas en secuencia. Útil en paneles que consumen varias APIs externas.

Pruebas

Mock con `Http::fake()`

En tests usa Http::fake() para simular respuestas sin realizar la petición real.

use Illuminate\Support\Facades\Http;

Http::fake();

// Todas las peticiones devuelven 200
$response = Http::get('https://api.example.com/users');
$response->successful(); // true

Definir respuestas para URLs concretas:

Http::fake([
    'api.example.com/users/*' => Http::response(['id' => 1, 'name' => 'Ana García'], 200),
    'api.example.com/posts/*' => Http::response(['error' => 'Not Found'], 404),
    '*' => Http::response('OK', 200),  // El resto
]);

Secuencia de respuestas (devuelve una respuesta distinta en cada invocación):

Http::fake([
    // 1ª: 200, 2ª: 200, 3ª: 429
    // Cuando se agota la secuencia las peticiones posteriores lanzan excepción
    'api.example.com/*' => Http::sequence()
        ->push(['id' => 1], 200)
        ->push(['id' => 2], 200)
        ->pushStatus(429),
]);

Aserciones sobre la petición

Con Http::assertSent() puedes validar el contenido de las peticiones enviadas.

use Illuminate\Http\Client\Request;
use Illuminate\Support\Facades\Http;

Http::fake();

Http::withToken('my-token')->post('https://api.example.com/users', [
    'name' => 'Ana García',
]);

Http::assertSent(function (Request $request) {
    return $request->url() === 'https://api.example.com/users'
        && $request->hasHeader('Authorization', 'Bearer my-token')
        && $request['name'] === 'Ana García';
});

// Comprobar que no se ha enviado
Http::assertNotSent(function (Request $request) {
    return $request->url() === 'https://api.example.com/admin';
});

// Comprobar que se ha enviado exactamente una petición
Http::assertSentCount(1);

En los tests, invoca siempre Http::fake() al principio. Si te lo saltas, las peticiones irán a las APIs reales. Con Http::preventStrayRequests() puedes hacer que las peticiones a URLs no simuladas lancen una excepción.

Prevención de peticiones no simuladas

Http::preventStrayRequests();

Http::fake([
    'api.example.com/*' => Http::response(['ok' => true]),
]);

// Las peticiones a URLs no simuladas lanzan excepción
Http::get('https://other.example.com/endpoint'); // Excepción

Ejemplo práctico: clase de servicio para una API externa

En proyectos reales, la buena práctica es agrupar la lógica del cliente HTTP en clases de servicio.

Crear la clase de servicio

<?php

namespace App\Services;

use Illuminate\Http\Client\RequestException;
use Illuminate\Http\Client\ConnectionException;
use Illuminate\Support\Facades\Http;

class GitHubService
{
    private string $baseUrl = 'https://api.github.com';

    public function __construct(
        private readonly string $token,
    ) {}

    /**
     * Obtiene información de un usuario
     *
     * @throws ConnectionException
     * @throws RequestException
     */
    public function getUser(string $username): array
    {
        return Http::baseUrl($this->baseUrl)
            ->withToken($this->token)
            ->acceptJson()
            ->timeout(10)
            ->get("/users/{$username}")
            ->throw()
            ->json();
    }

    /**
     * Obtiene la lista de repositorios
     *
     * @throws ConnectionException
     * @throws RequestException
     */
    public function getRepositories(string $username, int $page = 1): array
    {
        return Http::baseUrl($this->baseUrl)
            ->withToken($this->token)
            ->acceptJson()
            ->timeout(10)
            ->retry(2, 500)
            ->get("/users/{$username}/repos", [
                'page' => $page,
                'per_page' => 30,
                'sort' => 'updated',
            ])
            ->throw()
            ->json();
    }
}

Registrar el servicio en el service provider

// app/Providers/AppServiceProvider.php

use App\Services\GitHubService;

public function register(): void
{
    $this->app->singleton(GitHubService::class, function () {
        return new GitHubService(
            token: config('services.github.token'),
        );
    });
}

// config/services.php
'github' => [
    'token' => env('GITHUB_TOKEN'),
],

Usarlo desde el controlador

<?php

namespace App\Http\Controllers;

use App\Services\GitHubService;
use Illuminate\Http\Client\RequestException;
use Illuminate\Http\Client\ConnectionException;
use Illuminate\Http\JsonResponse;

class GitHubController extends Controller
{
    public function __construct(
        private readonly GitHubService $github,
    ) {}

    public function show(string $username): JsonResponse
    {
        try {
            $user = $this->github->getUser($username);
            return response()->json($user);
        } catch (ConnectionException) {
            return response()->json(['error' => 'No se ha podido conectar con la API de GitHub.'], 503);
        } catch (RequestException $e) {
            $status = $e->response->status();
            if ($status === 404) {
                return response()->json(['error' => 'Usuario no encontrado.'], 404);
            }
            return response()->json(['error' => 'Se ha producido un error en la API de GitHub.'], 502);
        }
    }
}

Escribir los tests

<?php

namespace Tests\Unit\Services;

use App\Services\GitHubService;
use Illuminate\Http\Client\ConnectionException;
use Illuminate\Http\Client\RequestException;
use Illuminate\Support\Facades\Http;
use Tests\TestCase;

class GitHubServiceTest extends TestCase
{
    private GitHubService $service;

    protected function setUp(): void
    {
        parent::setUp();

        Http::fake([
            'api.github.com/users/octocat' => Http::response([
                'login' => 'octocat',
                'name' => 'The Octocat',
                'public_repos' => 8,
            ], 200),
            'api.github.com/users/notfound' => Http::response(
                ['message' => 'Not Found'],
                404
            ),
        ]);

        $this->service = new GitHubService(token: 'test-token');
    }

    public function test_obtiene_la_informacion_del_usuario(): void
    {
        $user = $this->service->getUser('octocat');

        $this->assertEquals('octocat', $user['login']);
        $this->assertEquals('The Octocat', $user['name']);

        Http::assertSent(function ($request) {
            return $request->url() === 'https://api.github.com/users/octocat'
                && $request->hasHeader('Authorization', 'Bearer test-token');
        });
    }

    public function test_lanza_excepcion_con_usuario_inexistente(): void
    {
        $this->expectException(RequestException::class);

        $this->service->getUser('notfound');
    }
}

Resumen

Métodos más habituales

Método	Uso
`Http::get($url, $query)`	Petición GET
`Http::post($url, $data)`	Petición POST (JSON)
`Http::put($url, $data)`	Petición PUT
`Http::patch($url, $data)`	Petición PATCH
`Http::delete($url)`	Petición DELETE
`->withToken($token)`	Autenticación Bearer
`->withHeaders($headers)`	Cabeceras personalizadas
`->timeout($seconds)`	Configuración de timeout
`->retry($times, $sleep)`	Reintentos automáticos
`->throw()`	Lanzar excepción si hay error
`Http::fake()`	Mock para tests
`Http::pool($callback)`	Peticiones concurrentes

Métodos de comprobación de la respuesta

Método	Descripción
`successful()`	2xx
`failed()`	4xx o 5xx
`clientError()`	4xx
`serverError()`	5xx
`ok()`	200
`created()`	201
`notFound()`	404
`unauthorized()`	401
`forbidden()`	403
`unprocessableEntity()`	422
`tooManyRequests()`	429

Buenas prácticas al integrar APIs externas

Agrupa la lógica del cliente HTTP en clases de servicio.
Configura siempre un timeout (timeout() y connectTimeout()).
Configura reintentos para errores puntuales (retry()).
En los tests utiliza siempre Http::fake() y no llames nunca a las APIs reales.
Añadir Http::preventStrayRequests() al setup te da un extra de tranquilidad.
Guarda tokens y credenciales en variables de entorno y en config/services.php.

​Qué es el cliente HTTP

​Peticiones básicas

​Petición GET

​Petición POST

​PUT / PATCH / DELETE

​Manejo de la respuesta

​Opciones de la petición

​Cabeceras

​Autenticación

​URL base

​Enviar datos de formulario

​Timeouts

​Reintentos

​Gestión de errores

​Comprobar los errores manualmente

​Lanzar excepciones

​Peticiones concurrentes

​Pruebas

​Mock con Http::fake()

​Aserciones sobre la petición

​Prevención de peticiones no simuladas

​Ejemplo práctico: clase de servicio para una API externa

​Resumen

Qué es el cliente HTTP

Peticiones básicas

Petición GET

Petición POST

PUT / PATCH / DELETE

Manejo de la respuesta

Opciones de la petición

Cabeceras

Autenticación

URL base

Enviar datos de formulario

Timeouts

Reintentos

Gestión de errores

Comprobar los errores manualmente

Lanzar excepciones

Peticiones concurrentes

Pruebas

Mock con `Http::fake()`

Aserciones sobre la petición

Prevención de peticiones no simuladas

Ejemplo práctico: clase de servicio para una API externa

Resumen