Download the PHP package silviooosilva/cacheer-php without Composer

CacheerPHP

An explicit, instance-first PHP cache with a tiny core, optional capabilities, and zero framework lock-in.

--- > **CacheerPHP 6.x stable** provides instance-first caching over a four-method `Store` > contract. Optional interfaces add batching, tags, locks, and counters; decorators > add tiering, resilience, and instrumentation. Configure serialization, > compression, and encryption through the storage pipeline. Construct the cache > you need and inject it; the core package runs no code at autoload time. > Upgrading from v5? See [Migrating from v5](#migrating-from-v5). ## Five-minute quick start The `^6.0` constraint installs stable releases from the 6.x line and keeps updates within the same major version. PHP 8.3 or newer is required. The core installs with **no backend clients and no required extensions** — `ArrayStore` and `FileStore` work out of the box. Swap the store, keep the API: PDO stores need a driver and an explicitly created schema: Schema creation is an explicit setup step. Constructing the store does not run it. ## Why v6 - **Tiny core, honest capabilities.** A store implements four methods; extra behavior is declared by interface, and `$cache->supports(...)` answers truthfully even through decorators — a backend never pretends to guarantee something it can't. See [CAPABILITIES.md](CAPABILITIES.md). - **One cache type.** Scope, policy, and capabilities are state on one object, so every combination composes — a scoped cache still has a policy, a policy-bound cache still scopes, and both still increment, tag, and lock. Type-hint the `Cache` interface and any of them is substitutable. - **Instance-first.** Construct several caches side by side and inject them where needed. The core does not load `.env`, create database schemas, or change the global timezone at autoload time. [`Telemetry`](#observability-and-the-one-global) provides an optional process-global observability tap. - **Scopes instead of stringly namespaces.** `->scope('billing')` (or `->in()`) is an isolated keyspace you can clear on its own — and it applies to counters, tags, and locks too, not just to get/set. - **Composable decorators.** Tiered (L1/L2), resilient (circuit-breaker fallback), and instrumented (typed events + metrics) all wrap any store. - **Stampede protection.** `remember()` coordinates misses when locking is available; `flexible()` serves a bounded stale value through the chosen executor. - **Configurable storage.** Values are serialized → optionally compressed → optionally AES-256-GCM encrypted into a versioned envelope. Encryption authenticates the payload; an unencrypted envelope is not authenticated. - **Standards-first.** PSR-16 and PSR-6 adapters, a PSR-3 logging subscriber, and a PSR-14 event bridge ship in the box. - **Deterministic tests.** Time is an injected `Clock`; the suite uses a `FakeClock` and needs no `sleep()`. ## Core recipes ### Scopes ### One type, every combination ### Policies The default applies when a write omits its TTL. Negative caching only shortens empty results; it preserves a shorter explicit TTL and explicit forever storage. Use `forever()`, `rememberForever()`, or `Ttl::forever()` for explicit no-expiry storage under a policy. `flexible()` keeps its requested stale window unchanged by jitter or negative caching. See the [policies guide](https://cacheerphp.com/docs/v6/en/guides/policies/). ### Stampede protection & stale-while-revalidate `remember()` waits up to five seconds for its internal lock. After a timeout it rechecks the entry, then computes if still missing. Stores without locking use a plain compute-and-store; Array coordination is local to one process. Coordination lasts only while the lock's lease holds, so callbacks are not guaranteed exactly once. `flexible()` measures age from the original creation time, including promoted values, and rechecks freshness before a queued refresh. A refresh lock prevents duplicate pending work while its lease holds. On a store without locking, stale reads can queue multiple tasks, which each recheck freshness before computing. The default executor runs refreshes inline. For deferred work: The executor flushes at shutdown and sends the response first where `fastcgi_finish_request()` is available. In a long-running worker, call `$executor->flush()` after each request or job. See the [refresh guide](https://cacheerphp.com/docs/v6/en/guides/stale-while-revalidate/). ### Tiering, resilience, observability Tiered caches write L2 first and retain the source value's age and expiry on promotion. The default L1 cap is **60 seconds**; another worker's single-key change may remain stale locally until that cap expires. Bulk invalidation uses a shared generation token. See the [tiered guide](https://cacheerphp.com/docs/v6/en/guides/tiered-caching/). Resilient caches fail over on backend outages. Programming errors and corrupt payloads propagate; successful primary writes keep the primary's result even if mirroring fails. Counters, CAS, and locks stay on the primary and do not fail over. Before serving the recovered primary, each process reconciles its own fallback-only mutations. See the [resilient guide](https://cacheerphp.com/docs/v6/en/guides/resilient-store/). Instrumentation preserves native batches and their transaction behavior. Listener failures do not change completed cache operations, and reads do not increase `bytes_written`. ### Encryption & compression Reuse the same key across workers and restarts. Keep retired keys in the keyring while old entries still need to be read. An encrypting pipeline rejects plaintext envelopes, so enabling encryption on an existing cache needs a fresh keyspace or a clear. The value-size limit covers plain, compressed, and encrypted reads before deserialization; `0` means no configured limit. Native PHP serialization supports objects and allows classes by default. Restrict restoration on a shared backend when needed: See [SECURITY.md](SECURITY.md) and the [storage guide](https://cacheerphp.com/docs/v6/en/api/compression-encryption/). ### Fluent configuration — `Cacheer::build()` Assemble a store, storage pipeline, and default policy in one chain (the v6 take on v5's OptionBuilder — it returns a ready cache, not an options array): ### Formatting reads The default PHP serializer preserves serializable values. To reshape one on the way out, use the `CacheDataFormatter` — standalone, or via a fluent `formatted()` view: ### Counters, tags, locks, TTL renewal (capabilities) Capabilities are implemented by the store and reached on the cache, so the scope is applied for you and one clear exception names anything the backend can't do: `touch()` preserves value age and cannot revive expired data. Tags survive overwrites and end when the entry is deleted or cleared. Redis prefixes must not include the reserved `:e`, `:t`, `:l`, or `:kt` segments. Check the result of a lock's `block()` before entering a critical section and release it in `finally`. File locks last until release or process exit; their TTL does not expire a live `flock` handle. Array locks coordinate one process; shared Redis/PDO locks coordinate through their backend. ### Everyday verbs On a lock-capable store, `add()` coordinates competing `add()` calls and throws on lock timeout. Without locking it is best-effort; ordinary `set()` calls do not share that coordination. `pull()` reads then deletes and is not an atomic consume. ## Observability and the one global Everything above is instance-scoped. `Observability\Telemetry` is the single deliberate exception, and it is worth being precise about what it is: - It holds **process-global state** — a static listener list. - It is **dormant**: with no listeners registered, caches use the uninstrumented path. Register listeners before constructing caches you want to observe. - **This package registers nothing.** `silviooosilva/cacheer-php` declares only PSR-4 autoloading, so installing it executes no code. It exists so a telemetry package can observe caches it did not construct: Existing instrumented caches retain their dispatcher. Resetting the tap does not remove instrumentation from a cache already constructed. Value capture is off by default; enable it only deliberately with an appropriate redaction policy. Installing [`cacheerphp/monitor`](https://github.com/CacheerPHP/monitor) **does** add an autoload-time side effect: that package declares `autoload.files`, and its bootstrap registers a listener as soon as `vendor/autoload.php` is loaded. That is the point of it — zero-wiring monitoring — but it is a real side effect, from that package, and you opt into it by installing it. If you want no process-global state at all, never call `Telemetry::listen()` and don't install the monitor: wire observability explicitly with `Cacheer::instrumented($store, $events)` instead. ## PSR adapters PSR keys reject reserved characters (including `:`), empty keys, control characters, and keys beyond 1,024 bytes. Invalid inputs raise the PSR invalid-argument exception. Write failures return `false`; reads propagate backend errors. Deferred PSR-6 lifetimes begin when queued, so delaying `commit()` does not extend expiry. See the [adapter reference](https://cacheerphp.com/docs/v6/en/api/psr16-adapter/). ## Operations CLI Point the CLI at a `cacheer.config.php` that returns a `Store` (or `['store' => ..., 'pdo' => ..., 'table' => ...]`). ## Migrating from v5 v6 is a new major with an instance-first API. Migrating is mostly mechanical: - Rename the v5 methods to the v6 names — `putCache`→`set`, `getCache`→`get`, `flushCache`→`clear`, and the positional namespace → `scope()`. The optional [`rector.php`](rector.php) set automates the common renames. - Cached data starts cold: v6 uses its own storage layout and rejects v5 payloads. Use a separate cache directory, Redis prefix, or SQL table, and recompute values on first use. Keep the v5 keyspace through the rollback window. - Keep services that have not migrated on `^5.2`. The v5 line receives security and correctness fixes for 12 months from the 6.0.0 release. The method-by-method mapping and database migration/rollback steps are in **[MIGRATION.md](MIGRATION.md)**. ## Building a custom store Implement four methods, add capability interfaces you can honor, and prove it with the shared conformance suite — no need to read the built-in store source. See **[WRITING_A_STORE.md](WRITING_A_STORE.md)**. The conformance suite lives under `tests/Support/`. Composer does not load a dependency's `autoload-dev`, so a consumer must map the helpers in its own project: Merge this into your project's `composer.json`, install the development dependencies, and run `composer dump-autoload`. Extend `Tests\Support\StoreConformance`, return your store from `createStore(FakeClock $clock)`, and run it with `vendor/bin/phpunit`. Inject the supplied clock so expiry checks stay deterministic. See the [custom-store guide](https://cacheerphp.com/docs/v6/en/guides/custom-stores/). ## Requirements - **PHP 8.3+** - `ext-openssl` — only for AES-256-GCM encryption - `ext-zlib` — only for gzip compression - `ext-pdo` — only for the database store - `predis/predis` or `ext-redis` — only for the Redis store The core installs and runs (Array/File stores) with none of the optional pieces. ## Testing Use `composer test:kernel`, `composer test:storage`, or `composer test:contract` to focus on one part of the unit suite. Service checks are separate: Redis/MySQL/PostgreSQL integrations skip cleanly when their service is absent locally. `CACHEER_REQUIRE_REDIS=1` or `CACHEER_REQUIRE_DATABASE=1` makes a selected required check fail if the service is unavailable. Use dedicated test keyspaces. ## Documentation - [MIGRATION.md](MIGRATION.md) — v5 → v6 upgrade guide - [CAPABILITIES.md](CAPABILITIES.md) — capability matrix, guarantees, failure modes - [WRITING_A_STORE.md](WRITING_A_STORE.md) — third-party store author guide - [SECURITY.md](SECURITY.md) — support windows and vulnerability reporting - [KNOWN_LIMITATIONS.md](KNOWN_LIMITATIONS.md) — documented edges - Usage examples in [`Examples`](Examples) - [English docs](https://cacheerphp.com/docs/v6/en/getting-started/) and [Portuguese docs](https://cacheerphp.com/docs/v6/pt/primeiros-passos/) - [Release lines and support](https://cacheerphp.com/docs/v6/en/updating/version-support/) - The incremental v6 plan lives in [ROADMAP.md](ROADMAP.md) ## Contributing Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) and the issue and pull-request templates. Substantial changes start with an RFC. ## License CacheerPHP is open-sourced software licensed under the [MIT license](LICENSE). ## Support If CacheerPHP saves you time, consider supporting the project: