API Integration

Use fetch_client() for the process-wide helper client, or construct Fetch\Http\Client / ClientHandler when an application needs explicit dependency ownership. Keep endpoint-specific configuration in the request options and shared configuration on the handler.

$client = fetch_client([
    'base_uri' => 'https://api.example.test/v1/',
    'headers' => ['Accept' => 'application/json'],
]);

$handler = $client->getHandler();
$response = $handler->get('users', ['query' => ['page' => 2]]);

Convenience methods can return a response or a promise depending on async mode. See making requests. The offline client configuration fixture is included below.

<?php

declare(strict_types=1);

require dirname(__DIR__, 3).'/vendor/autoload.php';

use Fetch\Interfaces\Response as FetchResponse;
use Fetch\Testing\MockResponse;
use Fetch\Testing\MockServer;

MockServer::fake([
    'GET https://api.example.test/v1/users' => MockResponse::json([
        ['id' => 1, 'name' => 'Ada'],
    ]),
]);
MockServer::preventStrayRequests();

$client = fetch_client(
    [
        'base_uri' => 'https://api.example.test/v1/',
        'headers' => ['Accept' => 'application/json'],
        'timeout' => 5,
    ],
    reset: true,
);

$handler = $client->getHandler();
if ($handler->getOptions()['timeout'] !== 5) {
    throw new RuntimeException('The client options were not applied.');
}

$handler->withHeader('X-Client', 'example');
$response = $handler->get('users');

if (! ($response instanceof FetchResponse) || ! $response->successful()) {
    throw new RuntimeException('The configured client request failed.');
}