byjg / cache-engine

6.0.1 2026-02-22 01:27 UTC

Requires

• php: >=8.3 <8.6
• psr/cache: ^1.0|^2.0|^3.0
• psr/container: ^1.0|^1.1|^2.0
• psr/log: ^1.0|^2.0|^3.0
• psr/simple-cache: ^1.0|^2.0

Requires (Dev)

• phpunit/phpunit: ^10.5|^11.5
• vimeo/psalm: ^5.9|^6.13

Suggests

• ext-memcached: *
• ext-redis: *
• ext-shmop: *

Provides

• psr/cache-implementation: 1.0
• psr/simple-cache-implementation: 1.0

MIT

Published on Packagist.org on 2026-02-22 01:29 UTC

README

sidebar_key	cache-engine
sidebar_category	infrastructure
tags	php databases cache

Cache Engine

PSR-6 and PSR-16 caching over memory, files, Redis or Memcached, extended with atomic increment, decrement and compare-and-swap.

Why

PSR-16 and PSR-6 cover get, set and delete, and stop there. A counter, a rate limit or a lock needs more: with only get() and set(), two processes read the same value and one update is lost, and checking has() before set() lets both believe they own a key.

Cache Engine implements both standards and extends them with the operations the storage can do in one indivisible step:

$cache = new RedisCacheEngine('redis-host');

$hits = $cache->increment('hits:home', 1, 60);           // atomic counter, with a TTL
$cache->decrement('stock:sku-42');                        // never loses an update

if ($cache->setIfAbsent('lock:report', $token, 60)) {    // exactly one caller gets true
    // ... only this process runs
    $cache->deleteIfEquals('lock:report', $token);       // release only our own lock
}

• Atomic operations beyond PSR. increment(), decrement() and add() (append to a list) read and modify the value in one step, on Redis, Memcached and the file system (AtomicOperationInterface).
• Correct locks. setIfAbsent(), deleteIfEquals() and expireIfEquals() compare and write atomically on Redis and Memcached (CompareAndSwapInterface); engines that cannot guarantee it do not offer them. byjg/resilience builds its distributed mutex on them.
• Change the storage, keep the code. Memory, file system, Redis, Memcached or the no-op engine behind the same interfaces.

Key Features

• PSR-16 Simple Cache interface - Simple, straightforward caching API
• PSR-6 Cache Pool interface - More verbose caching with fine-grained control
• Multiple storage backends - Choose from memory, file system, Redis, Memcached and more
• Atomic operations - Support for increment, decrement and add operations in compatible engines
• Compare and swap - Conditional writes for correct distributed locking on Redis and Memcached
• Garbage collection - Automatic cleanup of expired items
• PSR-11 container support - Retrieve cache keys via dependency container
• Logging capabilities - PSR-3 compatible logging of cache operations

Installation

composer require "byjg/cache-engine"

Quick Start

// PSR-16 Simple Cache
$cache = new \ByJG\Cache\Psr16\FileSystemCacheEngine();
$cache->set('key', 'value', 3600); // Cache for 1 hour
$value = $cache->get('key');

// PSR-6 Cache Pool
$pool = \ByJG\Cache\Factory::createFilePool();
$item = $pool->getItem('key');
if (!$item->isHit()) {
    $item->set('value');
    $item->expiresAfter(3600);
    $pool->save($item);
}
$value = $item->get();

Documentation

Getting Started

• PSR-16 Simple Cache Usage
• PSR-6 Cache Pool Usage

Available Cache Engines

Engine	Description
NoCacheEngine	No-op engine for disabling cache without code changes
ArrayCacheEngine	In-memory array cache (non-persistent between requests)
FileSystemCacheEngine	File system based caching
MemcachedEngine	Memcached distributed caching
RedisCacheEngine	Redis-based caching
SessionCacheEngine	PHP session-based caching
TmpfsCacheEngine	Tmpfs-based caching

Advanced Features

• Atomic Operations
• Compare and Swap
• Garbage Collection
• Logging
• PSR-11 Container Usage

Running Tests

docker compose up -d
vendor/bin/phpunit

Open source ByJG