Forem: Dusan Malusev

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.