DEV Community: Dusan Malusev

ScyllaDB PHP Driver 1.4.0: the extension is pure C23 now

Dusan Malusev — Mon, 13 Jul 2026 21:21:53 +0000

The ScyllaDB PHP driver is not a C++ extension anymore. As of 1.4.0 it's pure C23, the ZendCPP template layer we leaned on for the object embed and allocate pattern is deleted, and the build no longer needs a C++ compiler at all. Every hand-written .cpp file is a .c file now (71 of them), the descriptor generator emits .c, and CMake builds with c_std_23 and nothing else. That's the biggest change to how this extension is built since we forked it for PHP 8.0.

This is also the release where a plan I opened back in 2023 finally landed. PR #50 laid it out: rewrite the src/Cluster directory to be more maintainable, use Zend Fast Argument Parsing, remove some memory allocations, and add .stub.php files that generate the C headers so nobody has to hand-maintain Zend arginfo by hand. 1.4.0 is that plan finished, and a lot more that grew out of it.

The things you'll actually feel: persistent session connect() doesn't allocate a 200-character key string on every call anymore, and the minimum PHP is now 8.3 (8.2 is gone). Nothing in your application code changes, this is almost all under the surface.

The .stub.php Build

The idea from PR #50 was small. Instead of writing ZEND_BEGIN_ARG_INFO_EX blocks by hand and keeping them in sync with the actual method bodies, write the signature once in a .stub.php file and generate the C arginfo from it. In v1.4.0 that's the whole build. There are 75 .stub.php files now, and each one is just the PHP signature of the class:

// src/Keyspace.stub.php
interface Keyspace {
    public function name(): string;
    public function replicationClassName(): string;
    /** @return array<string, mixed> */
    public function replicationOptions(): array;
    public function hasDurableWrites(): bool;
    /** @return Table|false */
    public function table(string $name): Table|false;
    public function aggregate(string $name, mixed ...$types): Aggregate|false;
}

At build time CMake runs gen_stub.php (vendored from PHP 8.5's build/gen_stub.php, with two small patches) and writes the _arginfo.h next to the source. We stopped committing the generated headers, there are none in git anymore (75 of them got deleted from tracking), they're regenerated against whatever PHP version you're compiling against. That last part matters, PHP 8.3 and 8.5 do not emit identical arginfo, and now we don't pretend they do.

The second half is class registration. The old MINIT had one giant hand-maintained block, 98 php_driver_define_*() calls in src/php_driver.cpp, order-dependent and a merge-conflict magnet:

// src/php_driver.cpp (v1.3.17) - the old registration block
php_driver_define_Value();
php_driver_define_Numeric();
php_driver_define_Bigint();
php_driver_define_Cluster();
php_driver_define_DefaultCluster();
php_driver_define_ClusterBuilder();
// ... 92 more, in exactly this order or it breaks

All of that is one line now:

// src/php_scylladb.c - MINIT
php_scylladb_class_registry_minit();

Every class self-registers with a descriptor via a __attribute__((constructor)) that appends it to a linked list when the .so loads, before MINIT runs. At MINIT we walk the list, topologically sort by parent class, resolve dependencies, and register in the right order. If a parent is missing or you've made a cycle, it fails loudly at MINIT and names the class that broke it. (I wrote the whole descriptor mechanism up on its own if you want the deep dive, self-registering class descriptors, deleting MINIT boilerplate in a PHP extension.)

A second generator, gen_class_descriptor.php (about 515 lines), reads the same .stub.php and emits the descriptor .c with the object handlers wired up. So adding a class is now: write the stub, write the method bodies, list both files in the module CMake, and that's it. No touching php_scylladb.c, no touching a central registration list.

And this also let us delete 16 pure-interface .cpp files (Cluster, Session, Statement, Future, Rows, and so on). They had no method bodies, just registration, so the generator makes them from the stub alone.

Persistent Sessions Don't Allocate Anymore

Here's the change most people running under PHP-FPM will actually feel. Persistent sessions cache the underlying CassCluster in EG(persistent_list) so it survives across requests. To find the cached entry, the old code built a key string out of every cluster setting, on every build(), hit or miss:

// src/Cluster/Builder.cpp (v1.3.17) - key built on every call
cluster->hash_key_len = spprintf(
    &cluster->hash_key, 0,
    PHP_DRIVER_NAME ":%s:%d:%d:%s:%d:%d:%d:%s:%s:%d:%d:%d:%d:%d:%d:%d:%d:%d:%d:%d:%d:%d",
    ZSTR_VAL(self->contact_points), self->port, self->load_balancing_policy,
    SAFE_ZEND_STRING(self->local_dc), /* ...28 fields... */);

zval *le;
if (PHP5TO7_ZEND_HASH_FIND(&EG(persistent_list), cluster->hash_key,
                           cluster->hash_key_len + 1, le) &&
    Z_TYPE_P(le) == IS_RESOURCE) {
    cluster->cluster = (CassCluster *)Z_RES_P(le)->ptr;
    return; /* cache hit - but we already paid for the string */
}

That's a spprintf into emalloc'd memory, then a zend_string_init (another allocation), then a hash over a 200-plus character string and a memcmp to confirm. Every request. Even when the answer was sitting in the cache the whole time.

v1.4.0 mixes the same fields into a uint64_t FNV-1a fingerprint inline, no allocation, and looks it up as an integer key:

// src/Cluster/Builder.c (v1.4.0) - no allocation on the hot path
zend_ulong h = php_scylladb_cache_key_init();
h = php_scylladb_cache_key_mix_cstr(h, PHP_SCYLLADB_NAME);
h = php_scylladb_cache_key_mix_zstr(h, self->contact_points);
h = php_scylladb_cache_key_mix_int(h, self->port);
/* ...28 fields... */
cluster->cache_key = h;

zval *le = zend_hash_index_find(&EG(persistent_list), h);
if (le != nullptr && Z_TYPE_P(le) == IS_RESOURCE &&
    Z_RES_P(le)->type == php_le_php_scylladb_cluster()) {
    cluster->cluster = (CassCluster *)Z_RES_P(le)->ptr;
    return; /* cache hit - and we allocated nothing */
}

The lookup is zend_hash_index_find with an integer compare instead of zend_hash_find walking a long string. The mix_zstr and mix_cstr helpers append a separator byte between fields so ("ab","c") and ("a","bc") can't collide into the same key. It's 64-bit FNV-1a, collisions across the few thousand entries a worker holds are not something you'll hit.

One C23 detour worth mentioning here, wave 2 tried making the FNV offset and prime (and the default consistency) static constexpr instead of #define, it reads nicer and it's typed. It didn't stick. CI clang-tidy runs without -std=c23 and choked on constexpr, so those went back to #define. C23 is only as usable as your lint toolchain lets it be, so keep an eye on that if you're modernizing a C codebase, the compiler saying yes doesn't mean the rest of your tooling does.

Net result, zero zend_string allocations on the persistent-cache hot path. There's a memory-safety bonus too, the old char* key was aliased between the cluster and the session, so unset($cluster) before $session->prepare() could efree it out from under the session (that was the use-after-free in issue #128). Integer keys don't alias, so that whole class of bug is just gone.

You can see the difference on your own box. The measurement is simple, loop build()+connect() with persistent sessions on and off, and watch the peak memory:

function bench(bool $persistent, int $n): array {
    $mem = memory_get_peak_usage(true);
    $t0  = hrtime(true);

    for ($i = 0; $i < $n; $i++) {
        $session = Cassandra::cluster()
            ->withContactPoints('127.0.0.1')->withPort(9042)
            ->withPersistentSessions($persistent)
            ->build()
            ->connect();
        $session->execute(new \Cassandra\SimpleStatement('SELECT now() FROM system.local'));
        $session->close();
    }

    return [
        'per_op'     => ((hrtime(true) - $t0) / 1e9) / $n,
        'mem_growth' => memory_get_peak_usage(true) - $mem,
    ];
}

$off = bench(false, 200);   // persistent OFF: fresh CassCluster + key string every build
$on  = bench(true, 200);    // persistent ON:  fingerprint lookup, no allocation on the hit

The wall-clock moves a little, but the mem_growth column is where the fingerprint change actually shows. The persistent path stops allocating a key string per call, so its peak barely moves while the non-persistent one climbs. The full script (prepared vs simple statements and batch inserts too) is in the repo under benchmarks/persistent_sessions_bench.php.

Also while we were in there, every zend_parse_parameters call in the scalar types (Uuid, Inet, Blob, the numerics) moved to the FastZPP Z_PARAM_* macros, and getThis() became ZEND_THIS. 153 parse sites converted, zero old-style zend_parse_parameters left, CI greps for it so it stays that way.

The Audits

Two audits ran against the whole extension and both left tracking docs in docs/. The memory-leak one worked through the extension and fixed:

borrowed-pointer leaks in the Builder setters
missing cass_future_free on error-return paths in execute() and paging
a missing UNREGISTER_INI_ENTRIES() at shutdown
get_gc handlers that didn't delegate to zend_std_get_gc, so cycles through object properties never got collected

But the correctness and ZTS audit is the scarier list. One of them, in ExecutionOptions, was a && that should have been ||:

// src/ExecutionOptions.cpp - CORR-001
-  if (Z_TYPE_P(retry_policy) != IS_OBJECT &&
+  if (Z_TYPE_P(retry_policy) != IS_OBJECT ||
         !instanceof_function(Z_OBJCE_P(retry_policy), php_scylladb_retry_policy_ce))

With the wrong operator a non-object retry_policy skipped the type check and walked straight into instanceof_function on garbage.

Another one was strncmp(name, "keyspace_name", name_length) used for schema lookups, which is a prefix match, so "keyspace_name_2" matched "keyspace_name". Fixed to an exact-length memcmp.

Then a batch of thread-safety fixes for people running ZTS. The log callback used php_localtime_r and PHP_EOL which aren't safe to touch from libuv's worker threads, those are POSIX localtime_r and a literal \n now, and the log lifecycle moved from per-thread init to process init.

We also marked the 29 classes that hold a raw Cass* pointer as @not-serializable, because the default unserialize would hand you an object with an uninitialized native handle, which is another use-after-free waiting to happen.

How Much of This Was AI

I'll be straight about this, a large part of 1.4.0 was written with AI (Claude Code), and it landed with an accuracy I did not expect going in. Not the design calls, those are mine, but the wide mechanical work is exactly what these tools are good at. Renaming 667 identifiers and 58 macros from php_driver_* to php_scylladb_* across 146 files without missing one. Converting 153 zend_parse_parameters sites to FastZPP. Porting 71 files from C++ to C23. Doing that by hand is a week of tedium and a real chance of a typo that compiles fine and then breaks at runtime.

The audits are the part that surprised me most. That correctness list up above was run as a checklist against the whole extension, every finding numbered, every one with a tracking doc in docs/, a fix, and a test. The &&-that-should-be-|| in ExecutionOptions, a human doing a tired review at the end of the day walks straight past that. A pass that reads every single conditional and asks "is this the operator you meant" does not.

But none of it shipped on trust, and that's the part that matters. Every change is behind the test suite, and the suite runs under ASan, UBSan and TSan in CI across 8.3, 8.4 and 8.5, NTS and ZTS. AI hallucinates, I've watched it confidently do something that makes no sense, so the rule was simple, if it can't pass the sanitizers and the Pest tests it doesn't merge, doesn't matter who or what wrote it. The accuracy is real, but it's accuracy inside a setup that catches the misses, not accuracy you take on faith.

Issue #108, Two Years Late

Issue #108 sat open for nearly two years. The report was simple, passing an explicit null as the $options argument to prepare(), execute(), executeAsync() or prepareAsync() threw an InvalidArgumentException, even though the signature says array|ExecutionOptions|null. Under the hood Z_PARAM_ZVAL hands you a non-null IS_NULL zval, so the if (options) guard walked into the type check and rejected it. The fix is one macro, Z_PARAM_ZVAL_OR_NULL, so an explicit null collapses to nullptr and behaves like leaving the argument off. That's the whole thing.

Two years, for that. And while I was validating the fix under AddressSanitizer, a worse bug fell out of it, a cycle-collector use-after-free. The collection and value types keep their data in the C struct, but their get_gc handlers fell back to zend_std_get_gc, which rebuilds object->properties on every call. The collector runs get_gc several times per pass, so it decremented one set of child refcounts and re-incremented a freshly rebuilt set, corrupting the counts and freeing a shared CassDataType early (a crash on teardown). Set, Map, Collection, Tuple, UserTypeValue, the Cassandra\Type\* classes, Decimal, Varint and the cluster Builder all got a real zend_get_gc_buffer over their actual zvals. There's a test-asan job now that runs the whole suite under ASan, red before the fix and green after, because a plain run doesn't reliably crash (the fault is heap-layout dependent).

I'm not proud that #108 took me almost two years. A one-macro parameter fix should not sit open that long, and that is not the behavior of a maintainer who wants his project to survive and keep moving. I'm the only one on it, mostly in my free time, and for a long stretch that meant the backlog just sat there. People who hit #108 worked around it or walked.

So that changes now, and AI is how. The same tooling that made this release possible, the mechanical refactors, the audits that found the operator bug, the ASan job that caught this GC crash, is what lets one person actually keep up with issues and features instead of drowning in them. The trunk-and-backport setup below is the other half of it. I'm going to be addressing things more than I have been.

A Third Backend

v1.4.0 adds a third driver backend, scylla-rust, which is ScyllaDB's cpp-rs-driver (the Rust core with a C-compatible API). You pick the backend at configure time:

# cmake/FindCPPDriver.cmake
set(PHP_SCYLLADB_BACKEND "scylla-cpp" CACHE STRING
    "C/C++ driver backend: cassandra | scylla-cpp | scylla-rust")

The default is still scylla-cpp (the ScyllaDB cpp-driver), so nothing changes unless you ask for it. scylla-rust is experimental and opt-in, it's in the CI matrix but allowed to fail, and it's not in the released binaries. A few things don't work on it yet, withMaxConnectionsPerHost() is a no-op and some schema-introspection calls come back empty (there's a compat shim that null-returns the six symbols the Rust driver doesn't implement, and the call sites null-check for it). If you want to try it, build it yourself with scripts/compile-cpp-rs-driver.sh. If you don't, you'll never notice it exists.

But don't ship it yet. scylla-rust is not production-ready, it's a preview, treat it as something you benchmark and file bugs against, not something you point a live app at. The default stays scylla-cpp for exactly this reason.

PHP Version Lifecycle

Minimum PHP is 8.3 now, 8.2 is dropped. composer.json went from ^8.2|^8.3|^8.4|^8.5 to ^8.3|^8.4|^8.5. If you're stuck on 8.2, pin to a 1.3.x release (the tags aren't going anywhere), that's your line.

The test matrix runs every supported version, both thread modes, against multiple backends:

php	thread modes	backends tested
8.3	NTS, ZTS	scylladb, cassandra, scylla-rust*
8.4	NTS, ZTS	scylladb, cassandra, scylla-rust*
8.5	NTS, ZTS	scylladb, cassandra, scylla-rust*

* scylla-rust is allowed to fail and is not in the release artifacts.

PHP 8.5 is a first-class target, the lint and clang-tidy reference build is DebugPHP8.5NTS and the vendored gen_stub.php comes from 8.5. For PHP 8.4 forward we shim zend_register_internal_class_with_flags on older versions so the stub-generated registration compiles everywhere. The plan going forward is boring on purpose, track the current PHP release, drop the oldest once it goes security-only, and keep the arginfo generated per-version so a new PHP doesn't turn into a scramble.

Where the Branches Go Now

The repo reorganized around this release, and if you track a branch instead of a release tag it'll affect you. The old 1.3.x branch is gone. There are three long-lived branches now: trunk is the default and where all new work lands first, v1.x is the maintenance line for the released 1.x series, and v2.x is the next major, under active development and not shipped yet.

Every PR opens against trunk. Fixes reach the release lines by backport, not by targeting them directly. It's automated, you put a backport/1.x or backport/2.x label on the PR and the bot (korthout/backport-action, SHA-pinned) cherry-picks the merged commit onto v1.x or v2.x and opens a [Backport ...] PR. Clean cherry-pick and it's ready for review, a conflict and it still opens the PR with the markers and comments the manual git steps. This #108 fix is the first thing going down that path to v1.x.

If your CI or your composer.json points at the 1.3.x branch (the dev-1.3.x style constraint), move it to a tagged release (^1.4) or to v1.x. The tags don't move, v1.3.17 and everything before it is still right where it was, it's only the branch that's gone. So this is the one breaking change in 1.4.0 that isn't code, it's where you pull from.

Where to Start

On PHP 8.3 or newer:

pie install codelieutenant/scylla-driver
# then build the extension for your PHP (CMake preset, or pecl/pie)

Turn on persistent sessions if you're running under FPM (->withPersistentSessions(true)), that's the path that got faster. Point the benchmark from earlier at your 127.0.0.1:9042 and watch the peak-memory column more than the clock, the fingerprint change is about not allocating, not about raw CPU, so that's where it shows...

Streaming journald logs to the browser with SSE

Dusan Malusev — Fri, 10 Jul 2026 21:23:40 +0000

I got tired of SSHing into the box every time I shipped something, just to watch the logs come up. So I wanted a page in the admin panel where the lines scroll past as they happen, no dashboard, no Grafana, just the raw tail. The surprising part was how little I had to build for it, most of the pieces were already sitting on the server waiting for me to connect them.

Here's the whole idea. The app writes JSON to stdout, systemd grabs that stdout and drops every line into the journal, and journalctl can follow the journal and hand the lines back live. All three of those already exist on an Ubuntu box. So the "live log viewer" is really just me spawning journalctl on the server and piping its output to the browser over an EventSource, which is a lot less code than it sounds like.

journald is boring and well understood. SSE is boring and well understood (it's been in browsers since about 2011). Nobody gets excited about either one on its own. But snap the two together and you get a real-time log tail with no agent, no log shipper, no vendor, and nothing new to keep alive. Two defaults meeting each other and pretending to be a feature.

Systemd thing

People have opinions about systemd. Some of them are that you should avoid every part of it that you can, run your own supervisor, ship logs somewhere with your own daemon, and treat journald as a thing to route around. That's a fine hobby if you have the time for it. I don't. The box boots, systemd starts my unit, and when the unit writes to stdout the line ends up in the journal without me configuring anything. Being a purist here costs real hours and buys me a philosophy. Being pragmatic costs nothing and buys me a log tail.

So this is the pragmatic path. If you're on a distro where journald is the default (Ubuntu, Debian, Fedora, most of them now) the setup below is basically free.

Getting logs into the journal

Here is the part most people overcomplicate. You do not "set up journald". You do not open a socket to it or pull in a library. You write to standard output, and if your process is a systemd service, systemd is already reading your stdout and stderr and writing every line into the journal tagged with your unit name.

My unit is about as plain as it gets:

# /etc/systemd/system/dusanmalusev-dev.service
[Unit]
Description=dusanmalusev.dev
After=network.target

[Service]
ExecStart=/usr/bin/node /srv/dusanmalusev-dev/build/index.js
WorkingDirectory=/srv/dusanmalusev-dev
Restart=always
User=www-data
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target

// src/lib/server/logger.ts
const stdout = pino.destination({ dest: 1, sync: false });


So each journal entry's `MESSAGE` field is a full JSON object, `{"level":30,"time":1720...,"msg":"request completed",...}`. That matters later, because it means I don't need journald's own timestamp or metadata. My structured fields are already inside the message.

Why bother with the journal at all instead of a file? A few reasons that add up. The journal is structured (every entry has fields you can query on, not just a blob of text), it rotates itself by size and age so I never touch logrotate, it survives across restarts, and I can already ask it questions from the shell without grep gymnastics:

bash
journalctl -u dusanmalusev-dev.service -f # follow live
journalctl -u dusanmalusev-dev.service --since "1 hour ago"
journalctl -u dusanmalusev-dev.service -p err # errors and worse
journalctl -u dusanmalusev-dev.service -o json # structured out


That last flag is the one that unlocks everything else. `-o json` (and its lighter sibling `-o cat`) turn the journal into something a program can parse, not just something a human can read.

## reading the journal back out

To follow the log live I spawn `journalctl` and read its stdout line by line. The flags that matter are `-f` (follow), `-n 0` (don't dump history, I only want new lines), and `-o cat` (print just the `MESSAGE` field). Since my MESSAGE is already pino JSON, `-o cat` hands me exactly the JSON I want with no journal wrapper to peel off.

typescript
// src/lib/server/admin/logs.ts (followLogs)
const child = spawn('journalctl', [
'-u', unit,
'-o', 'cat', // just the MESSAGE field, which is our pino JSON
'-f', // follow
'-n', '0', // no backlog, only new lines from now
'--no-pager'
]);

let buf = '';
child.stdout?.setEncoding('utf8');
child.stdout?.on('data', (chunk: string) => {
buf += chunk;
let idx;
while ((idx = buf.indexOf('\n')) !== -1) {
const line = buf.slice(0, idx);
buf = buf.slice(idx + 1);
if (!line) continue;
const parsed = parseLine(line);
if (!parsed) continue;
const ev = toStreamEvent(parsed);
if (passesFilter(ev, filter)) onEvent(ev);
}
});


The buffering there is the one thing you can't skip. `data` events don't arrive on line boundaries, a single chunk can be half a line, or three lines, or a line plus a fragment of the next. So I accumulate into `buf` and only cut on `\n`, keeping whatever partial line is left for the next chunk. Get this wrong and you'll spend an afternoon wondering why one log line in fifty is truncated JSON.

Parsing is forgiving on purpose. Most lines are pino JSON, but startup banners and stray stderr traces aren't, and I'd rather show those than drop them:

typescript
// src/lib/server/admin/logs.ts (parseLine)
function parseLine(line: string): LogLine | null {
try {
const obj = JSON.parse(line) as Record;
const time = typeof obj.time === 'number' ? obj.time : Date.now();
const level = typeof obj.level === 'number' ? obj.level : 30;
const msg = typeof obj.msg === 'string' ? obj.msg : '';
return { time, level, levelName: LEVEL_NAME[level] ?? String(level), msg, raw: obj };
} catch {
// Non-JSON line (a stderr trace or startup banner). Surface it as
// info-level with the raw text so the user still sees it.
const trimmed = line.trim();
if (!trimmed) return null;
return { time: Date.now(), level: 30, levelName: 'info', msg: trimmed, raw: { msg: trimmed } };
}
}


The filtering (`level`, `contains`) runs server-side before anything goes out on the wire. A client watching only errors shouldn't make the server serialize and send every debug line just to have the browser throw it away.

## the SSE endpoint

Server-Sent Events is the right transport here and WebSockets would be the wrong one. The data goes one direction (server to browser), it's text, and I want automatic reconnection without writing any of it. That's the exact shape SSE was designed for. The wire format is almost insultingly simple, you write `event: <name>` and `data: <json>` and a blank line, and the browser's `EventSource` does the rest.

In SvelteKit the endpoint is a `GET` that returns a `ReadableStream` with the `text/event-stream` content type. `followLogs` pushes each parsed line into the stream as a `log` event:

typescript
// src/routes/admin/logs/stream/+server.ts
export const GET: RequestHandler = async (event) => {
requireAdmin(event);

const encoder = new TextEncoder();
let stopFollow: (() => void) | null = null;
let heartbeat: ReturnType<typeof setInterval> | null = null;

const stream = new ReadableStream<Uint8Array>({
    start(controller) {
        const send = (name: string, payload: unknown) => {
            try {
                controller.enqueue(
                    encoder.encode(`event: ${name}\ndata: ${JSON.stringify(payload)}\n\n`)
                );
            } catch {
                /* controller closed */
            }
        };

        const handle = followLogs(
            { level, contains },
            (ev) => send('log', ev),
            (err) => send('error', { message: err.message })
        );
        stopFollow = handle.stop;

        send('ready', { source: handle.source, available: handle.available });

        // keeps idle-killing proxies (nginx / Cloudflare) from cutting us off
        heartbeat = setInterval(() => {
            try {
                controller.enqueue(encoder.encode(`: ping\n\n`));
            } catch {
                /* noop */
            }
        }, 25_000);
    },
    cancel() {
        stopFollow?.();
        if (heartbeat) clearInterval(heartbeat);
    }
});

return new Response(stream, {
    headers: {
        'content-type': 'text/event-stream; charset=utf-8',
        'cache-control': 'no-store, no-transform',
        'x-accel-buffering': 'no',
        connection: 'keep-alive'
    }
});

};


Three lines in there are the difference between "works on my laptop" and "works behind nginx", and I'll come back to them.

The `cancel()` on the stream is the part you can't forget. When the browser tab closes, the `ReadableStream` is cancelled, and if I don't kill the `journalctl` child there, every disconnect leaks a process. On a long-running box that's how you end up with two hundred orphaned `journalctl -f` processes and a confused future you. `stopFollow()` sends `SIGTERM` to the child, done.

## the browser side

The client is the smallest piece. `new EventSource(url)`, then listen for the named events. `EventSource` reconnects on its own if the connection drops, which is most of why I picked SSE over rolling something on `fetch`.

typescript
// src/routes/admin/logs/+page.svelte
let es: EventSource | null = null;

function connect() {
if (es) es.close();
es = new EventSource(streamUrl());

es.addEventListener('ready', (ev) => {
    const payload = JSON.parse((ev as MessageEvent).data);
    liveSource = payload.source;
    connected = payload.available;
});

es.addEventListener('log', (ev) => {
    if (paused) return;
    const e = JSON.parse((ev as MessageEvent).data) as LogEvent;
    events = [e, ...events].slice(0, linesCap);   // newest first, capped
});

es.addEventListener('error', (ev) => {
    const payload = JSON.parse((ev as MessageEvent).data ?? '{}');
    if (payload.message) streamError = payload.message;
    connected = false;
});

}


`events = [e, ...events].slice(0, linesCap)` prepends the newest line and caps the array, so the DOM never grows without bound on a chatty service. Everything else is just rendering. Level filter and search box rebuild the URL (`?level=warn&q=timeout`), close the old `EventSource`, and open a new one, so the filtering happens server-side and the browser only ever receives lines it's going to show.

## the parts that actually bite you

The happy path above is maybe forty lines. The three things that cost me real time were all environmental, not code.

**Permissions.** By default the app user can't read the journal. `journalctl` runs, returns nothing or errors, and you assume your spawn is broken when it isn't. The fix is one group, the user your service runs as needs to be in `systemd-journal`:

bash
usermod -aG systemd-journal www-data




I only figured this out fast because I catch the error and translate it instead of swallowing it, so the viewer says `Permission denied reading the journal, the app user needs to be in the systemd-journal group` instead of just going quiet. Past-me thanking past-me for that one.

**Proxy buffering.** nginx buffers proxied responses by default, which for a normal request is what you want and for an event stream means the browser sees nothing for thirty seconds and then a wall of lines. The `x-accel-buffering: no` header turns nginx buffering off for that one response, and `cache-control: no-transform` stops anything in the middle from trying to be clever. Without those two, SSE behind nginx just looks broken.

**Idle timeouts.** A quiet service might not emit a line for minutes, and proxies love to kill connections that go quiet. The `: ping\n\n` every 25 seconds is an SSE comment (any line starting with `:` is ignored by the client), it carries no data and exists only to keep the pipe warm. Cheap insurance.

None of those three are journald problems or SSE problems. They're deployment problems, the kind you only meet once the thing leaves your laptop.

## the short version

The whole path is four hops. The app writes JSON to stdout, systemd puts every line into the journal under your unit, `journalctl -f -o cat` follows that journal and hands the lines back, and an SSE endpoint pipes them to an `EventSource` in the browser. On the code side that's a `spawn`, a `ReadableStream`, and about ten lines of client. Everything expensive (structured logs, rotation by size and age, retention, querying) was already done for you by something that booted before your app did.

So if you're already on a systemd distro, this is close to free. Write to stdout, add the service user to `systemd-journal`, point `journalctl -f -o cat` at your unit, and pipe it out over SSE. That's the whole trick, and most of it isn't yours to build.

JWT is a scam and your app doesn't need it

Dusan Malusev — Sat, 23 May 2026 17:21:14 +0000

I am tired of pretending JWT is fine.

It isn't. It's a cargo cult. It solves a problem your app almost certainly does not have, it creates four or five problems your app definitely does have, and a generation of backend developers has been bullied into shipping it because some blog post in 2014 said "stateless" like it was a virtue instead of a tradeoff. Every Laravel app I started with tymondesigns/jwt-auth I eventually ripped it out of. Every JWT-based system I've audited has the same broken revocation story, the same useless refresh dance, and the same client codebase that decodes the payload and trusts it. My friend Dusan Mitrovic wrote about this in 2020. Six years later, people are still shipping the same mistakes, so here we go again.

If you're building a web app, a mobile app, or a first-party API: JWT is the wrong default and you should stop reaching for it. A row in Postgres with a bearer token in front of it is faster, simpler, and strictly more secure. The rest of this post is me showing my work.

what JWT actually is, and what the pitch was

A JWT is three base64url segments — a header, a JSON payload, a signature. The signature is either an HMAC or an RSA/ECDSA signature. The payload usually holds a user id, an iat, an exp, a jti, maybe some scopes.

The pitch is: the server signs it, the client carries it, every subsequent request only needs a signature verification — no database round-trip. Stateless authentication. That is the entire value proposition. Strip that one property away and JWT is just an opaque token wearing a costume.

So let's strip it away. It takes one question.

you cannot invalidate a JWT. you just can't.

How do you log a user out before exp?

You can't. That's the answer. The token is valid until it expires, full stop. The only way to invalidate it is to store the jti server-side in a revocation list and check that list on every single request. Which is a database lookup. Which is the thing JWT was supposed to let you skip. Congratulations, you've reinvented sessions, badly.

So you pick one of two losing moves:

Don't invalidate. A compromised token is valid until exp. And because nobody wants to "force users to log in again" — I have personally seen 1-year tokens, 5-year tokens, and a 10-year token in production at a company I won't name — the attacker owns the account for that entire window. Your "log out everywhere" button is a lie. Your password reset doesn't actually kick anyone out. You can rotate the signing key, sure, and log out every user on the platform to fix one breach. Beautiful design.
Maintain a revocation list. Now every request does signature verification plus a database or Redis lookup. You're paying both costs. You took on all the complexity of JWT to keep all the cost of sessions.

There is no third option. There has never been a third option. Anyone who tells you otherwise is selling something.

refresh tokens are a confession

The standard panic response to "long-lived JWTs are dangerous" is: use short-lived access tokens and a refresh token. Read that sentence carefully. It says the thing we sold you is unsafe, so here is a second thing to patch around it.

What you now ship, on every client:

attach the access token to every request
detect a 401 or near-expiry
call /auth/refresh with the refresh token
retry the original request with the new access token
handle the refresh failing (forced logout, redirect, queue replay)
secure storage for two tokens instead of one

And on the server you store the refresh token in the database for revocation. So you are already stateful. You built all of this — across web, iOS, Android, and every third party that integrates with you — to avoid the thing you ended up doing anyway. Every client team now spends a sprint on token plumbing instead of shipping product. For what? Because some JS developer in 2014 thought signed JSON was elegant?

A single opaque token, looked up in Redis with Postgres as the backing store, gives you the same security in one line of middleware. No refresh. No second token. No retry loop. Nothing.

the per-request cost is real and people lie about it

The standard handwave is that signature verification is "basically free". It is not.

Rough orders of magnitude per request on a modern x86 box:

Algorithm	Verification time	Notes
HS256	~5 µs	HMAC-SHA256, symmetric
RS256	~80–150 µs	2048-bit RSA, what most issuers ship
ES256	~40–80 µs	NIST P-256 ECDSA
Redis GET	~100–300 µs	localhost, single round-trip

RS256 verification is in the same order of magnitude as a Redis lookup. And you still have to parse JSON, validate exp, validate iss, validate aud, walk the JWKS cache for the right key, and allocate a few objects the GC has to clean up later. Multiply by your request rate.

"JWT saves you database hits" turns out to be mostly false the moment you measure it. An opaque token check is hash, GET from Redis, done — with an in-process LRU in front if you actually care. You're not saving compute by going JWT. You are spending more of it, on something less safe, that you can't revoke.

the frontend "verification" nobody has ever shipped

The asymmetric-JWT pitch had one more leg: the server publishes a public key, the client (or a gateway, or a third party) verifies the signature locally, and the auth server stays out of the request path. If you actually do this, you do save round-trips.

Almost no one does this. Large platforms with dedicated identity teams do. The Laravel app you're shipping next month does not. WebCrypto wasn't usable when JWT became fashionable, so frontends shipped atob(token.split('.')[1]), parsed the JSON, trusted whatever was inside, and called it a day. When the access token expired the next API call returned 401, the SPA bounced to /login, and the server got hit anyway. The "stateless" benefit existed only on a slide deck.

And here's the part that should make you angry: if you hand a JWT to a third-party integrator and they skip the public-key verification — and they will, because everyone does — every single one of their requests becomes a request through your auth backend the long way around. You wear the cost of their laziness, forever. With opaque tokens this is just… how it works. No mismatch, no hidden tax, no "did they implement the checks correctly" question to lose sleep over.

encrypted JWT (JWE) is even more nonsensical

If you're encrypting the payload because it contains sensitive data, you've also decided the client can't read it. So what is it doing in the token? The client is going to call /api/me to render the UI anyway. Put the data behind that endpoint and have the token reference it. JWE solves a problem you invented by stuffing user data into a credential.

And while we're here: if the JWT payload becomes the source of truth for "who is this user", the user updates their email, their role gets revoked, their plan gets downgraded — and your app keeps reading stale values from the token until the next refresh. The user files a support ticket because the app "isn't updating". You'll fix it by fetching the user from the database on every request. You're stateful again. You were always going to be.

"just put the JWT in an httpOnly cookie"

This is the suggestion that finally gives the game away.

The advice goes: don't put the JWT in localStorage because XSS will steal it — put it in an httpOnly, Secure, SameSite cookie so JavaScript can't touch it. Read that sentence one more time. You have just described a session cookie. The browser attaches it automatically, the server reads it on every request, the client can't see what's inside.

The only thing distinguishing it from a normal session cookie is that the bytes inside happen to be a signed JWT instead of a random ID. And since the browser can't read those bytes, the "you can decode it client-side" feature — already a feature nobody used — is now physically impossible. You have kept every line of JWT complexity (signing, expiry, refresh, JWKS) and given up the only property that ever made JWT different from a session.

That's it. That's the whole house of cards. If you're putting a JWT in an httpOnly cookie, you are running a stateful session with extra cryptography. Stop. Just run the session.

"no system is stateless" — please stop pretending

Your system has users. Your system has sessions. Your system has rate limits, audit logs, permissions, billing state, devices, account lockouts, abuse signals, feature flags. Every one of those is server-side state. Reading a session row alongside the user row in the same query costs you nothing. The architectural prize of "statelessness" only matters if every other thing in your request path is also stateless — and in a real app, it isn't and it never will be.

The Okta talk "Why JWTs Are Bad for Authentication" makes this point at length, and Okta is a company that sells you JWT for a living. When the vendor tells you to stop using their flagship pattern for first-party browser apps, maybe listen.

what to ship instead

For a first-party web app:

httpOnly, Secure, SameSite=Lax session cookie. A 256-bit random opaque ID. Done.
Sessions table. id, user_id, created_at, last_seen_at, user_agent, ip, revoked_at.
Redis in front keyed by the session ID hash. TTL ~60s or invalidate on write.
Logout: UPDATE sessions SET revoked_at = NOW() WHERE id = $1, plus DEL in Redis.
Force-logout all devices: the same UPDATE with user_id = $1. The feature your JWT app pretends to have, this app actually has.

For an API consumed by mobile or by integrators:

Opaque bearer tokens. GitHub-style xxx_ prefix so they're greppable in logs and revocable by secret-scanning services.
Same table. Add scopes, expires_at, last_used_at.
An admin panel to list, revoke, regenerate, expire. The thing you should have built for your JWT system but didn't.
Authorization: Bearer <token>. Document it once. Every HTTP client on Earth speaks this already.

You get everything JWT promised — issuance, revocation, expiry, scopes, audit — without the signing, the JWKS rotation, the refresh dance, the encoding gotchas, and the CVE class that begins with alg: none.

"but I'm building an OAuth 2 server"

Great. OAuth 2 is a delegation protocol — it does not require JWT. The spec says "access token" and leaves the format opaque on purpose. Build an OAuth 2 server with opaque tokens and an introspection endpoint and you are 100% compliant. The only time you actually need JWT-shaped access tokens is when your resource servers are operated by parties who genuinely cannot call your introspection endpoint on every request. That is a real use case. It is not your SaaS dashboard.

what it isn't

It's not "JWT is broken". The cryptography is fine. The tymondesigns/jwt-auth package is fine. The concept of using JWT as your app's session is what's broken.
It's not blanket opposition to signed tokens. Short-lived signed JWTs for service-to-service calls inside a trusted mesh, or as ID tokens in OIDC, are legitimate. Both are narrow.
It's not a claim opaque tokens are free. You pay for the Redis lookup. You were going to pay for it the moment you wanted to log a user out.
It does not apply to true federation. If you're Okta, Auth0, or running an identity provider whose tokens are consumed by hundreds of resource servers you don't operate, JWT earns its keep. You are not them.
It's not a license to hand-roll session cookies. Use your framework's session driver. The whole reason this is boring is that the framework already solved it.

If you're starting an app today, default to a session cookie or an opaque bearer token in a database, cached in Redis. Reach for JWT only when you can point at a federation requirement that actually needs it. I have built and rebuilt this stack enough times to be sure. JWT was the most expensive lesson I learned twice.

Self-registering class descriptors: deleting MINIT boilerplate in a PHP extension

Dusan Malusev — Sat, 23 May 2026 12:55:57 +0000

The ScyllaDB PHP driver used to open MINIT with ~70 calls to hand-written define_*() functions, one per registered class. The order mattered — parent before child, interface before implementer, Value before Bigint — and the only way to know you'd got it wrong was a segfault during php -m.

That whole block is now one call. Each class declares itself at file scope, a __attribute__((constructor)) appends it to a linked list at .so load time, and php_scylladb_class_registry_minit() topologically sorts by FQN and registers in dependency order. Missing or cyclic deps fail loudly at MINIT with the class name in the message.

This post is the second in the ScyllaDB PHP driver series. The pattern isn't novel — kernel module init tables and static_init-style registries have done this in C for decades — but it solves a problem PHP extension authors hit on day one and most of us paper over with a hand-maintained switch statement. If you've ever stared at a 50-line MINIT and wished the file declared its own registration, this is what that looks like.

the problem MINIT actually has

A PHP extension declares its classes in PHP_MINIT_FUNCTION(ext). The mechanical part is INIT_CLASS_ENTRY + zend_register_internal_class (or, since PHP 8.3, the register_class_*() helpers generated from .stub.php). The political part is that you have to call them in the right order.

zend_register_internal_class_ex wants a parent zend_class_entry*. If the parent hasn't been registered yet, you pass NULL and the child silently extends nothing. Interface implementers want the interface ce* to be present before they call zend_class_implements. So MINIT becomes:

// MINIT — the version this PR replaced
define_Cassandra_Value();          // interface, no deps
define_Cassandra_Numeric();        // interface, no deps
define_Cassandra_RetryPolicy();    // interface, no deps
define_Cassandra_Bigint();         // implements Value, Numeric
define_Cassandra_RetryPolicy_DefaultPolicy(); // implements RetryPolicy
// … 65 more lines, all order-sensitive

There's no checker. The compiler can't tell you that Bigint came before Value; it's just two function calls in a .c file. Renaming a class, adding an interface, or reordering for readability all have the same failure mode: a class entry with the wrong parent, discovered the first time someone instantiates it.

The other problem is locality. The class lives in src/Bigint.c. Its interfaces live in src/Numeric.stub.php and src/Value.stub.php. But the registration order lives in src/php_driver.c — a file most contributors never edit. Adding a class meant editing three or four places, in two languages, and remembering an ordering rule that wasn't enforced anywhere.

the registry

Every class file declares a descriptor at file scope:

// src/RetryPolicy/DefaultPolicy.c (excerpt)
PHP_SCYLLADB_REGISTER_CLASS(
    retry_policy_default_policy,                    // C identifier suffix
    "Cassandra\\RetryPolicy\\DefaultPolicy",        // FQN
    &php_scylladb_retry_policy_default_policy_ce,   // where to publish the ce*
    "Cassandra\\RetryPolicy",                       // parent FQN (or nullptr)
    php_scylladb_retry_policy_default_policy_register
)

The macro expands to a static descriptor struct + a constructor function that appends it to a global linked list:

// src/Registry/Registry.h
#define PHP_SCYLLADB_REGISTER_CLASS(slug, _name, _ce_out, _parent, _register_fn) \
    static const char *const scylladb_cls_##slug##_deps[] = { (_parent), nullptr }; \
    static php_scylladb_class_descriptor_t scylladb_cls_##slug = {              \
        .name       = (_name),                                                  \
        .deps       = ((_parent) == nullptr ? nullptr : scylladb_cls_##slug##_deps), \
        .ce_out     = (_ce_out),                                                \
        .register_  = (_register_fn),                                           \
        .next       = nullptr,                                                  \
        .registered = false,                                                    \
    };                                                                          \
    __attribute__((constructor))                                                \
    static void scylladb_cls_register_##slug##_ctor(void) {                     \
        php_scylladb_class_registry_add(&scylladb_cls_##slug);                  \
    }

__attribute__((constructor)) is a GCC/Clang extension — also accepted by recent MSVC via /Zc:__attribute__ — that runs the function during the dynamic linker's _init phase, before dlopen returns to PHP and before MINIT fires. By the time php_scylladb_class_registry_minit() runs, every descriptor in every .o linked into the extension has already added itself to registry_head.

There's one linker subtlety to flag now, because it'll bite you later: if a .o file has no externally referenced symbols, the static linker drops it from the final binary and the constructor never runs. The CMake wiring deals with this by linking the descriptor archives with $<LINK_LIBRARY:WHOLE_ARCHIVE,…>:

# cmake/GenStubs.cmake — module libs are linked whole, no GC
target_link_libraries(php_scylladb_ext PRIVATE
    "$<LINK_LIBRARY:WHOLE_ARCHIVE,php_scylladb_retry_policy>"
    "$<LINK_LIBRARY:WHOLE_ARCHIVE,php_scylladb_value>"
    # …
)

Without that, the linker sees DefaultPolicy_descriptor.o, notices nothing else references it, drops it, and the constructor — which exists purely for its side effect — never runs. The class then doesn't exist at MINIT. It's the constructor-attribute equivalent of forgetting extern.

topo-sort at MINIT

The runtime side is small enough to paste in full:

// src/Registry/Registry.c — topo sort, Kahn-ish
void php_scylladb_class_registry_minit(void) {
    bool progress = true;
    while (progress) {
        progress = false;
        for (php_scylladb_class_descriptor_t *d = registry_head; d; d = d->next) {
            if (d->registered) continue;

            zend_class_entry *resolved[MAX_DEPS_PER_CLASS] = { nullptr };
            size_t n_deps = 0;
            bool defer = false;

            if (d->deps != nullptr) {
                for (size_t i = 0; d->deps[i] != nullptr; i++) {
                    bool dep_deferred = false;
                    zend_class_entry *ce = resolve_dep(d->deps[i], &dep_deferred);
                    if (dep_deferred) { defer = true; break; }
                    if (ce == nullptr) {
                        zend_error_noreturn(E_CORE_ERROR,
                            "scylladb registry: class '%s' declares dep '%s' which is neither registered nor known to Zend",
                            d->name, d->deps[i]);
                    }
                    resolved[i] = ce;
                    n_deps = i + 1;
                }
            }
            if (defer) continue;

            zend_class_entry *ce = d->register_(n_deps > 0 ? resolved : nullptr);
            *(d->ce_out)  = ce;
            d->registered = true;
            progress      = true;
        }
    }

    /* Anything still un-registered means a cyclic or missing dep. */
    for (php_scylladb_class_descriptor_t *d = registry_head; d; d = d->next) {
        if (!d->registered) {
            zend_error_noreturn(E_CORE_ERROR,
                "scylladb registry: class '%s' could not be registered (cyclic or missing registry-owned dep)",
                d->name);
        }
    }
}

It's O(n²) — for each pass over the list, every descriptor whose deps are now resolved gets registered, and the loop reruns until a full pass makes no progress. The driver has ~120 classes, MINIT runs once per process, and the constant factor is strcmp on FQN strings. The full registration pass is below 1 ms on a 2023 M2.

resolve_dep does the only interesting thing in the file: it tries the registry first (so registry-owned classes resolve cleanly), and falls back to zend_lookup_class for anything it doesn't own:

static zend_class_entry *resolve_dep(const char *fqn, bool *deferred) {
    *deferred = false;
    php_scylladb_class_descriptor_t *p = registry_find(fqn);
    if (p != nullptr) {
        if (!p->registered) { *deferred = true; return nullptr; }
        return *(p->ce_out);
    }
    zend_string *lookup = zend_string_init(fqn, strlen(fqn), 0);
    zend_class_entry *ce = zend_lookup_class(lookup);
    zend_string_release(lookup);
    return ce;
}

That second branch is what makes SPL parents work. \Cassandra\Exception\DivideByZeroException ultimately inherits from \RangeException, which the driver doesn't own and can't INIT_CLASS_ENTRY on. zend_lookup_class finds it in Zend's global class table, the registry treats it as already-resolved, and the child registers normally.

The error messages name the culprit. If you add a class with a dep on "Cassandra\\Foo" and nothing declares Foo, MINIT aborts with:

PHP Fatal error: scylladb registry: class 'Cassandra\Bar' declares dep
'Cassandra\Foo' which is neither registered nor known to Zend

That's the bit I care about most. The old MINIT failed silently — a class would register with parent_ce = NULL and the bug would surface during instanceof checks. The registry fails at module load, before a single request runs.

the part you don't write

Two generators, one stub. The split between them is the whole point.

gen_stub.php ships with php-src and every modern extension uses it. Feed it DefaultPolicy.stub.php and it emits DefaultPolicy_arginfo.h containing register_class_Cassandra_RetryPolicy_DefaultPolicy(). That function is where the zend_class_entry is actually born — INIT_CLASS_ENTRY, class flags, property declarations, zend_register_internal_class_ex. Mature, version-aware, not mine to touch.

tools/gen_descriptor/gen_class_descriptor.php is mine. 513 lines of straight PHP, no dependencies. Same stub, different output: DefaultPolicy_descriptor.c.

// tools/gen_descriptor/gen_class_descriptor.php
/**
 * What it produces:
 *   - the `php_scylladb_<snake>_ce` global — the pointer the rest of the
 *     extension reads; the class entry itself is built by register_class_*()
 *     from _arginfo.h
 *   - the `zend_object_handlers php_scylladb_<snake>_handlers` global
 *   - a register fn that calls register_class_*() with deps wired from
 *     the stub's extends/implements, then applies create_object + handler
 *     overrides via weakly-declared callbacks, and calls a weak
 *     post_register hook
 *   - the PHP_SCYLLADB_REGISTER_CLASS / _DEPS macro invocation
 */

Read the split this way: php-src builds the class entry, my generator hangs it on the registry. Both run on every build, both write into the build directory, neither file lives in git. CMake exposes them as siblings — php_scylladb_generate_arginfo() and php_scylladb_generate_descriptor() — and you point both at the same .stub.php.

That leaves four things per class for a human to write. ZEND_METHOD bodies. The convention-named callbacks — _new, _free, _compare, _gc, _clone, _cast, _hash_value, _post_register — declared as weak symbols so the ones you skip stay NULL. Any public C helpers like _instantiate. And the stub itself. Everything in between is build output.

There are two annotations:

@scylladb-value-handlers in a class docblock opts into the php_scylladb_value_handlers struct (standard handlers + an extra hash_value slot). Applied to Bigint, Set, Map, Blob, Inet, and the rest of the Value-typed classes.
@scylladb-no-generate is the escape hatch for classes that need a fully hand-written descriptor. Currently used by Custom (no stub at all — legacy INIT_CLASS_ENTRY path) and the SPL-rooted exception batch in src/Exception/exceptions.c, which registers 23 classes in one call and doesn't want the per-class machinery.

Adding a class now looks like this:

Write Foo.stub.php with extends/implements declared in PHP.
Define php_scylladb_foo_new (and any other convention-named callbacks) in Foo.c.
List the stub in the module's CMakeLists.txt under php_scylladb_generate_arginfo and php_scylladb_generate_descriptor.

No edits to php_scylladb.c. No edits to include/php_scylladb_types.h. No order to remember.

what it isn't

It's not portable to MSVC's default mode. __attribute__((constructor)) is a GCC/Clang feature. MSVC needs /Zc:__attribute__ or the .CRT$XCU section trick. The driver doesn't target Windows yet, so this hasn't bitten us.
It does not save you from cycles in the dep graph. The topo-sort detects them at MINIT and aborts; it does not break them. A circular A → B → A is your bug.
It is not a substitute for ZEND_BEGIN_MODULE_GLOBALS or the rest of MINIT. Functions, INI entries, constants, persistent resources — all still register the old way. The registry only owns class entries.
The whole-archive link is non-negotiable. If you skip the LINK_LIBRARY:WHOLE_ARCHIVE guard for any module, you get a silently-missing class, which is the exact failure mode the registry was designed to eliminate. Audit it on every new module.
Generated descriptors mean stub correctness matters. A typo in extends \Cassandra\Foo in a .stub.php now becomes a MINIT-time failure with a clear message, not a compile error. That's a feature for me; if you prefer compile-time failure, this is a regression.

where to start

The full implementation is two files, ~170 lines of C: Registry.h and Registry.c. The generator is one PHP file at tools/gen_descriptor/gen_class_descriptor.php. All three are MIT-licensed; lift them into your own extension if the pattern fits.

I wrote the registry the week I deleted ZendCPP. Once the per-class descriptor was a generated file, the C++ that backed it stopped having a job.

dlopen, dlsym, and how PHP loads extensions

Dusan Malusev — Tue, 19 May 2026 17:02:24 +0000

Most programs are linked at build time. dlopen is for everything else: plugin systems, audio engines that load VST modules, language runtimes that pull in extensions, game loops that reload logic without restarting — and GPU drivers. The mechanism is identical across all of them. Four POSIX functions, one opaque handle, and a contract the compiler cannot enforce for you.

This is that contract.

API vs ABI

These two acronyms get conflated constantly. They describe different things, enforced at different times, by different tools.

An API (Application Programming Interface) is a source-level contract. It defines what you can call, with what argument types, and what you get back. The compiler enforces it. Pass an int where a const char * is expected and you get a type error before a binary exists. Change a function signature in a header and every file including that header fails to compile. The feedback is immediate and impossible to miss.

An ABI (Application Binary Interface) is a binary-level contract. It defines how compiled code actually executes a call: which registers carry which arguments, how structs are laid out in memory, and what a function's name looks like in the symbol table after the compiler has processed it. Nothing enforces this automatically. Two translation units can agree at the source level — identical header, identical types, identical function names — and still disagree at the binary level if compiled with different compilers, different compiler versions, different flags, or different target ABIs.

The gap between them is where dlopen lives.

When you link two .o files together, the linker sees both sides simultaneously. Any ABI inconsistency either resolves cleanly or produces a linker error. When you dlopen a .so at runtime, the two sides were compiled separately — possibly years apart, by different people, with different toolchains. The API contract (the header) might be unchanged. The ABI might not be.

A concrete example: a library ships struct Config { int version; char *name; }. Everything compiles. Two years later, a field is inserted between version and name. The function signatures are untouched; the API is compatible if you recompile. But a plugin compiled against the old header has name at byte offset 4. The new library reads name from offset 8. No compiler error. No linker error. A pointer read from the wrong address, producing garbage or a crash.

This is why "we didn't change the API" is not sufficient. The relevant question is whether the ABI changed.

ABI stability is a harder property than API stability. It requires:

never reordering struct fields
never inserting fields between existing ones
never changing the size of any exported type
never changing a function signature in ways that affect register assignment
using the same name mangling scheme — which implies the same language and often the same compiler family

Linux distributions maintain ABI stability for core system libraries across release cycles. Most application libraries do not, and signal breaks via SONAME version bumps — libfoo.so.1 → libfoo.so.2 — so the dynamic linker refuses to load the wrong version. dlopen by bare filename bypasses even that check. You own the contract entirely.

why dynamic loading exists

A statically linked binary resolves every symbol at link time. Addresses are baked in before the binary touches disk — predictable, fast, and completely inflexible. dlopen goes further than the normal dynamic linker: not only are the libraries separate from the host binary, the decision of which library to load and when happens at runtime, in your code.

The cost is real:

No compile-time type checking across the boundary
No ABI guarantees by default
The linker cannot dead-strip code it never sees

What you get in exchange depends on what problem you're solving:

Plugin systems — discover and load behavior the host binary never knew about at build time. A text editor loading syntax highlighters, a game engine loading user mods, an audio DAW loading instrument plugins.

Hot reloading — recompile a .so while the host process is running, swap the old handle for the new one, and continue with updated logic without restarting. The key design constraint is that state lives in the host and behavior lives in the .so. The host allocates the game world, the simulation state, the in-memory database — whatever must survive across reloads. The .so contains only the code that operates on it. When the .so is recompiled, the host calls dlclose on the old handle and dlopen on the new one between two iterations of its main loop, re-resolves the function pointers via dlsym, and continues. The state was never in the .so, so nothing is lost. This is a development workflow rather than a production deployment strategy, but it eliminates the restart-and-reproduce cycle for anything with a slow startup — a game engine loading assets, a simulation with expensive initialization, a server with a warm cache. Tsoding has demonstrated this pattern repeatedly on stream: game logic in a .so, main loop polling for mtime changes, swap between frames, state intact.

Language runtimes — PHP, Python, Ruby, and Lua all use dlopen to pull in native extensions. The interpreter is the host; the extension is the plugin; dlsym finds the entry point by a known name convention.

GPU and audio drivers — the OS loads the right driver for the installed hardware without recompiling anything.

the four functions

// <dlfcn.h>
void *dlopen(const char *filename, int flags);
void *dlsym(void *handle, const char *symbol);
char *dlerror(void);
int   dlclose(void *handle);

dlopen maps the library into the process's address space and returns an opaque handle. Two flag pairs matter:

RTLD_LAZY — resolve symbols only when called for the first time. Faster startup; missing symbols fail at call time, mid-execution.
RTLD_NOW — resolve everything immediately. A missing symbol aborts at dlopen time, not later.
RTLD_LOCAL (default) — keeps the library's symbols private to this handle.
RTLD_GLOBAL — dumps all exported symbols into the process-wide namespace. Every library loaded afterward can see them. PHP uses this; the cost is that two extensions with the same symbol name silently shadow one another based on load order.

dlsym does a hash lookup for a named symbol and returns its address as void *. The correct error-checking pattern is:

dlerror();                           // clear any stale error
void *sym = dlsym(handle, "name");
const char *err = dlerror();
if (err) { /* sym is unusable, do not call it */ }

Checking sym != NULL is not enough — a valid symbol can theoretically reside at address zero, and a failed lookup can return NULL without setting an error in some edge cases. The dlerror round-trip is the only reliable path.

minimal C23 example

Two translation units: the plugin compiled to .so, and the host that loads it.

// plugin.c — cc -std=c23 -fPIC -fvisibility=hidden -shared -o plugin.so plugin.c

#include <stdio.h>

__attribute__((visibility("default")))
int greet(const char *name) {
    return printf("hello, %s\n", name);
}

-fPIC (position-independent code) is required for shared libraries. Addresses inside the .so are relative offsets rather than absolute, so the same file maps at different virtual addresses in different processes. -fvisibility=hidden makes hidden the default; visibility("default") opts individual symbols back in. Without it, your entire symbol table is exported — a maintenance hazard and a collision risk in large plugin ecosystems.

// host.c — cc -std=c23 -o host host.c -ldl

#include <dlfcn.h>
#include <stdio.h>
#include <stdint.h>
#include <stdlib.h>

typedef int (*greet_fn)(const char *);

int main(void) {
    auto handle = dlopen("./plugin.so", RTLD_NOW | RTLD_LOCAL);
    if (!handle) {
        fprintf(stderr, "dlopen: %s\n", dlerror());
        return EXIT_FAILURE;
    }

    dlerror();
    greet_fn greet = (greet_fn)(uintptr_t)dlsym(handle, "greet");
    const char *err = dlerror();
    if (err) {
        fprintf(stderr, "dlsym: %s\n", err);
        dlclose(handle);
        return EXIT_FAILURE;
    }

    greet("world");
    dlclose(handle);
    return EXIT_SUCCESS;
}

auto handle is valid C23 — the type is inferred as void * from dlopen's return type. Same semantics as C++ auto, standardized in C 13 years later.

The cast (greet_fn)(uintptr_t)dlsym(...) is the standard-conforming path from void * to a function pointer. ISO C does not guarantee void * and function pointers share the same representation. POSIX guarantees it specifically for dlsym, but the double-cast suppresses the pedantic diagnostic cleanly.

how PHP loads extensions

PHP is one specific application of this exact pattern. Its loader lives in main/dl.c. The core of php_load_extension() — simplified but structurally faithful:

// main/dl.c (php-src)
void *handle = DL_LOAD(libpath);    // DL_LOAD is dlopen() on POSIX

zend_module_entry *(*get_module)(void) = dlsym(handle, "get_module");
zend_module_entry *module_entry = get_module();

zend_register_module_ex(module_entry);
zend_startup_module_ex(module_entry);

get_module is PHP's update — a known-name entry point the host finds via dlsym. The difference is the payload: instead of a function pointer to game logic, it returns a pointer to zend_module_entry, PHP's struct describing everything the extension provides.

zend_module_entry myext_module_entry = {
    STANDARD_MODULE_HEADER,
    "myext",
    myext_functions,      /* NULL-terminated Zend function table */
    PHP_MINIT(myext),     /* called once at process startup */
    PHP_MSHUTDOWN(myext),
    PHP_RINIT(myext),     /* called per request */
    PHP_RSHUTDOWN(myext),
    PHP_MINFO(myext),
    "1.0.0",
    STANDARD_MODULE_PROPERTIES
};

/* expands to: zend_module_entry *get_module(void) { return &myext_module_entry; } */
ZEND_GET_MODULE(myext)

RINIT/RSHUTDOWN run once per request; MINIT/MSHUTDOWN once per worker process lifetime. PHP passes RTLD_GLOBAL | RTLD_LAZY by default. RTLD_GLOBAL is intentional — some extensions wrap C++ libraries that need their own symbols visible to later-loaded libraries. The consequence is that two extensions exporting the same symbol name silently shadow each other by load order. No warning.

Rust without headaches

libloading wraps dlopen/dlsym with a type-safe API. The unsafe surface shrinks to the unavoidable: loading the library and declaring the expected function signature.

[dependencies]
libloading = "0.8"

// src/main.rs
use libloading::{Library, Symbol};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // SAFETY: plugin.so is a well-formed shared library we control.
    let lib = unsafe { Library::new("./plugin.so")? };

    // SAFETY: "greet" exists, takes *const c_char, returns c_int.
    let greet: Symbol<unsafe extern "C" fn(*const i8) -> i32> =
        unsafe { lib.get(b"greet\0")? };

    let name = c"world";
    unsafe { greet(name.as_ptr()) };

    Ok(())
}

Library::new calls dlopen and maps the error to Rust's Error trait. lib.get calls dlsym — b"greet\0" is the null-terminated symbol name exactly as dlsym expects. Symbol<F> carries the function signature, so calling greet(...) type-checks the arguments at compile time.

Symbol<T> borrows from Library, so the borrow checker prevents calling a symbol after the library is dropped — a use-after-free class of bug that C gives you silently.

For anything real, wrap the FFI behind a typed struct:

pub struct Plugin {
    _lib: Library,
    update: unsafe extern "C" fn(*mut State, f32),
}

impl Plugin {
    pub fn load(path: &str) -> Result<Self, libloading::Error> {
        let lib = unsafe { Library::new(path)? };
        // Dereference copies the fn pointer out of Symbol — fn pointers are Copy,
        // so we own the value before Symbol's borrow of lib ends.
        let update = *unsafe {
            lib.get::<unsafe extern "C" fn(*mut State, f32)>(b"update\0")?
        };
        Ok(Self { _lib: lib, update })
    }

    pub fn update(&self, state: &mut State, dt: f32) {
        unsafe { (self.update)(state as *mut State, dt) }
    }
}

_lib: Library keeps the shared library alive for the struct's lifetime. Dropping Plugin calls dlclose. Callers never see unsafe.

the ABI in detail

dlsym returns an address and trusts you've declared the right type to call through. There are three independent ways to get that wrong: symbol name, calling convention, and struct layout. Each fails silently.

calling convention

A calling convention is the machine-level agreement between caller and callee: which registers carry arguments, who restores the stack, and where the return value lands.

The x86-64 System V ABI (Linux, macOS, BSDs) assigns integer and pointer arguments in this order:

position	register	32-bit alias
1st	`rdi`	`edi`
2nd	`rsi`	`esi`
3rd	`rdx`	`edx`
4th	`rcx`	`ecx`
5th	`r8`	`r8d`
6th	`r9`	`r9d`
7th+	stack

Return value comes back in rax. Float arguments use xmm0–xmm7. Registers rax, rcx, rdx, rsi, rdi, r8–r11 are caller-saved — the callee may clobber them. rbx, rbp, r12–r15 are callee-saved — the callee must restore them.

// update(&state, 0.016f) on x86-64 System V:
// rdi = &state   ← pointer to State struct
// xmm0 = 0.016f  ← first float argument
// call <address from dlsym>

Windows x64 differs: rcx, rdx, r8, r9 for the first four, then stack, with 32 bytes of shadow space reserved regardless. A function compiled for one convention, called through the other, reads arguments from wrong registers. No error at any stage — just wrong values.

extern "C" in C++ and Rust selects the platform C calling convention. Without it the compiler chooses whatever it wants, and there is no guarantee two compilers choose the same thing.

struct layout

C lays out fields in declaration order, each aligned to its own natural size: char to 1, int to 4, long and pointers to 8 on LP64. The struct is padded at the end to a multiple of its largest member's alignment. Gaps are inserted between fields to satisfy alignment.

struct Example {
    char a;   // offset 0,  size 1
              // ← 3 bytes padding
    int  b;   // offset 4,  size 4
    char c;   // offset 8,  size 1
              // ← 7 bytes padding
    long d;   // offset 16, size 8
};
// sizeof == 24, not 14

field	offset	size	padding after
`a`	0	1	3
`b`	4	4	0
`c`	8	1	7
`d`	16	8	0

Reordering to { char a; char c; int b; long d; } produces a 16-byte struct. Same fields, same types, different size. A plugin compiled against the 24-byte layout that reads d at offset 16 reads from the middle of b and c in the 16-byte layout. No error at any point in the toolchain.

The standard mitigation: put a version or size field first in any struct that crosses the plugin boundary, and check it at load time.

struct PluginAPI {
    uint32_t version;       // must be first, must never move
    void (*update)(State *, float);
};

// At load time:
PluginAPI *api = get_api();
if (api->version != PLUGIN_API_VERSION) { /* reject */ }

name mangling

C symbol names are function names, verbatim. dlsym(handle, "greet") finds greet. C++ encodes namespace, class, and parameter types into the symbol to support overloading. Rust does the same for generics.

# C: int greet(const char *name)
$ nm -D plugin_c.so | grep greet
00000000000010f0 T greet

# C++: int greet(const char *name)
$ nm -D plugin_cpp.so | grep greet
00000000000010f0 T _Z5greetPKc

_Z5greetPKc means: function named greet (5 chars), taking PKc (pointer-to-const-char). Decode it with c++filt _Z5greetPKc. The scheme is not standardized — it differs between GCC and Clang, between versions, between platforms. dlsym(handle, "_Z5greetPKc") works today and breaks silently after a compiler upgrade.

extern "C" suppresses C++ mangling:

// Mangled — unstable symbol name
int greet(const char *name) { ... }

// Not mangled — stable, dlsym-able by plain name
extern "C" int greet(const char *name) { ... }

Rust needs both extern "C" (for calling convention) and #[no_mangle] (to emit the plain name):

// Mangled + Rust ABI — dlsym("greet") won't find it
pub fn greet(name: *const i8) -> i32 { ... }

// C ABI, plain symbol name — dlsym("greet") finds it
#[no_mangle]
pub extern "C" fn greet(name: *const i8) -> i32 { ... }

struct layout in Rust

Without #[repr(C)], Rust may reorder struct fields to minimize padding. The layout is unspecified and can change between compiler versions.

// repr(Rust) — layout unspecified, compiler may reorder
struct Foo { a: u8, b: u32, c: u8 }
// Possible layout: b(0), a(4), c(5), pad(6-7) → 8 bytes

// repr(C) — C rules, declaration order preserved
#[repr(C)]
struct Foo { a: u8, b: u32, c: u8 }
// Guaranteed: a(0), pad(1-3), b(4), c(8), pad(9-11) → 12 bytes

Any struct passed by pointer to C, returned from C, or embedded in a C struct must be #[repr(C)]. Without it, C reads fields from wrong offsets.

where it goes wrong

Symbol versioning exists in glibc — .symver directives, SONAME in the ELF header — but almost nothing outside of libc and GPU vendors uses it correctly. If your plugin ABI changes, you change the symbol name or the filename. There is no automatic enforcement.

Crashes inside a loaded plugin take down the whole process. PHP isolates this with shared-nothing worker processes — one per request — not with any sandbox inside the loader. If you need fault isolation, you need process boundaries or a WASM sandbox, not dlopen.

what it isn't

It's not a substitute for static linking when you control both sides and ship them together. Static linking gives the linker visibility to strip dead code, inline across translation units, and catch missing symbols at build time.
It does not give you ABI stability for free. Reordering struct fields, adding a parameter, or switching compiler versions can break a loaded plugin with zero compile-time signal.
It is not safe to pass Rust-native types across the boundary. Vec<T>, Box<T>, Arc<T> all depend on allocator identity and internal layout that is not stable across compiler versions. Use *const T/*mut T with #[repr(C)] structs.
RTLD_GLOBAL is not a default you want. It pollutes the process-wide symbol namespace. Use RTLD_LOCAL unless you have a concrete reason, and document it.
It does not work on Windows as written. The Windows equivalent is LoadLibrary/GetProcAddress. libloading abstracts over both; the raw POSIX API does not exist on Windows.

where to start

# Plugin
cc -std=c23 -fPIC -fvisibility=hidden -shared -o plugin.so plugin.c

# Host (Linux requires -ldl; macOS includes it in libSystem automatically)
cc -std=c23 -o host host.c -ldl

./host
# hello, world

For the hot-reload loop: compile the above, run the host, then edit logic.c, run make, and watch the swap happen without restarting.

For Rust: cargo add libloading, use the typed wrapper pattern above, keep unsafe blocks minimal and commented.

I built the ScyllaDB PHP driver on this foundation — every ZEND_GET_MODULE is the structured version of what's described here.

laravel-crypto: libsodium, no compromises, and per-user encryption

Dusan Malusev — Mon, 18 May 2026 21:22:54 +0000

Laravel's default cipher is AES-256-CBC. That is a 25-year-old design with no built-in authentication — the MAC is bolted on separately by the framework, and the correctness of that construction depends on nobody ever reordering the operations.

I am not saying it is broken. I am saying PHP has shipped with libsodium since 7.2, and libsodium gives you authenticated encryption by construction. There was no reason to keep using AES-256-CBC as the default the moment sodium_crypto_aead_xchacha20poly1305_ietf_encrypt became available in every standard PHP install. I built laravel-crypto because I wanted to stop thinking about that gap every time I started a new project.

why libsodium

NaCl — and libsodium as its portable successor — was designed around one principle: remove the ways you can shoot yourself in the foot. Every algorithm choice is made for you. There is no ECB mode. There is no "pick your own MAC." XChaCha20-Poly1305 is authenticated by definition. AEGIS was designed specifically for high-throughput AEAD on hardware with AES acceleration, which includes every modern x86 and ARM chip. The API surface is small enough to understand fully.

PHP's mcrypt was the old answer. It was unmaintained, it supported ECB, it let you combine incompatible primitives, and it was removed in PHP 7.2. libsodium replaced it — but Laravel did not update its default cipher. AES-256-CBC stayed in config/app.php, a leftover from before the ecosystem had anything better. laravel-crypto picks up where mcrypt's removal should have taken things.

the drop-in

Swapping the provider is two lines:

// bootstrap/providers.php (Laravel 11+)
// Illuminate\Encryption\EncryptionServiceProvider::class,   // remove
CodeLieutenant\LaravelCrypto\ServiceProvider::class,         // add

After that, Crypt::encryptString() and Crypt::decryptString() still work exactly as before. All existing code calling the facade keeps working. The only change is what runs underneath.

Set the cipher in config/app.php:

'cipher' => 'Sodium_AEGIS256GCM',
// Options: Sodium_AES256GCM, Sodium_XChaCha20Poly1305, Sodium_AEGIS256GCM, Sodium_AEGIS128LGCM, Sodium_SecretBox

Generate keys:

php artisan crypto:keys

That is the full migration for most apps. If you already use AEAD via APP_PREVIOUS_KEYS, the library picks those up automatically for decryption during key rotation.

the numbers

Benchmarks from PHP 8.5.1 on a MacBook M4 Pro — Apple Silicon has hardware AES-NI and dedicated AEGIS acceleration:

Algorithm	1 KiB enc	1 KiB dec	1 MiB enc	1 MiB dec
Laravel AES-256-CBC	8.09 μs	9.98 μs	5.02 ms	7.57 ms
Laravel AES-256-GCM	3.37 μs	5.33 μs	1.31 ms	3.94 ms
Sodium AES-256-GCM	2.39 μs	2.58 μs	1.11 ms	1.88 ms
Sodium XChaCha20-Poly1305	3.41 μs	3.58 μs	2.21 ms	2.90 ms
Sodium AEGIS-256	2.06 μs	2.27 μs	0.82 ms	1.65 ms
Sodium AEGIS-128L	2.03 μs	2.14 μs	0.90 ms	1.60 ms

AEGIS-128L decrypts a 1 MiB payload in 1.60 ms versus Laravel's AES-256-CBC at 7.57 ms. That is 4.7× faster, authenticated, on the same hardware. Sodium AES-256-GCM halves the decryption time compared to Laravel's own GCM implementation — same algorithm, better path through the Sodium extension than through OpenSSL via PHP's stream wrapper.

XChaCha20-Poly1305 is the conservative choice: well-analyzed, hardware-agnostic, fast on everything. Use it if you need consistent performance on older or constrained hardware without AES acceleration. On ARM or x86 with AES-NI, AEGIS is the right pick.

The point is not that the difference matters for a single request. It matters when you are decrypting a hundred fields per page load, or processing a batch job over encrypted rows, or streaming large files. AES-256-CBC at 7.57 ms per MiB is not a performance problem in isolation. As a default that never gets questioned, it adds up.

per-user encryption

The standard model — one APP_KEY encrypts everything — has a structural problem. Anyone with access to that key can decrypt every row in the database. That is the DBA, the sysadmin, the developer with a .env copy, and any process with access to the environment. If client data confidentiality is a real requirement, "we encrypted the database" is not a complete answer when a single key unlocks all of it.

Per-user encryption means each user's sensitive fields are encrypted with a key unique to that user. A 32-byte random key is generated at enrollment and wrapped in a self-contained blob stored in the encryption_key column. Two wrapping modes exist depending on what is available at enrollment time:

Mode 1 — password-wrapped (0x01, 89 bytes): wrapping key derived via Argon2id from the user's plaintext password. APP_KEY is not involved. Unwrapping requires the password — no server-side secret alone can decrypt these fields.
Mode 2 — server-wrapped (0x02, 73 bytes): wrapping key derived via BLAKE2b(appKey, userId). Used for auto-enrollment when the plaintext password is unavailable (e.g. OAuth users, Filament). The blob is promoted to Mode 1 transparently the next time the user provides their password.

The unwrapped key is never stored anywhere. It is base64url-encoded, sent to the client as X-Encryption-Token (header for SPA/API clients) or as an HTTP-only enc_token cookie (web clients), and re-sent on every subsequent request. The middleware reads it, loads it into the request-scoped context, then zeros it at the end of the response.

Setting it up:

// User model
use CodeLieutenant\LaravelCrypto\Traits\HasUserEncryption;

class User extends Authenticatable
{
    use HasUserEncryption;
}

At registration, return the token to the client:

$rawKey = $user->initUserEncryption($request->password);
$user->save();
return response()->json([...])->header('X-Encryption-Token', $user->encodeEncryptionToken($rawKey));

At login, re-derive the token from the password and hand it back:

if (Auth::attempt($credentials)) {
    $token = Auth::user()->issueEncryptionToken($credentials['password']);
    return response()->json([...])->header('X-Encryption-Token', $token);
}

After that, model casts handle the rest transparently:

class UserSecret extends Model
{
    protected function casts(): array
    {
        return [
            'ssn' => UserEncryptedWithIndex::class . ':ssn_index',
        ];
    }
}

Reading $secret->ssn decrypts using the key currently in the request context. Saving writes ciphertext. Nothing else in the application changes.

the key in memory

The key lives in a scoped container — one instance per HTTP request. The BootPerUserEncryption middleware loads it from the incoming header or cookie, sets it on the context, then clears it in a finally block:

// src/Encryption/UserKey/UserEncryptionContext.php
public function clear(): void
{
    if ($this->key !== null) {
        sodium_memzero($this->key);
        $this->key = null;
    }
}

public function __destruct()
{
    $this->clear();
}

Setting a variable to null in PHP does not zero the memory — the garbage collector might hold the reference, and even when it collects, it does not overwrite the bytes. sodium_memzero does. The key is gone, not just unreferenced.

For Mode 1 blobs the wrapped blob in the database is useless without the user's password. Compromising APP_KEY does not help. For Mode 2 blobs, APP_KEY + userId is enough to re-derive the wrapping key — that is the acknowledged trade-off for the auto-enrollment path. The moment the user sets a password, issueEncryptionToken() promotes the blob to Mode 1 automatically.

blind indexes for searchable fields

Encrypting a column means you can no longer query it. WHERE ssn = ? stops working when ssn is ciphertext. The standard solution is a blind index: a deterministic MAC of the plaintext stored alongside the ciphertext, used only for equality lookups.

The derivation:

// src/Encryption/UserKey/BlindIndex.php — compute
public function compute(
    #[SensitiveParameter] string $value,
    string $column,
    bool $normalise = true,
): string {
    $userKey = $this->context->get();
    $subKey  = $this->deriveColumnSubKey($userKey, $column);

    $input = $normalise ? mb_strtolower(trim($value)) : $value;

    return sodium_crypto_generichash($input, $subKey, self::INDEX_BYTES);
}

// src/Encryption/UserKey/BlindIndex.php — column sub-key
private function deriveColumnSubKey(string $userKey, string $column): string
{
    $hash = sodium_crypto_generichash($column, '', SODIUM_CRYPTO_GENERICHASH_BYTES_MIN);
    $ctx  = substr($hash, 0, 8);

    return sodium_crypto_kdf_derive_from_key(
        self::INDEX_BYTES,
        self::KDF_SUBKEY_ID,
        $ctx,
        $userKey,
    );
}

Each column gets a distinct sub-key derived from the user's key via libsodium's official KDF. The index for ssn is cryptographically separated from the index for email, even though both come from the same user key. Two users with identical SSNs produce different indexes. Querying:

UserSecret::where('ssn_index', UserCrypt::blindIndex('123-45-6789', 'ssn'))->first();

The leakage is explicit: blind indexes leak equality. An attacker with database read access can tell that two rows share a value — they learn nothing about what that value is. Do not put a blind index on a low-cardinality field. gender, country, boolean flags — no. SSN, passport number, phone, email — yes.

what it isn't

It is not a replacement for proper key management. Mode 1 blobs are only as safe as the user's password — weak passwords mean weak wrapping. Mode 2 blobs are only as safe as APP_KEY. Treat APP_KEY accordingly: secrets manager, rotation policy, backup.
It does not protect against runtime compromise. If an attacker can execute arbitrary PHP in your process, they can read the key from the request context during a live request. Encryption protects data at rest, not running code.
Per-user encryption is not transparent key rotation. Changing a user's password requires rewrapUserEncryption($old, $new). Rotating APP_KEY requires re-wrapping every user's key. Neither is automatic.
Blind indexes leak equality. Two rows with the same value in the same column for the same user produce the same index. On fields with a small set of possible values, that is dangerous enough to skip the index entirely.
It is not end-to-end encryption. The raw key is derived server-side and then handed to the client as a token. The server sees it. True E2E requires the key to never reach the server — that is a different architecture and a different threat model entirely.

where to start

composer require codelieutenant/laravel-crypto
php artisan vendor:publish --provider="CodeLieutenant\LaravelCrypto\ServiceProvider"
php artisan crypto:keys

Set 'cipher' => 'Sodium_AEGIS256GCM' in config/app.php, swap the service provider, run your test suite. For most apps the migration takes twenty minutes.

Per-user encryption takes longer — you need to decide which columns are sensitive enough to warrant it, wire up the middleware, and handle the password-change re-wrap flow. The docs in docs/UserEncryption.md cover the full setup. I use it in every project where the question "can your team read this user's data?" has an answer I would be uncomfortable defending.

ScyllaDB PHP Driver: the story so far

Dusan Malusev — Mon, 18 May 2026 21:22:28 +0000

The DataStax PHP driver for Cassandra would not compile on PHP 8. That was the whole problem.

At the time I was working at Nano Interactive. The entire backend was PHP. We were running Apache Cassandra as a primary data store — session data, event pipelines, a few hot lookup tables — and the driver that talked to it was the official DataStax extension. It worked fine on PHP 7. Then PHP 8 came out, we needed to upgrade, and the extension refused to build. Compile errors in the Zend internals layer. make spitting out pages of incompatible API warnings.

I went looking for a fix. There was none. DataStax had effectively abandoned the project — no PHP 8 tag, no branch, no response on the open issues. The last meaningful release was years old. The options were: stay on PHP 7 indefinitely, rewrite our Cassandra layer to use something else, or fix the driver ourselves.

why not just switch

Switching looked easy on paper. In practice the codebase had Cassandra-specific types everywhere — Cassandra\Uuid, Cassandra\Timestamp, Cassandra\Bigint — not because of architectural brilliance but because the extension had its own type system and those types had leaked into application code over years. Replacing the driver meant touching hundreds of files. And we had no guarantee that a different client library would give us the same behavioral semantics — retry policies, paging state, consistency levels.

There was also no other option in the PHP ecosystem. No community-maintained pure-PHP client existed that came close in performance — the extension is a thin wrapper over the ScyllaDB C/C++ driver, which means shard-aware routing and native binary protocol handling at C++ speed. A pure-PHP implementation would have been an order of magnitude slower. The realistic alternatives were: stay on PHP 7 until it became a security liability, or abandon PHP entirely and rewrite the service in another language.

Staying on PHP 7 was not a permanent answer. Security patches. Framework compatibility. PHP 7 EOL was already behind us. Rewriting the service was months of work with no guarantee the result would be better. So I forked the driver and started reading Zend source.

learning the zend engine the hard way

PHP extensions are C code that hooks into the Zend Engine through a set of macros and function tables. In principle that is not complicated. In practice the codebase I inherited had been written to support PHP 5, 6, and 7 simultaneously through a layer of compatibility macros with names like PHP5TO7_ZEND_OBJECT, PHP5TO7_ZEND_HASH_FOREACH_STR_KEY_VAL, and PHP5TO7_ZVAL_MAYBE_DESTROY. There were dozens of them, some wrapping trivial one-liners, some hiding real semantic differences between PHP versions.

The Zend Engine's object model changed significantly between PHP 7 and PHP 8. zend_parse_parameters deprecated half its format specifiers. get_properties and get_gc handlers changed signatures. And the macros — originally written to smooth over the 5→7 transition — did not account for 8 at all.

I fixed the compile errors. PHP 8.0 worked. Then 8.1. Then 8.2, which introduced new deprecations of its own — __toString prototype mismatches, zend_hash_sort API changes. Each minor version was another round of "which macro is lying to me now."

This was also when I realized the original driver had been written in C, and that C was making the maintenance problem worse. Not because C is wrong for PHP extensions — it is perfectly valid — but because the compatibility macro layer had produced code that was almost impossible to read. You needed three mental translation steps to understand what any given function actually did at runtime.

the decision i still regret

In March 2023 I renamed every .c file to .cpp. All of them. In one pull request.

The rationale made sense at the time: C++ gives you RAII, references that cannot be null, std::string instead of manual char * arithmetic, better type inference. The Zend API is a C API but you can call it from C++ with extern "C". ScyllaDB's own C/C++ driver — which we wrap — is C++ already. The pieces would fit together.

What I underestimated was how much of the existing code relied on C idioms that do not translate cleanly to C++: implicit void * casts everywhere, VLAs, designated initializers used in ways the C++ standard does not permit. The conversion produced warnings. Some warnings were bugs. Tracking down which was which took months.

And the toolchain story got harder. Finding people who were comfortable contributing to a PHP extension was already difficult. Finding people comfortable with a PHP extension written in C++ that wraps a C++ driver and uses CMake — that narrowed the pool considerably.

I would have been better off keeping C and just deleting the compatibility macro layer one file at a time. The abstraction was the problem, not the language.

cmake and the build system swamp

The original extension used config.m4 — the PHP build system, based on autoconf. It worked, but it was opaque, hard to extend, and did not give you any way to express modern dependency relationships cleanly. Adding the ScyllaDB C/C++ driver as a bundled dependency was painful.

I replaced it with CMake. That decision I do not regret — CMake at least has documentation you can actually read. But learning it was its own project. The PHP extension build model assumes phpize generates your Makefile. CMake generates its own build system and has to replicate what phpize does: finding the PHP headers, setting the correct CFLAGS, linking against the right interpreter library, installing the .so to the right extension directory.

Getting that working took several iterations. Getting it to work on GitHub Actions — across PHP 8.1, 8.2, 8.3, multiple Linux distributions, both thread-safe and non-thread-safe builds — took longer. The CI was a second project hiding inside the first one. There were commits like fix(release): release fixed appearing three times in a row because I had been testing the release workflow by pushing tags and watching it fail.

libuv was its own subplot. The ScyllaDB C++ driver depends on libuv. Building libuv as a static dependency and linking it into a shared .so requires -fPIC everywhere. Miss it in one place — the C++ driver's own cmake build, for instance — and you get a linker error that looks completely unrelated to the actual cause. I have that error memorized.

daniel and he4rt

At some point in 2023, Daniel — danielhe4rt — joined ScyllaDB and started looking at the PHP driver situation. He found the fork, sent a message, and we started working on it together under the he4rt organization.

Working with Daniel changed the pace of the project. He had a different focus — documentation, making the thing actually approachable for people who were not deep in the Zend internals — which complemented the low-level work I was doing. The test suite migrated from Behat to Pest. The README became legible. The he4rt organization became the home for the project.

The driver got PHP 8.3 support in late 2023. PIE packaging in early 2025. macOS and Apple Silicon in 2026. Each of those required fixing something that had been quietly broken for a while.

where it is now

The codebase is functional but not clean. There are still hundreds of PHP5TO7_* macros in the source — the same ones that caused problems in 2022 — because removing them safely requires understanding each one individually and verifying the replacement compiles and behaves correctly across every supported PHP version. We are doing this in staged waves. Wave 1 is done. Wave 2 is in progress.

The PHP stubs — .stub.php files that describe the extension's public API and generate the argument info tables that PHP uses for reflection, named arguments, and IDE support — are about 70% complete. The remaining classes have hand-written arginfo that was correct for PHP 7 and may or may not be correct now.

PHP 8.5 is coming. Some of the GC handler signatures changed again. Those fixes are already in.

what i want to do next

AI tooling has made this kind of mechanical refactoring much faster than it used to be. Working through the macro purge with an AI assistant that understands the Zend API has compressed weeks of careful reading into days. I want to spend more structured time on the project this year — not just fixing what's broken when someone files an issue, but actually finishing the cleanup work that has been sitting in the backlog.

That means completing the stub coverage, removing the remaining PHP5TO7 macros, getting the full test suite green across PHP 8.2 through 8.5, and publishing proper releases on a predictable schedule. The PIE packaging is already there. The GitHub Actions pipeline works. The pieces exist; they need to be connected.

The driver is useful. People are using it — in Serbia, in Brazil, in teams I have never talked to who found it through Packagist. That matters enough to do the job properly.

There is also a series of posts I want to write alongside this work. The PHP extension ecosystem has almost no approachable documentation for people starting from scratch in 2025. Most tutorials assume autoconf, PHP 7, and C89. I want to write about building a PHP extension from zero using C23 and CMake — including the bridge between CMake and the config.m4 build system that phpize expects, which is the part nobody documents clearly. And about publishing it on PIE, the modern PHP extension installer that finally makes distributing compiled extensions sane.

Beyond C, the official stance is that PHP extensions must be written in C or C++. That is technically true — the Zend API is a C API — but it is not the whole story. Rust can call C APIs. Zig can call C APIs. You can write the glue layer in C and implement the actual logic in whatever compiled language you want. I plan to write about that: what it actually takes to build a PHP extension in Rust, in Zig, in anything that can produce a shared library and link against libphp. The ecosystem deserves more than one path.

what it isn't

It is not an official ScyllaDB product — even though I now work at ScyllaDB. It started as a community fork of an abandoned DataStax project and that is still what it is. Nothing here represents ScyllaDB's roadmap or commitments.
It does not have a test suite that covers every API surface. Large sections of the schema metadata API are untested.
It does not have a stable ABI across PHP minor versions. You recompile for each PHP version. This is true of all PHP extensions, but worth stating.
The C-to-C++ migration added real complexity. Contributing to this extension requires understanding both the Zend C API and C++17. That is a higher bar than it should be.
The macro cleanup is not done. There are correctness bugs hiding in the legacy layer. We find them by running the test suite, and the test suite does not cover everything yet.

The project is in a better place than it was in 2022. It is not where I want it to be. I am still working on it.