README

A flexible, PSR-16 compliant cache library with pluggable adapters for PHP 8.1+.

Features

• Full PSR-16 (Simple Cache) compliance
• Pluggable adapter architecture
• File-based cache adapter
• Redis cache adapter
• Thread-safe file operations with LOCK_EX
• Automatic expiration handling
• Support for TTL as integer seconds or DateInterval

Installation

composer require solophp/cache

For Redis support, ensure you have the Redis PHP extension installed:

pecl install redis

Usage

File Cache

<?php

use Solo\Cache\Cache;
use Solo\Cache\Adapter\FileAdapter;

// Create file adapter
$adapter = new FileAdapter('/path/to/cache/directory');

// Create cache instance
$cache = new Cache($adapter);

// Store a value
$cache->set('user.123', ['name' => 'John', 'email' => 'john@example.com'], 3600);

// Retrieve a value
$user = $cache->get('user.123');

// Check if key exists
if ($cache->has('user.123')) {
    echo "Cache hit!";
}

// Delete a key
$cache->delete('user.123');

// Clear all cache
$cache->clear();

Redis Cache

<?php

use Solo\Cache\Cache;
use Solo\Cache\Adapter\RedisAdapter;
use Redis;

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

// Create Redis adapter (default MODE_THROW, prefix "cache:")
$adapter = new RedisAdapter($redis);

// Or with custom prefix and graceful error handling
$adapter = new RedisAdapter($redis, RedisAdapter::MODE_FAIL, 'myapp:');

// Create cache instance
$cache = new Cache($adapter);

// Use the cache
$cache->set('session.abc123', ['user_id' => 42], 7200);
$session = $cache->get('session.abc123');

// Switch error mode at runtime if needed
$adapter->setMode(RedisAdapter::MODE_FAIL);

Multiple Operations

<?php

// Set multiple values
$cache->setMultiple([
    'key1' => 'value1',
    'key2' => 'value2',
    'key3' => 'value3',
], 3600);

// Get multiple values
$values = $cache->getMultiple(['key1', 'key2', 'key3'], 'default');

// Delete multiple values
$cache->deleteMultiple(['key1', 'key2']);

Using DateInterval for TTL

<?php

use DateInterval;

// Cache for 1 hour
$cache->set('key', 'value', new DateInterval('PT1H'));

// Cache for 1 day
$cache->set('key', 'value', new DateInterval('P1D'));

// Cache for 30 days
$cache->set('key', 'value', new DateInterval('P30D'));

Adapters

FileAdapter

File-based cache implementation suitable for low to medium load applications.

Constructor Parameters:

• $cacheDirectory (string): Directory path for storing cache files
• $mode (int): Error handling mode (optional, default: MODE_THROW)

Features:

• Two error handling modes:
  • FileAdapter::MODE_THROW - Throws exceptions on errors (default)
  • FileAdapter::MODE_FAIL - Returns false/default on errors (graceful degradation)
• Optimized batch operations:
  • Automatic deduplication of keys in batch operations
  • Early return for empty arrays
  • Graceful error handling in batch operations
• Garbage collection method gc() for manual cleanup of expired files
• Refactored cache loading with centralized loadCacheData() method
• Automatic directory creation with 0755 permissions
• Thread-safe operations with file locking (LOCK_EX)
• Automatic cleanup of expired entries on read operations
• Uses MD5 hashing for file names
• Runtime mode switching with setMode() method

Usage with error modes:

// Default mode - throws exceptions
$adapter = new FileAdapter('/path/to/cache');

// Graceful mode - returns defaults on errors
$adapter = new FileAdapter('/path/to/cache', FileAdapter::MODE_FAIL);

// Manual garbage collection
$deletedFiles = $adapter->gc(); // Returns number of deleted expired files

Limitations:

• Not suitable for high-performance or distributed systems
• Consider Redis or Memcached for high-load scenarios

RedisAdapter

Redis-based cache implementation for high-performance and distributed applications.

Constructor Parameters:

• $redis (Redis): Connected Redis instance
• $mode (int): Error handling mode (optional, default: MODE_THROW)
• $prefix (string): Key prefix for namespace isolation (optional, default: cache:)

Features:

• Optimized batch operations using Redis native commands (mGet, mSet, del)
  • getMultiple() uses single mGet call instead of N individual gets
  • setMultiple() uses atomic mSet when no TTL is specified
  • deleteMultiple() uses single del call with array of keys
• Manual serialization — correctly handles all PHP types including false
• Production-safe clear() — uses SCAN instead of KEYS to avoid blocking Redis
• Two error handling modes:
  • RedisAdapter::MODE_THROW - Throws exceptions on errors (default)
  • RedisAdapter::MODE_FAIL - Returns false/default on errors (graceful degradation)
• Automatic deduplication of keys in batch operations
• Configurable key prefix for multi-app namespace isolation
• Native Redis TTL support
• Runtime mode switching with setMode() method
• Suitable for distributed systems

Key Validation

Both adapters enforce PSR-16 key requirements:

• Keys cannot be empty
• Only alphanumeric characters, underscores, dots, colons, and hyphens are allowed
• Pattern: /^[a-zA-Z0-9_.:-]+$/
• Colons (:) are supported as the standard separator for cache keys (Redis, Memcached conventions)
• Hyphens (-) are supported for UUID keys

Example keys:

• user:123:profile
• cache:session:abc123
• app.config.database
• 550e8400-e29b-41d4-a716-446655440000

Invalid keys will throw Solo\Cache\Exception\InvalidArgumentException.

Exceptions

The library provides PSR-16 compliant exceptions:

• Solo\Cache\Exception\InvalidArgumentException - Invalid cache keys or arguments
• Solo\Cache\Exception\CacheException - Cache operation failures

Requirements

• PHP 8.1 or higher
• psr/simple-cache ^3.0
• ext-redis (for Redis adapter)

License

MIT