Asymmetric visibility and the shape of the client

The Database class is the front door of the client, and it carries internal state that callers should read but never set: the base URL, the default transport, the current session token, and a few cached metadata objects. Before PHP 8.4, the honest choices were either public readonly properties, which expose the value for reading but still let anyone assign it during construction if the constructor is inside the class, or a pile of private properties with boilerplate getters that exist only to say “this is not for you.” Asymmetric visibility fixes this by letting the property be public private(set), which means the world can read it and only the class can write it after construction, so internal mutation in methods like withToken still works while external callers are frozen out. This is exactly what a Database object needs.

final class Database
{
    public function __construct(
        public private(set) string $baseUrl,
        public private(set) TransportInterface $transport,
        private ?string $sessionToken = null,
    ) {}

    public function withToken(string $token): static
    {
        $clone = clone $this;
        $clone->sessionToken = $token;       // private property, fine here
        return $clone;
    }
}

This is not a cosmetic win; it is a stability win, because the public surface of the object now matches the contract we actually want, and there is no private getter a maintainer can forget to update when they rename a field. The client has a lot of value objects, Column, Table, ResultSet, QueryPlan, and asymmetric visibility keeps them honest without turning the source code into Java.

Readonly properties and the transport configuration

PHP 8.1 gave us readonly properties, PHP 8.2 added readonly classes, and by PHP 8.4 they are mature enough that we use them as the default for any object that is effectively a record. A transport configuration, for example, is a bundle of timeouts, retry counts, and header defaults that should be immutable once constructed, because a live request is already in flight and changing its timeout halfway through is a great way to get a bug nobody can reproduce. The combination of a readonly class and constructor property promotion means the entire configuration object collapses to a few lines.

readonly class TransportConfig
{
    public function __construct(
        public int $connectTimeoutMs = 5000,
        public int $requestTimeoutMs = 30000,
        public int $maxRetries = 2,
        public array $defaultHeaders = [],
    ) {}
}

Readonly classes are not a free lunch, because clone becomes awkward and you need a with method or clone plus reassignment if you want a modified copy, but for transport config that is exactly what we want: the object is a snapshot, not a living document, and the database client treats it that way.

Array find functions and query-plan navigation

PHP 8.4 adds array_find, array_find_key, array_any, and array_all, and these are the kind of functions that sound trivial until you write the code that used to do the same thing with a loop and a flag. We hit them constantly when walking query-plan metadata, because a plan node is a nested array of operators, and we need to know whether any operator touches a vector index, or whether all operators are point lookups, or which node is the first one that references a JSON column. The old way was array_filter(...)[0] ?? null for find, and a hand-rolled foreach with return false for any/all, which is fine once but becomes noise when it appears twenty times in a client.

// Before: array_filter gives you all matches, then you take the first.
$vectorNode = array_filter($planNodes, fn($n) => $n['op'] === 'ann')[0] ?? null;

// After: intent is explicit, no allocation of the full filtered array.
$vectorNode = array_find($planNodes, fn($n) => $n['op'] === 'ann');

$hasVectorScan = array_any($planNodes, fn($n) => $n['op'] === 'ann');
$allPointLookups = array_all($planNodes, fn($n) => $n['op'] === 'point');

The performance difference is small for most client workloads, but the readability difference is large, and a readable client is one that gets more contributions and fewer misuses.

Property hooks and lazy hydration

PHP 8.4 introduces property hooks, which let you attach get and set logic directly to a property declaration without writing a backing field and a separate accessor. We use them for lazy hydration on the ResultSet rows, where each row is a thin wrapper over a raw JSON array until the caller actually asks for a typed value. The hook is not magic; it is just a place to put the conversion logic so that the object remains a plain object while still doing the work on demand.

final class Row
{
    public function __construct(private array $data) {}

    public string $name {
        get => $this->data['name'] ?? ''
    }

    public int $id {
        get => (int) ($this->data['id'] ?? 0)
    }

    public object $document {
        get => json_decode($this->data['document'] ?? '{}')
    }
}

The tradeoff is that property hooks can hide work, and a getter that does JSON decoding on every access is a trap if you call it in a loop. We keep the hooks thin and cache the heavier conversions in the constructor, so the hook is mostly a type-safe doorway, not a compute sink.

ext-curl in PHP 8.4: the HTTP foundation

The default transport is cURL, because cURL is the only HTTP client that is present on enough hosts that we can assume it exists, and PHP 8.0 gave us the OO CurlHandle and typed exceptions we use in the wrapper, with PHP 8.4 refinements to default encoding behavior keeping the implementation small. The client detects cURL at runtime, falls back to streams if it is missing, and lets you inject a PSR-18 or Symfony HttpClient adapter if you want something else, but the cURL path is the one we optimize for because it is the one that exists everywhere.

final class CurlTransport implements TransportInterface
{
    private \CurlHandle $handle;

    public function __construct(private TransportConfig $config)
    {
        $this->handle = curl_init();
        curl_setopt($this->handle, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($this->handle, CURLOPT_FOLLOWLOCATION, false);
        curl_setopt($this->handle, CURLOPT_CONNECTTIMEOUT_MS, $config->connectTimeoutMs);
        curl_setopt($this->handle, CURLOPT_TIMEOUT_MS, $config->requestTimeoutMs);
    }

    public function request(string $method, string $url, string $body = ''): Response
    {
        curl_setopt($this->handle, CURLOPT_CUSTOMREQUEST, $method);
        curl_setopt($this->handle, CURLOPT_URL, $url);
        curl_setopt($this->handle, CURLOPT_POSTFIELDS, $body);

        $raw = curl_exec($this->handle);
        if ($raw === false) {
            throw new ConnectionException(curl_error($this->handle));
        }

        return Response::fromCurl($this->handle, $raw);
    }
}

The cURL handle is reused for the lifetime of the transport object, which is better than creating a new handle per request, but it is not yet true connection persistence across the whole process, which is where PHP 8.5 comes in.

PHP 8.5: the pipe operator and persistent cURL sharing

PHP 8.5 shipped in November 2025 with the pipe operator, persistent cURL share handles, and clone with modifications. These are not theoretical wins for the client; they are the features that let us simplify the code we already have.

The pipe operator lets you write $value |> $this->normalize(...) |> $this->send(...) instead of nesting calls right-to-left or assigning to a temporary variable. For a client that chains encoding, validation, and request building, the pipe operator makes the middle of the call stack readable without turning it into a fluent builder.

// PHP 8.5
$response = $requestBody
    |> json_encode(...)
    |> $this->transport->request('POST', $this->baseUrl . '/sql', ...)
    |> Response::fromRaw(...);

Persistent cURL share handles are the bigger deal. In PHP 8.4, the CurlTransport reuses a single CurlHandle for the lifetime of the transport object, but each transport object still starts a fresh TCP handshake. PHP 8.5 lets share handles persist across multiple PHP requests, which means an FPM or FrankenPHP worker can keep a warm connection to the database server instead of reopening it. We are wiring this into the transport layer so that the same CurlTransport can attach to a process-wide share handle when the runtime offers one, and the fallback for PHP 8.4 stays exactly the same.

clone with modifications is the last piece. Readonly classes are great for value objects, but changing one field used to mean either a constructor spread with get_object_vars or a hand-written with method. PHP 8.5’s clone($this, ['field' => $value]) collapses that to a single expression, so the withAlpha style of method becomes small enough that we no longer need helper traits to keep it readable.

// PHP 8.5
public function withAlpha(int $alpha): self
{
    return clone($this, ['alpha' => $alpha]);
}

The backward-compatibility tradeoff

The client currently supports PHP 8.4 as its minimum, and PHP 8.5 is now stable and widely available in the distributions we track. Runtime features like persistent cURL share handles can be guarded with function_exists and curl_share_init, so the same package can run faster on PHP 8.5 without breaking PHP 8.4, but syntax features like the pipe operator cannot be runtime-guarded. That means the pipe operator and clone with modifications will arrive as part of a major version bump that raises the minimum to PHP 8.5, while the cURL sharing lands as a backward-compatible performance improvement for anyone already on 8.5.

The modern equivalent

In 2010, a PHP database client would have been a thin wrapper around mysql_connect and the main challenge was escaping strings correctly. In 2026, the challenge is building a client that is safe, typed, and deployable without native code, and PHP 8.4 is the first version where that feels natural rather than defensive. PHP 8.5 is now the version that removes the remaining reasons a database client would need to touch anything outside Composer, not by adding one big feature, but by making the small workarounds unnecessary. That is the goal, and the language is finally moving in the same direction.

What pure PHP actually means in 2026

The phrase “pure PHP” has accumulated some baggage over the years, partly because PHP’s early reputation as a slow interpreted language made “pure PHP” sound like “slow PHP,” and partly because the PHP ecosystem spent a decade leaning on C extensions as proof of seriousness. Neither of those associations is accurate anymore, and the PHP client does not trade on either of them.

What pure PHP means here is concrete: the entire client is written in PHP 8.4 syntax, it ships as a Composer package, it has no native code dependencies, and it does not call any function that requires a C extension. HTTP is handled by curl via ext-curl when PHP 8.5 persistent handle sharing is available (PHP 8.5 being the newer of the two runtimes, so the stream-context path remains the common case for now), and by regular stream contexts when it is not; both are in the standard PHP distribution and neither requires a compile step. JSON is handled by json_decode and json_encode, which have been built into PHP since 5.2 and have been reliably fast since 7.0. There is no binary .so to load, no phpize to run, no ABI version to match against the server’s architecture, and no risk that pecl install mongrel fails because your host has disabled exec() in php.ini.

The install experience

composer require visorcraft/mongreldb-php

That is the entire install. The package lands in vendor/, autoloading is configured, and you can instantiate the client in one line:

use Visorcraft\MongrelDB\Client;

$db = new Client('https://db.example.com', token: getenv('MONGRELDB_TOKEN'));

No bootstrap scripts, no extension loading in php.ini, no running mongreldb-php-setup as a post-install script. The Composer package ships the client, the type stubs, and the error hierarchy; you require the package and you are talking to the database.

Why HTTP is the right transport for a pure PHP client

The PHP client could have used a Unix socket or a raw TCP protocol with a binary framing layer, and in a pure-server context those choices would make sense for latency. But PHP is not a long-running process by default; PHP-FPM spawns a process per request or per few requests, and the typical PHP application opens a fresh database connection on every web request, closes it at the end, and does not reuse it unless you have gone out of your way to implement connection pooling. An HTTP client reuses keep-alive connections across requests in the same process lifetime, and when PHP-FPM recycles a worker the next request starts fresh, which is the same behavior the database would have expected anyway.

HTTP also means the PHP client works through every HTTP-aware proxy, load balancer, and API gateway that already exists in your infrastructure, and it means TLS termination happens at the normal layer rather than requiring a special database-facing certificate setup. You are already doing HTTP for every other external service your application calls; the database does not need to be special.

What you give up and what you do not

You give up the single-digit-microsecond in-process path, because HTTP adds a header processing layer that a raw TCP protocol would not have (a few hundred microseconds of framing overhead per operation, not a category shift), and you give up the ability to operate without a network path to the server, which is the embedded-database use case that MongrelDB handles differently through its Kit SDK. For a PHP web application that talks to a mongreldb-server over a LAN or a VPC, those tradeoffs are not on the critical path; the query execution time inside the database dominates the HTTP overhead by two orders of magnitude.

You do not give up type safety, because the client speaks a typed wire format and deserializes responses into PHP native types with a full exception hierarchy that maps HTTP status codes to domain exceptions, so a 404 from the server becomes a NotFoundException in your application code rather than a generic runtime error. You do not give up connection pooling in the PHP-FPM context, because the client uses persistent curl handles when PHP 8.5 is available, which means the underlying TCP connection is reused across requests in the same worker process without the TLS handshake cost on every page load. And you do not give up SQL surface area, because the wire format carries the same query plans and constraint semantics as the Kit SDK and the Rust core, so the PHP client is not a reduced-surface wrapper; it is the full client in a different transport.

Who benefits from this in practice

The obvious answer is the shared-hosting developer who is on a cPanel machine with no root access and no ability to run phpize, and that answer is correct but incomplete. The more interesting case is the CI pipeline: a composer require in a Dockerfile that uses php:cli as its base image does not need any system package installed beyond the PHP runtime and Composer itself, which means your test matrix can cover PHP 8.4 and PHP 8.5 on the same Docker image without an extension compilation step slowing down every build. The pure PHP client makes your database client a first-class Composer dependency rather than a system-level install, and that distinction matters when your CI minutes are metered and your container build time is on the critical path.