Store & Counter

OpenSwoole adapters for cross-worker shared memory. Must be created before $app->run() so all forked workers inherit the same memory segment.

// Before app->run():
Store::make('demo_table', 128, [
    'name'  => [Store::TYPE_STRING, 64],
    'score' => [Store::TYPE_INT,    4],
]);

// In any route (any worker):
Store::set('demo_table', 'user_1', ['name' => 'alice', 'score' => 100]);
$row = Store::get('demo_table', 'user_1');
// → ['name' => 'alice', 'score' => 100]

echo Store::count('demo_table'); // total rows across all workers

// Atomically increment a counter column
Store::set('demo_table', 'page_hits', ['score' => 0]);
$new = Store::incr('demo_table', 'page_hits', 'score');
// → 1 (atomic, safe under concurrent workers)

// Before app->run():
$requestCounter = new Counter(0);

// In any route:
$app->route('/demo/counter/increment', function() use ($requestCounter) {
    $new = $requestCounter->increment();
    return ['total_requests' => $new, 'pid' => getmypid()];
    // Every worker shares the same atomic integer
});

Store API reference

Cache — general-purpose key-value with TTL

Tiered cache built on Store. Memory tier (fast, cross-worker) + file tier (persistent, survives restarts). No Redis needed for most apps.

// Before $app->run():
Cache::init();

// Anywhere (any worker):
Cache::set('user:42', $profileArray, ttl: 300);   // any PHP value, auto-serialized
$profile = Cache::get('user:42');                  // memory first, file fallback
Cache::has('user:42');                             // TTL-aware existence check
Cache::del('user:42');                             // removes from both tiers
Cache::flush();                                    // clear everything

Consistency semantics — what's atomic, what isn't

Store is shared memory, not a database. The atomicity guarantees are narrow and important to understand before reaching for it in production.

What happens on worker crash mid-write

The honest answer: it depends on how the worker died.

Pluggable backends — Table / Redis / Tiered / Memcached

As of v0.2.39, Store and Counter are backend-agnostic. Four backends ship in-tree; pick by scope. Every Store::set/get/incr/count call works unchanged across all four.

use ZealPHP\Store;

// Recommended — type-safe enum (IDE autocomplete + refactor-safe):
Store::defaultBackend(Store::BACKEND_TABLE);                                // default
Store::defaultBackend(Store::BACKEND_REDIS, 'redis://cache.internal:6379'); // cross-node
Store::defaultBackend(Store::BACKEND_TIERED, [                              // ns reads + cross-node truth
    'url'                 => 'redis://cache.internal:6379',
    'l1_ttl'              => 5,                              // L1 freshness window (seconds)
    'invalidation_secret' => getenv('ZEALPHP_TIERED_INVALIDATION_SECRET') ?: null,
]);

// Bare strings still work for BC (also: ZEALPHP_STORE_BACKEND=redis|tiered env):
Store::defaultBackend(Store::BACKEND_REDIS);
Store::defaultBackend(Store::BACKEND_TIERED, 'redis://cache:6379');

Two table modes at make(): 'tracked' (default) keeps a membership SET so count() is O(1); 'ttl' supports per-key expiry but count() falls back to O(N) SCAN. Pick one per table. Mixing tracked + ttl throws at boot (v0.2.41 hardening — H1). The connection pool is per-worker (default 8 clients) — concurrent coroutines never share a socket.

Client lib: auto-detects phpredis (preferred when ext-redis is loaded) or predis (pure-PHP fallback, shipped as a dev dep). User code never imports a phpredis/predis symbol — the single ZealPHP\Store\RedisClient adapter is the only place either lib is referenced.

Backend scope — what "single process" really means

OpenSwoole\Table is shared memory allocated by the master process BEFORE fork, inherited by all worker processes of that server. So the Table backend is:

• Shared across coroutines in one worker ✓
• Shared across workers in one OpenSwoole server ✓ (the whole point)
• NOT shared across two php app.php invocations on the same machine ✗ (different mmap segments)
• NOT shared across machines ✗

For cross-server state, use Redis or Tiered. For cross-tab/cross-tenant WS routing where state must survive node death, see /pubsub#ws-routing.

Memory math for the Table backend

maxRows is allocated UP FRONT at the OpenSwoole master fork, not lazily. Empirically (PHP 8.3 + OpenSwoole 22.x):

Rule of thumb: RAM ≈ maxRows × (4 × Σ column sizes + ~32 B/row). The 4× factor is OpenSwoole's open-addressed-hash overcommit. For Cache::init(4096) with the default 8 KB value column: ~130 MB reserved per worker server. When you'd say "tens of millions of rows", flip to Redis (server-side bound) or Tiered (L1 stays small, L2 grows).

Cache::init & the maxRows chokepoint

Cache::init($maxRows, $cacheDir, $gcIntervalMs, $ttlSeconds) behaves differently across backends — flagged at boot when misconfigured (v0.2.41 hardening):

• Table backend: $maxRows is a HARD CAP. Cache spills oversize / overflow to the file tier automatically.
• Redis backend: $maxRows has NO equivalent — Redis is a global KV store. Pair with $ttlSeconds for per-key auto-expiry, OR configure Redis-server maxmemory + maxmemory-policy allkeys-lru for cluster-wide bound. If you pass a non-default $maxRows without a TTL on the Redis backend, Cache::init() emits a one-line warning telling you so.
• Tiered backend: L1 honours $maxRows (Table); L2 (Redis) ignores it as above.

// Recommended Redis-backed Cache config — bounded by per-key TTL:
Cache::init(
    maxRows:    4096,      // HARD CAP on Table; informational on Redis
    cacheDir:   '/var/cache',
    ttlSeconds: 3600,      // On Redis → mode='ttl' auto-expiry
);

// Read-through pattern — canonical helper (no more get-then-compute boilerplate):
$users = Cache::getOrCompute("users:active", fn() => DB::select(...), ttl: 60);
// First call computes + caches; subsequent calls within TTL short-circuit to the cached read.
// Null is cached as a valid value (sentinel-based miss detection).

Pub/sub + Streams (cross-node messaging)

Two public primitives on top of the Redis backend for cross-worker AND cross-host messaging. Both require Store::defaultBackend(Store::BACKEND_REDIS).

// Fire-and-forget pub/sub
App::subscribe('chat:room:42', function (string $payload, string $channel) {
    // runs in every worker that's registered; routes to your local fd map
});
$receivers = Store::publish('chat:room:42', json_encode($message));

// Reliable variant via Redis Streams (at-least-once via consumer groups)
App::subscribeReliable('orders', function (string $payload, string $id, string $stream): bool {
    $ok = processOrder($payload);
    return $ok; // true → XACK; false/throw → leave pending
});
$messageId = Store::publishReliable('orders', json_encode($order));

Store::defaultBackend(Store::BACKEND_REDIS, [
    'url'    => 'redis://cache:6379/0',
    'prefer' => Store::PREFER_PREDIS,   // or Phpredis (default when ext loaded)
]);
// Or via env: ZEALPHP_REDIS_PREFER=predis

Receiver count semantics: Store::publish delivers ONE copy to every worker (across every node) running a matching subscriber. So 32 workers per node × 2 nodes = receivers: 64 for one PUBLISH. That's correct Redis pub/sub — matches the cross-server WebSocket routing pattern where each worker owns a subset of fds.

Atomic Lua — Store::eval()

For multi-step operations that must be atomic (read-modify-write, conditional set-membership), run a Lua script server-side. Available on the Redis / Tiered backend (throws on Table).

// Keys are raw/absolute (like publish); values pass as KEYS/ARGV — never
// interpolated into the script body. Returns whatever the script returns.
$n = Store::eval(
    "local v = redis.call('INCR', KEYS[1])\n" .
    "if v == 1 then redis.call('SADD', KEYS[2], ARGV[1]) end\n" .
    "return v",
    keys: ['room:42:count', 'room:42:servers'],
    args: [$serverId],
);

Live demo — this very server

Each button below fires a real HTTP request against the running ZealPHP instance. Output panel shows the JSON the server returned. Most useful with ZEALPHP_STORE_BACKEND=redis; on the default Table backend the pub/sub buttons surface a clean StoreException error in JSON.

Click a button above to fire a request. The response JSON will land here.

Redis Cluster / Sentinel

For HA topologies that span multiple Redis nodes (Cluster) or use a failover monitor (Sentinel), drive the driver with a pre-wired Predis\Client instead of a URL string. Predis natively supports both topologies via its constructor parameters — ZealPHP’s adapter accepts the prebuilt client and uses it as-is for the connection pool.

use Predis\Client as PredisClient;
use ZealPHP\Store\{RedisBackend, RedisConnectionPool, PredisDriver};

// === Cluster (3-node, key-slot routing) ===
$cluster = new PredisClient(
    ['tcp://node1:7000', 'tcp://node2:7000', 'tcp://node3:7000'],
    ['cluster' => 'redis'],
);
// Wire as the Store backend (pool of 1 because Cluster manages its own connections):
$backend = new RedisBackend(
    new RedisConnectionPool(
        url: 'unused-for-cluster',
        size: 1,
        opts: ['prefer' => Store::PREFER_PREDIS],   // phpredis Cluster needs RedisCluster — future v0.2.41
    ),
);
// Or simpler — bypass the URL+pool layer:
$driver = new PredisDriver($cluster);

// === Sentinel (master/slave failover) ===
$sentinel = new PredisClient(
    ['tcp://sentinel1:26379', 'tcp://sentinel2:26379'],
    ['replication' => 'sentinel', 'service' => 'mymaster'],
);
$driver = new PredisDriver($sentinel);

First-class Store-facade integration (a Store::clusterBackend() / Store::sentinelBackend() helper) is on the v0.2.41 roadmap. Today's path is to construct the Predis\Client + PredisDriver directly and inject into a RedisBackend. phpredis users wanting Cluster/Sentinel should currently use predis (set ZEALPHP_REDIS_PREFER=predis); the RedisCluster phpredis class needs a separate driver shape.

Production hardening (v0.2.41)

A senior-eng review of the v0.2.39/v0.2.40 Redis backend surface flagged 3 critical + 10 medium issues — all closed in this pass. Each gets a brief description + the opt-in recipe. Default behaviour is unchanged; nothing on this page is a BC break.

C3 — TLS via rediss://

Cross-region or untrusted-network deployments need encrypted Redis connections. Both drivers now recognise rediss:// (and the tls:// alias). verify_peer + verify_peer_name are on by default.

Store::defaultBackend(Store::BACKEND_REDIS, 'rediss://cache.prod:6380/0');
// or  ZEALPHP_REDIS_URL=rediss://cache.prod:6380/0

Bare redis:// (no host) is now rejected at parse time — surfaces misconfig at boot instead of after silently defaulting to 127.0.0.1.

C1 — WSRouter FD-reuse race fix

The previous cross-server WS routing pattern was vulnerable to a FD-reuse race: when client A's onClose was lost (kernel reaped the fd, OpenSwoole reassigned it to client B), an in-flight publish to A could land on B's connection — a cross-tenant data-leakage vector.

The fix is a per-connection 16-byte hex nonce stored in ws_owner.conn_id + WSRouter::$localFds[clientId]['conn_id']. WSRouter::sendToClient() carries the nonce in the publish payload; the subscriber on the owning server verifies it matches the local conn_id before pushing. Stale entries with the same fd are evicted on own() (the fd-coherence invariant).

No API change for callers — WSRouter::own($clientId, $fd) still works exactly as before; it now returns the generated conn_id for tests + debug.

C2 — HMAC-signed L1 invalidation

TieredBackend publishes invalidation messages on {prefix}:__l1_invalidate:{table}. Before this fix, anyone with Redis write access could forge invalidations and DoS L1 across the cluster. Now: optional shared secret signs every outbound message; receivers verify before evicting.

// Same secret on every node:
$tiered = new TieredBackend(
    l1: new TableBackend(),
    l2: new RedisBackend(/* … */),
    invalidationSecret: getenv('ZEALPHP_TIERED_INVALIDATION_SECRET') ?: null,
);
// Or via env: ZEALPHP_TIERED_INVALIDATION_SECRET=<32-byte-random-hex>

No secret set → trust mode (any peer message accepted; preserves the v0.2.40 default). When set, messages without a matching truncated HMAC-SHA256 are silently dropped + elog'd at warn level. Same secret on every node, or peers will reject each other's invalidations.

H1 — tracked + TTL combo throws at make()

Pre-v0.2.41 silently ignored TTL on tracked-mode tables (the membership SET would have drifted). Now it throws at make() with a clear message — fail fast at boot, not silently after the first expiry.

H2 — Store::getStrict() for new code

The legacy Store::get() returns false on miss for BC. New code that wants ??-style fallbacks safely with stored falsy values (0, '', '0') uses the strict variant — returns null on miss.

// Legacy — keep using === false to detect misses:
$row = Store::get('users', $id);
if ($row === false) { /* miss */ }

// New code — null on miss, value otherwise:
$row = Store::getStrict('users', $id);
$hits = Store::getStrict('users', $id, 'hits') ?? 0;   // 0-stored value preserved

H3 — pipelined bulk ops + UNLINK

Store::mget, Store::mset, and Store::clear on the Redis backend now run in a single MULTI/EXEC pipeline instead of N sequential round-trips. clear() uses UNLINK (non-blocking, Redis 4.0+) so multi-second clears on 10k+-row tables drop to sub-second.

No API change — existing call sites get the speedup automatically.

H4 — Circuit breaker (opt-in graceful degradation)

When Redis is degraded, every Store call previously hit the 5-second pool acquire timeout. The CircuitBreakerBackend decorator adds three-state fail-fast: closed (normal) → open (skip primary) → half-open (one probe). Reads can fall back to a Table backend; writes throw (no fallback semantics for writes — they'd diverge on recovery).

// Opt in via the connection opts:
Store::defaultBackend(Store::BACKEND_REDIS, [
    'url'      => 'redis://cache:6379',
    'on_error' => 'fallback_table',   // wraps with CircuitBreakerBackend
    'breaker'  => [
        'failure_threshold'   => 5,   // failures within window to trip
        'failure_window_sec'  => 10,  // sliding window
        'open_seconds'        => 30,  // cooldown before half-open probe
    ],
]);

// Inspect state for ops dashboards:
$b = Store::defaultBackend();
echo $b->state();  // 'closed' | 'open' | 'half-open'

Default (no opt) — no decoration, throws on Redis down (the v0.2.40 behaviour). Reads use the fallback when OPEN; writes always surface the failure to the caller.

H5 — Store::stats() operational visibility

Per-worker counter snapshot — pool acquires, pool acquire timeouts, pool clients created. Pub/sub instances expose pubsub_reconnects_total, pubsub_messages_received_total, pubsub_handler_errors_total via RedisPubSub::stats(). Wire to your monitoring of choice (Prometheus, statsd, plain log line).

// Plumb into a health endpoint:
$app->route('/health/store', fn() => Store::stats());
// → ["pool_acquires_total":1247, "pool_clients_created_total":8, ...]

H6 + H7 — boot-time advisories

• H6 (ping): when ZEALPHP_STORE_BACKEND=redis, App::run() PINGs the pool once at boot. Failure → loud error_log in the master before workers fork. Misconfigured URL surfaces immediately, not after the first request 5 seconds in.
• H7 (HOOK_ALL + phpredis): phpredis SUBSCRIBE blocks the worker without OpenSwoole\Runtime::HOOK_ALL — the production default. If you've explicitly disabled HOOK_ALL AND have App::subscribe handlers registered AND phpredis is the resolved driver, boot emits a warning telling you to either re-enable HOOK_ALL or set ZEALPHP_REDIS_PREFER=predis.

H8 — TieredBackend::existsCached()

The strict exists() always hits L2 for consistency. existsCached() returns true when L1 has a fresh entry (within $l1Ttl); otherwise defers to L2. Use on hot paths where "probably exists" + $l1Ttl-bounded staleness is acceptable — saves a Redis round-trip.

H9 + H10 — operational debug

• H9: PhpredisDriver::close() exceptions now route through elog at debug level instead of being swallowed silently — diagnosable disconnect bugs.
• H10: RedisPubSub takes an optional $maxAttempts param (default 0 = unlimited, preserving the existing eventually-reconnect behaviour). Set to N>0 to fail loudly after N consecutive reconnect cycles — useful for CI workers that should crash if Redis disappears.

Full review notes + the original risk-by-risk mapping: docs/architecture/2026-05-23-redis-backend-review.md.

When to use Redis / Valkey

Store and Cache cover most single-server apps. Here's when you'll need an external cache.