armin-dev/cache-box

dev-main 2025-09-30 07:52 UTC

MIT

• PouyaniArmin

README

CacheBox is a flexible PHP caching library that allows developers to store and retrieve data easily using multiple drivers, including file system, Memcached, and Redis. It provides a unified API for caching and simplifies cache management in PHP projects.

Installation

Requirements

• PHP 8.0 or higher
• PHP extensions:
  • redis (for RedisDriver)
  • memcached (for MemcacheDriver)
• File write permissions (for FileCache)

Installation via Composer

You can install CacheBox using Composer:

composer require armin-dev/cache-box

require __DIR__ . '/vendor/autoload.php';

use ArminDev\CacheBox\CacheBox;

Drivers

Memcached

• Supports two formats: string and json.
• Data must be stored in one of these formats.
• TTL (expiration) is fully supported.
• Requires Memcached server to be running and accessible.

Redis

• No format selection required; Redis can store any type of data directly.
• TTL (expiration) is fully supported.
• Requires Redis server to be running and accessible.

Usage / Examples

Using FileCache

use ArminDev\CacheBox\CacheBox;

$cache = new CacheBox();
$cache->driver('file')
      ->path(__DIR__ . '/cache')   // optional, default directory will be used
      ->directory('my_cache')      // optional
      ->format('json');            // set format: json, serialize, txt

$cache->set('post_1', ['title' => 'Hello World'], '1h');
$data = $cache->get('post_1');
print_r($data);

Using Memcached

use ArminDev\CacheBox\CacheBox;

$cache = new CacheBox();
$cache->driver('memcached')
      ->server('127.0.0.1', 11211)
      ->setFormat('json');        // required for Memcached

$cache->set('post_2', ['title' => 'Memcached Example'], '30m');
$data = $cache->get('post_2');
print_r($data);

Using Redis

use ArminDev\CacheBox\CacheBox;

$cache = new CacheBox();
$cache->driver('redis')
      ->server('127.0.0.1', 6379); // no format needed

$cache->set('post_3', ['title' => 'Redis Example'], '2h');
$data = $cache->get('post_3');
print_r($data);

TTL / Expiration

CacheBox supports setting expiration times (TTL) for cached items. You can provide TTL as a string with a numeric value followed by a unit:

• s → seconds
• m → minutes
• h → hours
• d → days

Examples:

use ArminDec\CacheBox\CacheBox;

$cache = new CacheBox();
$cache->driver('file')
      ->path(__DIR__ . '/cache')
      ->directory('my_cache')
      ->format('json');

// TTL in seconds
$cache->set('post_sec', 'Data expires in 30 seconds', '30s');

// TTL in minutes
$cache->set('post_min', 'Data expires in 15 minutes', '15m');

// TTL in hours
$cache->set('post_hour', 'Data expires in 2 hours', '2h');

// TTL in days
$cache->set('post_day', 'Data expires in 5 days', '5d');

Configuration / Options

CacheBox provides some configurable options depending on the driver you use:

FileCache

• path($path) → set the base path for cache files (required).
• directory($dir) → set a subdirectory inside the base path (optional).
• format($type) → choose the format: json, serialize, txt (required).

Memcached

• server($host, $port) → set Memcached server host and port (required).
• setFormat($type) → choose format: string or json (required).

Redis

• server($host, $port) → set Redis server host and port (required).
• No format selection is needed; Redis stores data directly.

Example:

$cache = new CacheBox();
$cache->driver('file')
      ->path(__DIR__ . '/cache')
      ->directory('my_cache')
      ->format('json');

$cache->driver('memcached')
      ->server('127.0.0.1', 11211)
      ->setFormat('json');

$cache->driver('redis')
      ->server('127.0.0.1', 6379);

Error Handling / Exceptions

CacheBox throws exceptions in cases where operations fail or invalid configurations are provided. You should handle these exceptions using try/catch blocks to prevent application crashes.

Common Exceptions

CacheBox may throw exceptions in several scenarios. Examples:

$cache = new CacheBox();

try {
    // Driver Not Supported
    $cache->driver('unknown');
} catch (Exception $e) {
    echo "Driver Error: " . $e->getMessage() . PHP_EOL;
}

try {
    // Redis server not reachable
    $cache->driver('redis')->server('127.0.0.1', 6379);
} catch (Exception $e) {
    echo "Redis Error: " . $e->getMessage() . PHP_EOL;
}

try {
    // Memcached server not reachable
    $cache->driver('memcached')->server('127.0.0.1', 11211);
} catch (Exception $e) {
    echo "Memcached Error: " . $e->getMessage() . PHP_EOL;
}

try {
    // FileCache file missing or expired
    $data = $cache->driver('file')->get('nonexistent_key');
} catch (Exception $e) {
    echo "FileCache Error: " . $e->getMessage() . PHP_EOL;
}

Contributing

Contributions to CacheBox are welcome! You can help by:

• Reporting bugs or issues
• Suggesting new features
• Submitting pull requests with improvements

Before submitting a pull request, please make sure your code follows the existing coding standards and passes any tests.

License

CacheBox is released under the MIT License. See the LICENSE file for more details.