The HTTP Driver

Introduction

The HTTP driver gives Kipchak APIs their HTTP clients. By default it returns Laravel's HTTP client (illuminate/http), with its fluent API. It can also provide named clients, each configured separately, including a PSR-18 client and the PSR-17 factories for libraries and SDKs that require the PHP standards.

Installation

Install the driver via composer by running:

composer require kipchak/driver-http

Initialise the Driver

Add the following line to your drivers/drivers.php file, after the Config driver:

\Kipchak\Driver\Http\Http::initialise($container);

Configuration

The driver needs no configuration. Without a config file, Http::get() returns Laravel's HTTP client, as it always has.

To define named clients, create config/kipchak.http.php. Each entry is a client, by name:

<?php

use function Kipchak\Core\env;

return [
    // Http::get(): Laravel's client. Omit this entry and the default is Laravel's client anyway.
    'default' => ['type' => 'laravel'],

    // Http::get('github'): Laravel's client with a base URL and its own options.
    'github' => [
        'type' => 'laravel',
        'base_url' => 'https://api.github.com',
        'options' => [
            'timeout' => 10,
            'headers' => ['Authorization' => 'Bearer ' . env('GITHUB_TOKEN', '')],
        ],
    ],

    // Http::get('ai'): a PSR-18 client, for SDKs that take one.
    'ai' => [
        'type' => 'psr18',
        'options' => ['timeout' => 120, 'connect_timeout' => 10],
    ],

    // Http::get('psr17'): the PSR-17 factories.
    'psr17' => ['type' => 'psr17'],
];

Each client is built once per worker and shared, which is safe in FrankenPHP worker mode and reuses connections across requests. A mistake in the file, such as an unknown type, stops the API at startup with a message naming the key.

Usage

Laravel's client

use Kipchak\Driver\Http\Http;

$response = Http::get()->get('https://api.example.com/data');
$repos = Http::get('github')->get('/user/repos')->json();

Access parts of the response using:

$response->body() : string;
$response->json($key = null, $default = null) : mixed;
$response->object() : object;
$response->collect($key = null) : Illuminate\Support\Collection;
$response->resource() : resource;
$response->status() : int;
$response->successful() : bool;
$response->redirect(): bool;
$response->failed() : bool;
$response->clientError() : bool;
$response->header($header) : string;
$response->headers() : array;

For more details, see the Laravel HTTP Client documentation.

PSR-18 and PSR-17

Http::get() returns any type of client. Http::psr18() and Http::psr17() return the same configured clients, typed for your editor and static analysis, and fail with a clear message if the named client is of another type.

use Kipchak\Driver\Http\Http;

$client = Http::psr18('ai');            // Psr\Http\Client\ClientInterface
$factory = Http::psr17('psr17');        // request, response, stream, URI ... factories

$request = $factory->createRequest('GET', 'https://api.example.com/data');
$response = $client->sendRequest($request);

Pass them to SDKs that take a PSR-18 client, so that their requests use your timeouts and proxy:

$openai = \OpenAI::factory()->withApiKey($key)->withHttpClient(Http::psr18('ai'))->make();

The PSR-18 client follows the standard: responses with any status are returned rather than thrown, and network failures, including timeouts, throw Psr\Http\Client\NetworkExceptionInterface. Redirects are returned rather than followed, so the library calling it decides. The driver's tests run the official PSR-18 suite (php-http/client-integration-tests) and PSR-17 suite (http-interop/http-factory-tests) against configured clients.

Testing

Laravel clients can be faked in your tests with Http::get()->fake(). Any client can be replaced in the container under drivers.http.<name>, for example with a Guzzle client built on Guzzle's MockHandler.

Git Repository

The source code for this driver is available on 1x.ax at https://1x.ax/mamluk/kipchak/drivers/http.