The seam is one method

The whole contract is four parameters in, one value object out:

interface TransportInterface
{
    /**
     * @param array<string,string> $headers
     * @throws ConnectionException On network errors
     */
    public function request(string $method, string $url, array $headers = [], ?string $body = null): Response;
}

The Response is a final readonly value object carrying status, body, and lowercase-keyed headers, with json() and isSuccessful() helpers, and that is genuinely the whole seam; the transport owns connection concerns like timeouts, TLS, pooling, and redirect policy, while everything above it, the status-code-to-exception mapping that turns a 401 into AuthException and a 409 into ConstraintException, lives in the client and never sees cURL at all.

cURL by default, streams when you have to

The default is CurlTransport, which keeps a per-request handle pool keyed by host so sequential calls reuse warm connections, the right pattern here because a database client’s workload is sequential rather than concurrent, so curl_multi would buy nothing, and it enforces a 256 MB response cap so a buggy or malicious server cannot exhaust your memory, set advisory through CURLOPT_MAXFILESIZE against the Content-Length header and then enforced authoritatively by counting the bytes that actually arrived, and on PHP 8.5 it can opt into persistent share handles, which the previous article covered in detail. When ext-curl simply is not there, which still happens on stripped-down shared hosting builds in 2026, you drop to StreamTransport, the fallback built on PHP’s native stream wrappers:

use Visorcraft\MongrelDB\MongrelDB;
use Visorcraft\MongrelDB\Transport\StreamTransport;

$client = new MongrelDB(
    'http://127.0.0.1:8453',
    token: 'secret',
    transport: new StreamTransport(timeout: 10),
);

The stream fallback is honest about its limits: no keep-alive, no connection pooling, a fresh TCP setup per call, so latency climbs on chatty workloads, but the API your application code sees is identical, which is the entire point of the seam. One rule both shipped transports share is worth stating plainly, neither follows redirects, because a redirect target that is not your daemon would receive your Authorization header on a platter, and a transport that silently follows a 302 is a credential leak wearing a convenience feature’s clothes.

Bringing your own: tests, proxies, PSR-18

The case that pays for the interface immediately is testing, because a fake that returns canned responses is twenty lines and turns your whole data layer into something you can exercise without a daemon:

use Visorcraft\MongrelDB\Transport\Response;
use Visorcraft\MongrelDB\Transport\TransportInterface;

final class FakeTransport implements TransportInterface
{
    /** @var list<Response> */
    private array $queue = [];

    /** @var list<array{string, string, array, ?string}> */
    public array $requests = [];

    public function push(Response $response): void
    {
        $this->queue[] = $response;
    }

    public function request(string $method, string $url, array $headers = [], ?string $body = null): Response
    {
        $this->requests[] = [$method, $url, $headers, $body];

        return array_shift($this->queue)
            ?? new Response(500, '{"error":"no queued response"}');
    }
}

Push a 401 onto the queue and assert your code surfaces AuthException, push a 409 and assert the constraint path fires, and inspect $requests to verify the idempotency key header actually went out, all with zero sockets. The second case is the enterprise-shaped one, where outbound HTTP must pass through a proxy or carry credentials your application never sees, and there the right move is a PSR-18 bridge over whatever client the platform already standardized on:

use Psr\Http\Client\ClientExceptionInterface;
use Psr\Http\Client\ClientInterface;
use Psr\Http\Message\RequestFactoryInterface;
use Psr\Http\Message\StreamFactoryInterface;
use Visorcraft\MongrelDB\Exceptions\ConnectionException;
use Visorcraft\MongrelDB\Transport\Response;
use Visorcraft\MongrelDB\Transport\TransportInterface;

final class Psr18Transport implements TransportInterface
{
    public function __construct(
        private readonly ClientInterface $http,
        private readonly RequestFactoryInterface $requestFactory,
        private readonly StreamFactoryInterface $streamFactory,
    ) {}

    public function request(string $method, string $url, array $headers = [], ?string $body = null): Response
    {
        $request = $this->requestFactory->createRequest($method, $url);
        foreach ($headers as $name => $value) {
            $request = $request->withHeader($name, $value);
        }
        if ($body !== null) {
            $request = $request->withBody($this->streamFactory->createStream($body));
        }

        try {
            $response = $this->http->sendRequest($request);
        } catch (ClientExceptionInterface $e) {
            throw new ConnectionException($e->getMessage(), previous: $e);
        }

        $responseHeaders = [];
        foreach ($response->getHeaders() as $name => $values) {
            $responseHeaders[strtolower($name)] = implode(', ', $values);
        }

        return new Response($response->getStatusCode(), (string) $response->getBody(), $responseHeaders);
    }
}

Guzzle, Symfony HttpClient, or anything else with a PSR-18 front drops in through this shape, and the wiring stays a one-line change at construction. One caveat before you paste it into production: PSR-18 has no standard timeout API, so timeouts and retry policy live on the concrete client you inject, and if you leave Guzzle or Symfony HttpClient at its defaults a dead upstream will hang your request far longer than the thirty seconds the shipped transports give you.

use Visorcraft\MongrelDB\Database;
use Visorcraft\MongrelDB\MongrelDB;

$client = new MongrelDB('http://127.0.0.1:8453', token: 'secret', transport: $psr18);
$db = new Database(client: $client);

What belongs in the seam

The discipline that keeps this interface small is knowing what not to put in it, so a custom transport should return the raw status and body and let the client map errors, it should throw ConnectionException only when the network itself failed, it should refuse redirects rather than follow them, and it should never grow methods for queries or transactions, because the moment transport code learns about SQL the seam has leaked and you are back to curl_exec in the business logic with extra steps. We used to reach for a full HTTP abstraction library just to fake a database call in a unit test, which is how a three-method mock turned into a weekend; the modern equivalent is an interface narrow enough that the fake is smaller than the test that uses it, and that is the shape worth copying.

What a persistent share handle actually shares

A classic cURL share handle lets handles inside one request reuse DNS results, TLS session tickets, and the connection pool, which is what the client has always done internally with its per-request handle pool keyed by host. The persistent variant takes the same idea and lifts the lifetime, so the shared state survives the request and is waiting for the next FPM invocation that hits the same daemon; PHP deduplicates persistent share handles by their option set, which means creating one per client instance is cheap, because the second call hands you back the first handle rather than building a new one.

The three things worth sharing are DNS resolution, TLS sessions, and the connection pool itself, exposed as CURL_LOCK_DATA_DNS, CURL_LOCK_DATA_SSL_SESSION, and CURL_LOCK_DATA_CONNECT, and each one removes a different slice of the handshake tax. DNS sharing kills the resolver round trip, TLS session resumption kills most of the handshake, and connection-pool sharing kills the TCP setup entirely when an idle connection is still warm, which for a mongreldb-server sitting on loopback or one hop away is the difference between a query that costs two milliseconds and a query that costs two milliseconds wrapped in twenty milliseconds of ceremony.

Turning it on

The feature is off by default and opt-in, because a client library has no business silently carrying state across your requests, so you flip it with one constructor argument:

use Visorcraft\MongrelDB\Database;

// Sensible defaults: DNS + TLS sessions + connection pool
$db = new Database('http://127.0.0.1:8453', persistentSharing: true);

If you want to decide exactly what gets shared, pass an explicit list of CURL_LOCK_DATA_* constants at the transport layer instead:

use Visorcraft\MongrelDB\MongrelDB;
use Visorcraft\MongrelDB\Transport\CurlTransport;

// Share DNS only, keep everything else per-request
$transport = new CurlTransport(persistentSharing: [\CURL_LOCK_DATA_DNS]);
$client = new MongrelDB('http://127.0.0.1:8453', token: 'secret', transport: $transport);
$db = new Database(client: $client);

The defaults include CURL_LOCK_DATA_CONNECT, the connection-pool sharing option, only when the constant is defined, because it needs libcurl 7.67 or newer underneath; the client checks with defined() rather than trusting the PHP version number, since the version of PHP and the version of libcurl it was built against are two different facts.

The 8.4 fallback and the cookie guard

The client supports PHP 8.4 as its floor, and it cannot require a function that did not exist until 8.5, so the detection is a plain function_exists('curl_share_init_persistent') at the moment the share handle would be created. On 8.4 the option quietly degrades to the per-request pooling the client always had, no exception, no warning, and no behavior change, which is exactly how a version-gated feature should behave when the floor is one release behind.

One share option is rejected outright, and it is rejected at construction time rather than at first request: CURL_LOCK_DATA_COOKIE. PHP itself refuses the same option by throwing a ValueError, because cookies carried across requests would leak session state between unrelated callers, and a stateless database client has no use for cookies in the first place, so the client goes one step earlier and throws its own InvalidArgumentException the moment you build the transport. That guard deliberately does not depend on the 8.5 runtime API, which means it catches the mistake on 8.4 too, where the persistent handle would otherwise be skipped and the bad option would sit there looking harmless.

Where the win shows up, and where it does not

The honest tradeoff is that this is a latency feature, not a throughput feature, and it earns its keep wherever each request rebuilds the client from scratch: PHP-FPM serving many short requests against the same daemon is the canonical case, where the first query of each request used to pay full connection setup. Under FrankenPHP or a long-running worker the picture changes but does not disappear, because process lifetime and handle lifetime are different facts: if your client is bootstrapped once in worker scope and its cURL handles already survive the request boundary, the per-request pool was never the bottleneck and persistent sharing adds little, while a client instantiated per request inside a worker still pays the setup each time and still benefits, which is exactly the long-lived-SAPI shape PHP built the feature for; under a CLI script that runs one migration and exits, persistent sharing buys nothing at all, since there is no next request to inherit the state.

That is also why the default stays off, because the client cannot know which of those shapes it is running inside, and opting in is one boolean once you do know. The older me, the one who tuned KeepAlive on Apache 1.3 boxes and measured handshake overhead with tcpdump because nothing better existed, would have loved having this switch; the modern equivalent is a constructor argument and a runtime check, and the result is the same as it ever was, which is that the fastest connection is the one you do not have to set up again.