README

A simple, secure, and highly customizable caching engine for PHP. This library provides time-based caching with built-in encryption support, making it suitable for application-level, server-level, and database-level caching scenarios.

Features

• Instance-based API — fully DI-friendly, multiple cache pools can coexist
• Static facade (CacheFacade) for quick usage without DI
• Time-based caching with configurable TTL (Time-to-Live)
• Built-in encryption for sensitive data protection
• Multiple storage backends (File-based and Redis included, extensible via Storage interface)
• Key prefixing for namespace isolation (withPrefix() returns a new instance — no mutation)
• Expired item cleanup via purgeExpired()
• Comprehensive error handling with custom exceptions

Installation

composer require webfiori/cache

Supported PHP Versions

This library requires PHP 8.1 or higher.

Build Status

Quick Start

<?php
require_once 'vendor/autoload.php';

use WebFiori\Cache\Cache;
use WebFiori\Cache\FileStorage;
use WebFiori\Cache\KeyManager;

// Set up encryption key (recommended for production)
$_ENV['CACHE_KEY'] = KeyManager::generateKey();

// Create a cache instance
$cache = new Cache(new FileStorage('/path/to/cache'));

// Store and retrieve
$cache->set('greeting', 'Hello, World!', 3600);
echo $cache->get('greeting'); // Hello, World!

// Auto-populate on cache miss using a generator callback
$data = $cache->get('user_data', function () {
    return fetchUserDataFromDatabase();
}, 3600);

// Check, delete, flush
$cache->has('greeting');   // true
$cache->delete('greeting');
$cache->flush();

For a complete runnable version of this, see the Set and Get example.

Usage

Basic Operations

use WebFiori\Cache\Cache;
use WebFiori\Cache\FileStorage;

$cache = new Cache(new FileStorage('/path/to/cache'));

// Store with default TTL (60 seconds)
$cache->set('key', 'value');

// Store with custom TTL and override existing
$cache->set('key', 'new_value', 3600, true);

// Retrieve (returns null on miss)
$data = $cache->get('key');

// Generator with parameters
$profile = $cache->get('user_profile', function ($userId, $includePrefs) {
    return fetchUserProfile($userId, $includePrefs);
}, 3600, [123, true]);

// Update TTL of existing item
$cache->setTTL('key', 7200);

// Enable/disable caching (useful for debugging)
$cache->setEnabled(false);

Working examples for each operation: basic examples

Prefix Isolation

withPrefix() returns a new Cache instance — the original is never mutated.

$users = $cache->withPrefix('users_');
$orders = $cache->withPrefix('orders_');

$users->set('count', 100, 60);
$orders->set('count', 250, 60);

$users->get('count');  // 100
$orders->get('count'); // 250

// Flush only one prefix
$users->flush();

See Prefix Isolation and Prefix Flush.

Static Facade

For quick usage without dependency injection, use CacheFacade:

use WebFiori\Cache\CacheFacade;

CacheFacade::set('key', 'value', 60);
echo CacheFacade::get('key');

// withPrefix() returns a Cache instance
CacheFacade::withPrefix('users_')->set('count', 100, 60);

Security & Encryption

Cached data is encrypted using AES-256-CBC when an encryption key is available. If no key is set, data is stored unencrypted. Configure via environment variables or programmatically:

# 64-character hexadecimal encryption key (required for encryption)
CACHE_KEY=your64characterhexadecimalencryptionkeyhere1234567890abcdef

# Optional settings
CACHE_ENCRYPTION_ENABLED=true
CACHE_ENCRYPTION_ALGORITHM=aes-256-cbc
CACHE_FILE_PERMISSIONS=600
CACHE_DIR_PERMISSIONS=700

use WebFiori\Cache\KeyManager;

// Generate and set a key programmatically
$key = KeyManager::generateKey();
KeyManager::setEncryptionKey($key);

See Encryption Key Management, Security Config, and Encrypt/Decrypt Round-Trip.

Redis Storage

A built-in Redis backend is available via RedisStorage. It requires the ext-redis PHP extension and a connected \Redis instance:

use WebFiori\Cache\Cache;
use WebFiori\Cache\RedisStorage;

$redis = new Redis();
$redis->connect('127.0.0.1', 6379);

$storage = new RedisStorage($redis, 'wf_cache:');
$cache = new Cache($storage);

$cache->set('key', 'value', 3600);
echo $cache->get('key'); // value

Redis handles TTL natively, so expired items are removed automatically — no need for purgeExpired().

See Redis Storage for a full example.

Custom Storage Drivers

Implement the Storage interface to create custom backends (e.g., Memcached, database):

use WebFiori\Cache\Storage;
use WebFiori\Cache\Item;

class MemoryStorage implements Storage {
    public function store(Item $item) { /* ... */ }
    public function read(string $key, ?string $prefix) { /* ... */ }
    public function readItem(string $key, ?string $prefix): ?Item { /* ... */ }
    public function has(string $key, ?string $prefix): bool { /* ... */ }
    public function delete(string $key) { /* ... */ }
    public function flush(?string $prefix) { /* ... */ }
    public function purgeExpired(): int { /* ... */ }
}

$cache = new Cache(new MemoryStorage());

Full working implementation: Custom Storage Driver.

API Reference

Cache Class (Instance Methods)

CacheFacade Class (Static Methods)

Same methods as Cache, plus:

Item Class

Storage Interface

Error Handling

See Error Handling for all cases.

Upgrading from v2

v3 changes Cache from a static singleton to an instance class. Migration is straightforward:

// v2 (static singleton)                    // v3 (instance-based)
Cache::set('k', 'v', 60);                  $cache = new Cache(new FileStorage($path));
Cache::get('k');                            $cache->set('k', 'v', 60);
                                            $cache->get('k');

Cache::withPrefix('x')->get('k');           $cache->withPrefix('x')->get('k');
// ⚠️ prefix leaked to all future calls    // ✅ prefix is scoped, original unchanged

Cache::setDriver($driver);                  $cache = new Cache($driver);

Cache::create($driver, true, 'pfx');        new Cache($driver, true, 'pfx');

If you prefer the static API, use CacheFacade — it works identically to v2's Cache:

use WebFiori\Cache\CacheFacade;

CacheFacade::set('k', 'v', 60);
CacheFacade::get('k');

Examples

The examples/ directory contains 23 self-contained, runnable samples organized by difficulty:

Basic — Core operations every user needs:

Advanced — Security, extensibility, and error handling:

Run any example:

composer install
php examples/basic/01-set-and-get/index.php

License

This library is licensed under MIT License. See LICENSE file for more details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite: composer test
6. Submit a pull request

Support

• Issues: GitHub Issues
• Documentation: This README and examples/