Cache

Cache System

Razy provides a PSR-16 compatible caching layer with a static facade, pluggable storage adapters, and file-validation support. The Cache system supports File, Redis, APCu, and Null adapters out of the box.

---

Table of Contents

• Quick Start
• Initialization
• Basic Operations
• Batch Operations
• File-Validated Cache
• Adapters
  • FileAdapter
  • RedisAdapter
  • ApcuAdapter
  • NullAdapter
• Graceful Degradation
• API Reference

---

Quick Start

use Razy\Cache;
use Razy\Cache\FileAdapter;

// Initialize with file adapter
Cache::initialize('/path/to/cache', new FileAdapter('/path/to/cache'));

// Store and retrieve values
Cache::set('user.profile.123', $userData, ttl: 3600);
$profile = Cache::get('user.profile.123');

// Check existence
if (Cache::has('user.profile.123')) {
    // cached
}

// Delete
Cache::delete('user.profile.123');

---

Initialization

The Cache facade must be initialized before use. If not initialized, it auto-initializes with a NullAdapter (no-op):

use Razy\Cache;
use Razy\Cache\FileAdapter;
use Razy\Cache\RedisAdapter;

// File-based cache
Cache::initialize('/var/cache/razy', new FileAdapter('/var/cache/razy'));

// Redis-based cache
$redis = new Redis();
$redis->connect('127.0.0.1', 6379);
Cache::initialize('', new RedisAdapter($redis, 'myapp_'));

// Check status
Cache::isInitialized(); // true

// Enable/disable at runtime (disabled = NullAdapter behavior)
Cache::setEnabled(false);
Cache::isEnabled(); // false

// Swap adapter at runtime
Cache::setAdapter(new RedisAdapter($redis));

// Get current adapter
$adapter = Cache::getAdapter();

---

Basic Operations

All operations follow the PSR-16 SimpleCacheInterface contract:

use Razy\Cache;

// SET ??store a value with optional TTL
Cache::set('key', 'value');                    // no expiry
Cache::set('key', 'value', 3600);              // expires in 1 hour (seconds)
Cache::set('key', 'value', new DateInterval('PT1H')); // DateInterval TTL

// GET ??retrieve with optional default
$value = Cache::get('key');                    // returns null if missing
$value = Cache::get('key', 'fallback');        // returns 'fallback' if missing

// HAS ??check existence
if (Cache::has('key')) {
    // ...
}

// DELETE ??remove a single entry
Cache::delete('key');

// CLEAR ??remove all entries
Cache::clear();

---

Batch Operations

Efficiently read/write multiple keys in a single call:

// SET multiple values
Cache::setMultiple([
    'user.1' => $user1,
    'user.2' => $user2,
    'user.3' => $user3,
], ttl: 3600);

// GET multiple values
$users = Cache::getMultiple(['user.1', 'user.2', 'user.3']);
// Returns: ['user.1' => $user1, 'user.2' => $user2, 'user.3' => $user3]

// GET with default for missing keys
$users = Cache::getMultiple(['user.1', 'user.999'], default: null);
// Returns: ['user.1' => $user1, 'user.999' => null]

// DELETE multiple
Cache::deleteMultiple(['user.1', 'user.2']);

---

File-Validated Cache

A unique Razy feature that ties cached data to a source file's modification time. If the file changes, the cache is automatically invalidated:

// Cache compiled template ??auto-invalidates when template.html changes
Cache::setValidated(
    key: 'template.compiled.main',
    filePath: '/path/to/template.html',
    data: $compiledTemplate,
    ttl: 86400
);

// Retrieve ??returns null if file has been modified since caching
$compiled = Cache::getValidated(
    key: 'template.compiled.main',
    filePath: '/path/to/template.html'
);

if ($compiled === null) {
    // File changed or cache expired ??recompile
    $compiled = compileTemplate('/path/to/template.html');
    Cache::setValidated('template.compiled.main', '/path/to/template.html', $compiled);
}

How it works: setValidated() stores the file's mtime alongside the cached data. getValidated() compares the stored mtime with the current file's mtime ??if they differ, the cache entry is considered stale and returns $default.

---

Adapters

FileAdapter

Directory-sharded file cache with atomic writes. Files are stored as {dir}/{xx}/{md5}.cache:

use Razy\Cache\FileAdapter;

$adapter = new FileAdapter('/var/cache/razy');

// All PSR-16 methods available
$adapter->set('key', 'value', 3600);
$value = $adapter->get('key');

// File-specific extras
$stats = $adapter->getStats();
// Returns: ['directory' => '/var/cache/razy', 'files' => 142, 'size' => 1048576]

// Garbage collection ??removes expired entries, returns count removed
$removed = $adapter->gc();

Features:

• Atomic writes via temp file + rename (crash-safe)
• Two-character directory sharding (e.g. ab/abcdef123456.cache)
• Lazy purge on read (expired entries deleted when accessed)
• Windows-compatible file handling
• Key validation rejects PSR-16 reserved characters: {}()/\@:

RedisAdapter

High-performance Redis-backed cache:

use Razy\Cache\RedisAdapter;

$redis = new Redis();
$redis->connect('127.0.0.1', 6379);
$redis->auth('password');
$redis->select(2);

$adapter = new RedisAdapter($redis, prefix: 'myapp_');

// Access underlying Redis instance
$redis = $adapter->getRedis();

Features:

• Configurable key prefix (default: 'razy_')
• serialize/unserialize for complex PHP values
• Batch getMultiple uses Redis MGET for efficiency
• clear() with prefix uses SCAN to delete only prefixed keys (safe for shared Redis)

ApcuAdapter

Shared memory cache via APCu extension:

use Razy\Cache\ApcuAdapter;

// Requires ext-apcu
$adapter = new ApcuAdapter(prefix: 'myapp_');

Features:

• High performance (shared memory, no I/O)
• clear() uses APCuIterator with prefix regex to only clear own entries
• Best for single-server deployments

NullAdapter

No-op adapter for testing or disabled cache mode:

use Razy\Cache\NullAdapter;

$adapter = new NullAdapter();
$adapter->get('key');     // always returns default
$adapter->set('key', 1);  // always returns true
$adapter->has('key');      // always returns false

---

Graceful Degradation

All Cache facade operations wrap adapter calls in try/catch(\Throwable). If an adapter throws (e.g. Redis connection lost), the operation fails silently and returns the default/false:

// Even if Redis is down, this won't crash your application
$value = Cache::get('key', 'fallback'); // returns 'fallback'
Cache::set('key', 'value');             // returns false

When the cache is disabled via Cache::setEnabled(false), all operations behave as if using the NullAdapter.

---

API Reference

Cache Facade (Static)

Method	Signature	Description
initialize	(string $cacheDir, ?CacheInterface $adapter): void	Set up cache system
isInitialized	(): bool	Check if initialized
setEnabled	(bool $enabled): void	Enable/disable caching
isEnabled	(): bool	Check if enabled
getAdapter	(): CacheInterface	Get current adapter
setAdapter	(CacheInterface $adapter): void	Swap adapter
get	(string $key, mixed $default = null): mixed	Retrieve value
set	(string $key, mixed $value, int|DateInterval|null $ttl = null): bool	Store value
delete	(string $key): bool	Remove entry
clear	(): bool	Remove all entries
has	(string $key): bool	Check existence
getMultiple	(iterable $keys, mixed $default = null): iterable	Batch retrieve
setMultiple	(iterable $values, int|DateInterval|null $ttl = null): bool	Batch store
deleteMultiple	(iterable $keys): bool	Batch remove
getValidated	(string $key, string $filePath, mixed $default = null): mixed	File-validated get
setValidated	(string $key, string $filePath, mixed $data, int|DateInterval|null $ttl = null): bool	File-validated set
reset	(): void	Reset facade state

FileAdapter Extras

Method	Signature	Description
getStats	(): array{directory, files, size}	Cache directory statistics
gc	(): int	Garbage collect expired entries

??Previous: Collection Validation