FrankenState — Shared state between Go and PHP with Redis protocol support

[johanjanssens]

PHP workers can't share state natively. Every request starts fresh. Need shared config, feature flags, or cached data? You reach for Redis adding a network hop, a server to manage, and serialization overhead for data that lives in the same process.

Note

This is a proof of concept for thread-safe shared state in FrankenPHP, demonstrating the pattern of
Go ↔ PHP data sharing, not optimized for cache-level performance. The focus is on the API and the
architecture: a single store accessible from Go, PHP, and over wire protocol.

FrankenState takes a different approach: a Go map[string]any protected by sync.RWMutex, exposed to PHP as ArrayAccess. Same process, same memory. Zero network overhead.

use FrankenPHP\SharedArray;

$state = new SharedArray();

// Read what Go pushed (e.g. server metrics, model status)
$requests = $state['server.requests'];

// Write from PHP — persists across requests, visible to Go
$state['theme'] = 'dark';
$state['config'] = ['debug' => true, 'version' => '1.0'];

// Iterate, count, bulk ops
foreach ($state as $key => $value) { ... }
$state->merge(['a' => 1, 'b' => 2]);

Any Go extension can push data that PHP sees immediately:

import "github.com/johanjanssens/frankenstate/state"

state.Set("onnx.status", "ready")
state.Set("server.requests", count)

Same data, accessible via Redis protocol:

redis-cli -p 6380 GET onnx.status    # "ready"
redis-cli -p 6380 SET theme dark
redis-cli -p 6380 INCR visitors
redis-cli -p 6380 KEYS '*'

Three access paths, one store:

Path	Use case
Go state.Set()	Extensions pushing metrics/status
PHP $state['key']	Request handlers reading/writing (cached, zero CGO)
redis-cli -p 6380	Debugging, external tools, any Redis client

The demo speaks Redis wire protocol too. The same shared memory is accessible via redis-cli, phpredis, or any language with a Redis client. No phpredis extension needed — the demo talks RESP with 40 lines of raw PHP sockets. It's not a full Redis protocol implementation but covers the basics (GET, SET, DEL, KEYS, INCR, MGET, MSET, DBSIZE, etc).

Performance: Every write (from Go, PHP, or Redis) increments an atomic version counter on the Go side. Each PHP SharedArray object caches the full snapshot locally and remembers which version it last fetched. On read, it checks the counter, if unchanged, it serves from the local zval cache with zero CGo crossings. If the version bumped (someone wrote), it fetches a fresh snapshot. This means 10 reads in a row cost one version check and zero data fetches if nothing changed.

Writes use type-specific setters for scalars, a PHP integer goes straight to Go's int64 without touching JSON. Only complex types (arrays, objects) need JSON encoding.

Approach	Read Latency	Infrastructure
Database	Slowest (network + query)	Database server
Redis	Fast (network round-trip)	Redis server
SharedArray (cache miss)	Faster (in-process CGO)	None
SharedArray (cache hit)	Fastest (local zval, zero CGO)	None

What it replaces: The real win isn't raw speed, it's eliminating infrastructure. No Redis to provision, monitor, and scale. No connection pool to manage. No serialization format to debug. The state is just... there.

This is part of the franken* family of FrankenPHP extensions:

• frankenasync — parallel PHP subrequests
• frankenwasm — WASM plugins via Extism
• frankenonnx — ONNX inference
• frankenwails — native desktop apps with PHP

Together, FrankenState + FrankenAsync replace the proposed background workers/sidekicks PR with two composable primitives, no need forpemalloc, no signaling streams, no new thread types, no Caddyfile directives.

Repo: https://github.com/johanjanssens/frankenstate
Design doc: https://github.com/johanjanssens/frankenstate/blob/main/DESIGN.md

[nickchomey]

Am i correct to view this as a sort of APCu that is available to both php and Go, and apparently also can serve as a sort of in-memory, in-process drop-in replacement for a (basic) Redis Server? If so, it's super cool!

I have a few questions:

1. Would it work in non-worker (normal php) mode? I have WordPress object caching in mind here.
2. Does it have any mechanism for evicting items from the cache (eg LRU, LFU, etc)? If not, could/should it? It might get rather large without that, and RAM is now almost as expensive as gasoline.
3. And if going in that direction, would it make sense to somehow leverage an existing Go caching package, like Otter?

And if that were to be done, perhaps the caching package could be abstracted to allow for using different Golang caches. Here's a good overview of the evolution of caching libraries. https://maypok86.github.io/otter/blog/cache-evolution/

Or perhaps that would be more hassle than it is worth, as you'd probably have to build a different static php for each.

4. Though, the real thought that I had was to allow using something like etcd or NATS KV to allow distributed and/or persistence cache. Here's a frankenphp etcd extension from Kevin https://github.com/dunglas/frankenphp-etcd. I'm curious how frankenstate might differ from that approach.

Thanks for all of your hard work and innovation!

[johanjanssens]

Thanks!

1. Yes - works in both worker and non-worker mode. The store lives in Go, persists across requests.
2. No - this is a state store, not a cache. No TTL, no eviction. Different semantics: state = "guaranteed there until removed," cache = "might expire or be evicted."
3. Possible - Otter is a cache library, which is a different concern, also require a bit more thought for the API design in PHP.

This is the simplest possible proof of concept to show how to do thread-safe shared state in FrankenPHP, exposed to PHP, Go, and over wire protocol. Everything else is possible, just needs to get built.

Since it speaks Redis protocol, adding TTL support (SET key value EX 300) and eviction is possible. Redis itself can serve both roles.

Re: etcd/NATS: FrankenState is intentionally single-process, for sharing state between threads, not between servers. You could sync from etcd into FrankenState so PHP threads read from local memory instead of making network calls per request.

[nickchomey]

Fair enough!

I contribute to a WordPress object caching plugin that uses sqlite for persistence (this is faster than even local Redis server over Unix socket, and much simpler), and also optionally uses APCu in front of that, but apcu is... not ideal... This seems like it could improve upon apcu, while also adding the extremely-useful capability of sharing the state with Go/caddy modules!

And we just clear apcu when sqlite gets too big and we evict old keys, so not really an issue that this doesn't have eviction capabilities. Its just an in-memory view of sqlite state, and would rebuild quickly

The distributed stuff is a separate concern/curiosity, so totally fine that it's way out of scope.

Looking forward to testing this out at some point!

[henderkes]

Fwiw I've implemented a badger/ristretto caching extension and the general disadvantages of Go (garbage collection, cgo bridge, required serialization) make this a no-go. For a state sharing mechanism it's fine, it just can't replace a real cache implementation like apcu. Most cache operations in apcu are in the 30-100ns range, nowhere near microseconds, let alone milliseconds.

The way I worked around it is keeping the caching in C-only, only on server start/shutdown the state is serialized and synced from C to Go.

[johanjanssens]

This is intentionally a state store, not a cache replacement. Different use case, and a more extensive discussion too. That said, the same version-gated snapshot mechanism I implemented could achieve similar read performance for caching too, cached reads are pure zval lookups, zero CGO crossing.

The real value here though is the Go side, Go extensions write directly without CGO, and external tools push data in via Redis protocol (or other protocols). That's the gap this addresses: getting data into PHP's world from outside it.

The performance is not the key focus of this POC, I added a little note to make that more clear.

[nickchomey]

Yeah, you brought up the badger/ristretto work in our ddev-frankenphp discussion. Was just curious whether these ideas would work differently with frankenstate.

Though, I don't know that extreme speed should be the sole decision factor for something like this - there's always lots of tradeoffs. Apcu also has issues like fragmentation leading to the entire cache getting cleared.

Moreover, I can foresee benefits to being able to use the state/cache from both go and php. If it comes at a small perf cost, that's surely fine.

[withinboredom]

I've got something coming down the pipe that you may be interested in... we're a couple weeks away from open sourcing it!

[johanjanssens]

If I can help, let me know.

[henderkes]

If you've been paying attention ... you've noticed I've been mysteriously quiet for a bit. This wasn't accidental. Not at all.

😂

[nickchomey]

Another thought: Im sure the read latency table in your post is just a back-of-the-napkin approximation, nor was it meant to be exhaustive.

But I think the figures are somewhat off. Eg Redis in localhost (and especially Unix sockets) can be much faster than 0.5–2 ms. And a DB 5-50ms seems slow as well - even mysql locally is faster than this, and sqlite is extremely fast.

Still, your point stands that apcu/frankenstate would be vastly faster.

[johanjanssens]

Updated it. It's merely meant as illustration.