7 changing client

One of the core design goals of this package is driver independence. You write your request code once, and the underlying HTTP library can be swapped at any time — through configuration, the builder, or direct injection. This is especially valuable when moving between environments (e.g., a Symfony project that uses the Symfony driver vs. a CLI tool that uses raw cURL).

Available Drivers

The package ships with three production drivers and one test driver:

Driver name	Library	Package
`curl`	PHP cURL extension	Built-in (no dependency)
`guzzle`	Guzzle HTTP	`guzzlehttp/guzzle`
`symfony`	Symfony HttpClient	`symfony/http-client`
(mock)	Built-in test double	Built-in

The default driver is curl, which requires no additional dependencies since the cURL extension is included with most PHP installations.

CurlDriver

The cURL driver provides zero-dependency HTTP support. It uses PHP’s native cURL extension with automatic HTTP/1.1 and HTTP/2 negotiation, full header parsing, streaming support, and built-in SSL verification. This is the best choice for quick starts and lightweight applications.

GuzzleDriver

Guzzle is a mature, feature-rich HTTP client with its own middleware ecosystem, PSR-7 message support, and excellent streaming capabilities. Use it when you need Guzzle-specific features or when your project already depends on it.

SymfonyDriver

The Symfony HttpClient offers native HTTP/2 support, automatic content-type detection, and multiple transports (native PHP, cURL, amphp). It is the natural choice for Symfony applications.

Switching Drivers

Via Configuration

The simplest way to choose a driver is through HttpClientConfig:

use Cognesy\Http\Config\HttpClientConfig;
use Cognesy\Http\HttpClient;

// Use Guzzle
$client = HttpClient::fromConfig(new HttpClientConfig(driver: 'guzzle'));

// Use Symfony
$client = HttpClient::fromConfig(new HttpClientConfig(driver: 'symfony'));

// Use cURL (default)
$client = HttpClient::fromConfig(new HttpClientConfig(driver: 'curl'));
// @doctest id="6897"

Via the Builder

The builder gives you the same choice in a more explicit, composable form:

use Cognesy\Http\Config\HttpClientConfig;
use Cognesy\Http\Creation\HttpClientBuilder;

$client = (new HttpClientBuilder())
    ->withConfig(new HttpClientConfig(driver: 'guzzle'))
    ->create();
// @doctest id="0946"

Injecting a Driver Directly

If you have a pre-configured driver instance, bypass the registry entirely:

use Cognesy\Http\Creation\HttpClientBuilder;

$client = (new HttpClientBuilder())
    ->withDriver($myCustomDriver)
    ->create();
// @doctest id="3b10"

Or use the static shorthand:

use Cognesy\Http\HttpClient;

$client = HttpClient::fromDriver($myCustomDriver);
// @doctest id="5aae"

Reusing a Vendor Client Instance

Sometimes you already have a configured vendor client (e.g., a GuzzleHttp\Client with custom options or a Symfony client with specific transport settings). You can pass that instance directly:

use Cognesy\Http\Creation\HttpClientBuilder;
use GuzzleHttp\Client;

$guzzle = new Client([
    'timeout' => 10,
    'verify' => '/path/to/cacert.pem',
]);

$client = (new HttpClientBuilder())
    ->withClientInstance('guzzle', $guzzle)
    ->create();
// @doctest id="958c"

The withClientInstance() method selects the driver by name and passes your vendor client to it, so the driver uses your instance instead of creating its own. This works with any supported driver:

use Symfony\Component\HttpClient\HttpClient as SymfonyHttpClient;

$client = (new HttpClientBuilder())
    ->withClientInstance('symfony', SymfonyHttpClient::create(['timeout' => 30]))
    ->create();
// @doctest id="c6a9"

Using the Mock Driver

For testing, the mock driver lets you define responses without making network calls:

use Cognesy\Http\Creation\HttpClientBuilder;
use Cognesy\Http\Data\HttpResponse;

$client = (new HttpClientBuilder())
    ->withMock(function ($mock) {
        $mock->addResponse(
            HttpResponse::sync(200, ['Content-Type' => 'application/json'], '{"users":[]}'),
            url: 'https://api.example.com/users',
            method: 'GET',
        );
    })
    ->create();
// @doctest id="ae48"

Request Code Stays the Same

The key insight is that your request code never changes when you switch drivers. The same HttpRequest, the same send() call, the same response handling:

$response = $client->send(new HttpRequest(
    url: 'https://api.example.com/data',
    method: 'GET',
    headers: ['Accept' => 'application/json'],
    body: '',
    options: [],
))->get();

echo $response->body();
// @doctest id="751e"

This code works identically with cURL, Guzzle, Symfony, or the mock driver.

Packages

Instructor

Polyglot

Agents

Agent-ctrl

Telemetry

Sandbox

HTTP Client

Laravel

Symfony

Xprompt

Available Drivers

CurlDriver

GuzzleDriver

SymfonyDriver

Switching Drivers

Via Configuration

Via the Builder

Injecting a Driver Directly

Reusing a Vendor Client Instance

Using the Mock Driver

Request Code Stays the Same

See Also

​Available Drivers

​CurlDriver

​GuzzleDriver

​SymfonyDriver

​Switching Drivers

​Via Configuration

​Via the Builder

​Injecting a Driver Directly

​Reusing a Vendor Client Instance

​Using the Mock Driver

​Request Code Stays the Same

​See Also

Available Drivers

CurlDriver

GuzzleDriver

SymfonyDriver

Switching Drivers

Via Configuration

Via the Builder

Injecting a Driver Directly

Reusing a Vendor Client Instance

Using the Mock Driver

Request Code Stays the Same

See Also