Skip to main content
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 nameLibraryPackage
curlPHP cURL extensionBuilt-in (no dependency)
guzzleGuzzle HTTPguzzlehttp/guzzle
symfonySymfony HttpClientsymfony/http-client
(mock)Built-in test doubleBuilt-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.

​
See Also