4.0

Overview

CacheLayer 4.0 focuses on safer defaults, race-resistant cache and invalidation behavior, and optional Runwire 2.1 integration. It requires PHP 8.4 and includes compatibility changes that 3.x users should review before deployment. (Ref: PR #29)

New Features

• Runwire 2.1 integration: Applications can share runtime and request scopes for isolated memoization, and let host-owned workers run bounded cluster invalidation or Node maintenance. Runwire remains optional; CacheLayer does not start workers or event loops. (Ref: PR #29)
• Bounded maintenance and polling: NodeCacheMaintenance::cycle() and ClusterRuntime::poll() provide bounded operational work for schedulers and worker integrations. (Ref: PR #29)

Improvements

• Safer payload handling: Recursive, excessively deep, and over-budget value graphs are rejected. Signed records bind to their logical storage identity and key; object and Closure deserialization are disabled by default and require explicit opt-in. (Ref: PR #29)
• More reliable concurrent operations: Stale-entry cleanup and tag-generation initialization avoid overwriting concurrent replacements. Tiered and Node caches fence upper-tier reads after failed mutations so stale values cannot override authoritative storage. (Ref: PR #29)
• Isolated exact counters: Redis and Valkey counters use a dedicated keyspace unaffected by ordinary cache clears, and preserve exact integer values within PHP’s integer range. (Ref: PR #29)
• Improved PSR and key handling: Deferred writes are visible before commit() and are reconciled with immediate mutations; numeric-string keys retain their identity in bulk operations and tiering. Memcached TTLs longer than 30 days are converted correctly. (Ref: PR #29)
• Safer cluster recovery: Cursor ownership includes cluster, node, namespace, and transport identity. New scopes are cleared before use, and recovery detects empty or reset histories. PDO invalidation publication serializes event-ID allocation through transaction completion. (Ref: PR #29)
• Hardened storage boundaries: Filesystem adapters check symlinked path components, and Redis/PDO/MongoDB configuration failures avoid exposing credentials. (Ref: PR #29)

Breaking Changes

• PHP requirement: PHP 8.3 is no longer supported; PHP 8.4 or newer is required. Upgrade the runtime before installing 4.0. (Ref: PR #29)
• Configuration and interface changes: ClusterCacheConfig now requires transportIdentity; callers must supply a stable identity and use a new, never-used value after invalidation-history resets. NodeCacheConfig replaces failOpen with options: new CacheOptions(failOpen: ...). Custom InvalidationTransportInterface and CursorStoreInterface implementations must implement the new methods. (Ref: PR #29)
• Bulk return types: Cache::getItems() and Cache::getMultiple() now return iterable, not array; callers that require array-only behavior may need to materialize the result. (Ref: PR #29)
• Stored data and defaults: Signed records use an identity-bound format; legacy unbound signed records are rejected. Object and Closure deserialization now defaults to disabled. Review the 3.x upgrade guide before sharing existing cache data with 4.0. (Ref: PR #29)

Notes

• MySQL/MariaDB identity columns use byte-sensitive collation, and existing schemas may be altered during installation. Back up durable invalidation state and review the documented migration procedure before deployment. (Ref: PR #29)
• Counter keys move to cachelayer:counter:<namespace>:<key>; migrate security- or quota-relevant 3.x counter state deliberately while old writers are stopped. (Ref: PR #29)
• Cursor upgrades and history resets can cold-clear local cache state. Recreating or restoring an invalidation log requires a coordinated cutover using a new transportIdentity and reconciliation of every APCu/L1 domain; arbitrary same-identity history resets are unsupported. (Ref: PR #29)

Full Changelog: 3.4...4.0