diff --git a/README.md b/README.md index d0a6def..7eb447b 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, 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) @@ -15,6 +15,37 @@ 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 + +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: + +```php +$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](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