DEV Community: Dusan Malusev

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.