From 758ec5eca338037197966478b54587baf334e334 Mon Sep 17 00:00:00 2001 From: Joao Gilberto Magalhaes Date: Sun, 25 Oct 2026 18:31:47 -0400 Subject: [PATCH 1/2] Explain why the component exists in the README --- README.md | 27 ++++++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index d0a6def..be6aa80 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ tags: [php, databases, cache] # Cache Engine -A powerful, versatile cache implementation providing both PSR-6 and PSR-16 interfaces with support for multiple storage drivers. +PSR-6 and PSR-16 caching over memory, files, Redis or Memcached, with the atomic operations a distributed lock needs. [![Sponsor](https://img.shields.io/badge/Sponsor-%23ea4aaa?logo=githubsponsors&logoColor=white&labelColor=0d1117)](https://github.com/sponsors/byjg) [![Build Status](https://github.com/byjg/php-cache-engine/actions/workflows/phpunit.yml/badge.svg?branch=master)](https://github.com/byjg/php-cache-engine/actions/workflows/phpunit.yml) @@ -15,6 +15,31 @@ A powerful, versatile cache implementation providing both PSR-6 and PSR-16 inter [![GitHub license](https://img.shields.io/github/license/byjg/php-cache-engine.svg)](https://opensource.byjg.com/license/) [![GitHub release](https://img.shields.io/github/release/byjg/php-cache-engine.svg)](https://github.com/byjg/php-cache-engine/releases/) +## Why + +A cache is easy until two processes use it at the same time. Checking `has()` and then +calling `set()` leaves a gap where another process can write, so both believe they own the +key, and most cache libraries offer nothing better. + +Cache Engine gives the same engines both standard interfaces (PSR-16 and PSR-6), and adds +the operations the storage can do in one indivisible step: + +```php +$cache = new RedisCacheEngine('redis-host'); + +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 +} +``` + +- **Correct locks on Redis and Memcached.** `setIfAbsent()`, `deleteIfEquals()` and + `expireIfEquals()` compare and write atomically; engines that cannot guarantee it do not + offer them. [byjg/resilience](https://github.com/byjg/php-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 From ed810e744e78e9d093f033b62e3c25749b45ef48 Mon Sep 17 00:00:00 2001 From: Joao Gilberto Magalhaes Date: Sun, 25 Oct 2026 18:32:56 -0400 Subject: [PATCH 2/2] Lead the Why with the atomic operations beyond PSR --- README.md | 30 ++++++++++++++++++------------ 1 file changed, 18 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index be6aa80..7eb447b 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ tags: [php, databases, cache] # Cache Engine -PSR-6 and PSR-16 caching over memory, files, Redis or Memcached, with the atomic operations a distributed lock needs. +PSR-6 and PSR-16 caching over memory, files, Redis or Memcached, extended with atomic increment, decrement and compare-and-swap. [![Sponsor](https://img.shields.io/badge/Sponsor-%23ea4aaa?logo=githubsponsors&logoColor=white&labelColor=0d1117)](https://github.com/sponsors/byjg) [![Build Status](https://github.com/byjg/php-cache-engine/actions/workflows/phpunit.yml/badge.svg?branch=master)](https://github.com/byjg/php-cache-engine/actions/workflows/phpunit.yml) @@ -17,26 +17,32 @@ PSR-6 and PSR-16 caching over memory, files, Redis or Memcached, with the atomic ## Why -A cache is easy until two processes use it at the same time. Checking `has()` and then -calling `set()` leaves a gap where another process can write, so both believe they own the -key, and most cache libraries offer nothing better. +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 gives the same engines both standard interfaces (PSR-16 and PSR-6), and adds -the operations the storage can do in one indivisible step: +Cache Engine implements both standards and extends them with the operations the storage +can do in one indivisible step: ```php $cache = new RedisCacheEngine('redis-host'); -if ($cache->setIfAbsent('lock:report', $token, 60)) { // exactly one caller gets true +$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 + $cache->deleteIfEquals('lock:report', $token); // release only our own lock } ``` -- **Correct locks on Redis and Memcached.** `setIfAbsent()`, `deleteIfEquals()` and - `expireIfEquals()` compare and write atomically; engines that cannot guarantee it do not - offer them. [byjg/resilience](https://github.com/byjg/php-resilience) builds its - distributed mutex on them. +- **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](https://github.com/byjg/php-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.