⬡ Lacelium
⌘K
Version 2.x ▾

HTTP Client

Introduction

Lacelium provides an expressive, minimal API around the Guzzle HTTP client, allowing you to quickly make outgoing HTTP requests to communicate with external APIs, microservices, and webhooks.

The HTTP client's primary focus is on developer ergonomics, clean chaining, and handling common tasks like sending JSON payloads, adding bearer authentication tokens, and retrying failed requests.

Making Requests

To make requests, you may use the get, post, put, patch, and delete methods provided by the global http() helper or the Lacelium\Core\Http\Client class:

use Lacelium\Core\Http\Client as Http;

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

$response = Http::post('https://api.example.com/orders', [
    'product_id' => 42,
    'quantity' => 2,
]);

Request Data & Query Parameters

When making GET requests, you may either append a query string to the URL directly or pass an array of key-value pairs as the second argument to the get method:

$response = Http::get('https://api.example.com/search', [
    'query' => 'lacelium framework',
    'page' => 1,
]);

Headers & Authentication

You may use the withHeaders method to add custom headers to the request, or use dedicated convenience helpers for authentication:

// Custom headers
$response = Http::withHeaders([
    'X-Custom-Header' => 'Value',
])->post('https://api.example.com/data');

// Bearer token authentication
$response = Http::withToken('your-secret-token')
    ->get('https://api.example.com/profile');

// Basic authentication
$response = Http::withBasicAuth('username', 'password')
    ->get('https://api.example.com/protected');

Inspecting Responses

The response object returned by request methods provides a variety of methods that may be used to inspect the response:

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

// Status code checking
$status = $response->status(); // 200
$ok = $response->successful(); // true if 2xx
$failed = $response->failed(); // true if 4xx or 5xx

// Body decoding
$json = $response->json(); // Decoded associative array
$name = $response->json('data.name'); // Nested dot access
$body = $response->body(); // Raw string body

// Headers
$contentType = $response->header('Content-Type');

Timeouts & Retries

To specify a maximum time in seconds to wait for a response, use the timeout method. To automatically retry a request if a connection error occurs, use the retry method:

// Timeout after 3.5 seconds
$response = Http::timeout(3.5)->get('https://api.example.com/fast');

// Retry up to 3 times with 100ms backoff between attempts
$response = Http::retry(3, 100)->post('https://api.example.com/payment', $data);

Error Handling

By default, the HTTP client will not throw exceptions when a 4xx or 5xx HTTP status code is encountered. If you want an exception to be thrown if the response status code indicates an error, use the throw method:

$response = Http::post('https://api.example.com/webhook')->throw();

Next Steps