Alpha ZealPHP is early-stage and under active development. APIs may change between minor versions until v1.0. Feedback and bug reports welcome on GitHub.
Esc
API Index — Namespaces, Packages, Reports, Indices

Cache
in package

Cache — Tiered key-value cache (memory + file)

General-purpose cache with a dead-simple API. Two tiers: Tier 1: In-memory via Store (OpenSwoole\Table) — fast, cross-worker, volatile Tier 2: File-based (.cache/ directory) — persistent, survives restarts

Every set() writes through to both tiers. get() checks memory first, falls back to file. TTL-based expiry with lazy cleanup + periodic GC timer.

Usage:

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

// Anywhere (any worker):
Cache::set('user:42', $profile, ttl: 300);
$profile = Cache::get('user:42');
Cache::has('user:42');
Cache::del('user:42');

LIMITATIONS — when to use Redis/Valkey instead:

  • Multi-server: Cache is per-server. Redis shares state across machines.
  • Large datasets: Memory tier caps at maxRows (default 4096), 8KB per value.
  • Pub/Sub: No built-in publish/subscribe between workers or servers.
  • Data structures: No sorted sets, streams, Lua scripting. Flat KV only.
  • Persistence: File tier is best-effort. Redis AOF/RDB is crash-safe.
  • Eviction: No LRU/LFU. Full memory tier spills to file-only.
  • Transactions: No MULTI/EXEC. Store has per-row spinlocks only.

Table of Contents

Constants

MAX_MEM_SIZE  : mixed = 8192
TABLE  : mixed = '__cache'

Properties

$dir  : string
$hitsFile  : Counter|null
$hitsMem  : Counter|null
$initialized  : bool
$misses  : Counter|null
$spillsFile  : Counter|null
$spillsFull  : Counter|null

Methods

clear()  : bool
Alias for flush() — PSR-16 naming convention. Returns true.
count()  : int
Number of entries in memory tier (may include expired).
del()  : bool
Delete from both tiers.
delete()  : bool
Alias for del() — PSR-16 naming convention.
flush()  : void
Clear all cache entries from both tiers.
get()  : mixed
Retrieve a value. Memory tier checked first, file tier as fallback.
has()  : bool
Check existence without deserializing. Respects TTL.
init()  : void
Initialize the cache. Must be called before $app->run().
set()  : bool
Store a value. Writes to both memory and file tiers.
stats()  : array{memory_entries: int, hits_memory: int, hits_file: int, misses: int, spills_oversize: int, spills_full: int, hit_rate: float}
Cache performance stats. All counters are cross-worker (atomic).
filePath()  : string
readFile()  : mixed
registerGc()  : void
writeFile()  : bool

Constants

MAX_MEM_SIZE

private mixed MAX_MEM_SIZE = 8192

TABLE

private mixed TABLE = '__cache'

Properties

$dir

private static string $dir = ''

$initialized

private static bool $initialized = false

Methods

clear()

Alias for flush() — PSR-16 naming convention. Returns true.

public static clear() : bool
Return values
bool

count()

Number of entries in memory tier (may include expired).

public static count() : int
Return values
int

del()

Delete from both tiers.

public static del(string $key) : bool
Parameters
$key : string
Return values
bool

delete()

Alias for del() — PSR-16 naming convention.

public static delete(string $key) : bool
Parameters
$key : string
Return values
bool

flush()

Clear all cache entries from both tiers.

public static flush() : void

get()

Retrieve a value. Memory tier checked first, file tier as fallback.

public static get(string $key[, mixed $default = null ]) : mixed
Parameters
$key : string
$default : mixed = null

has()

Check existence without deserializing. Respects TTL.

public static has(string $key) : bool
Parameters
$key : string
Return values
bool

init()

Initialize the cache. Must be called before $app->run().

public static init([int $maxRows = 4096 ][, string|null $cacheDir = null ][, int $gcIntervalMs = 60000 ]) : void
Parameters
$maxRows : int = 4096

Max entries in memory tier (default 4096)

$cacheDir : string|null = null

File tier directory (default: .cache/ in project root)

$gcIntervalMs : int = 60000

GC sweep interval in ms (default 60000)

set()

Store a value. Writes to both memory and file tiers.

public static set(string $key, mixed $value[, int $ttl = 0 ]) : bool

Values larger than 8KB are stored in file tier only.

Parameters
$key : string
$value : mixed
$ttl : int = 0
Return values
bool

stats()

Cache performance stats. All counters are cross-worker (atomic).

public static stats() : array{memory_entries: int, hits_memory: int, hits_file: int, misses: int, spills_oversize: int, spills_full: int, hit_rate: float}

Returns: [ 'memory_entries' => int, // current rows in memory tier 'hits_memory' => int, // get() served from memory 'hits_file' => int, // get() served from file (memory miss) 'misses' => int, // get() found nothing 'spills_oversize' => int, // set() skipped memory (value > 8KB) 'spills_full' => int, // set() skipped memory (table full) 'hit_rate' => float, // hits / (hits + misses), 0.0–1.0 ]

Return values
array{memory_entries: int, hits_memory: int, hits_file: int, misses: int, spills_oversize: int, spills_full: int, hit_rate: float}

filePath()

private static filePath(string $hash) : string
Parameters
$hash : string
Return values
string

readFile()

private static readFile(string $hash) : mixed
Parameters
$hash : string

registerGc()

private static registerGc(int $intervalMs) : void
Parameters
$intervalMs : int

writeFile()

private static writeFile(string $hash, string $serialized, int $expires) : bool
Parameters
$hash : string
$serialized : string
$expires : int
Return values
bool
On this page