[Moritz Mazetti (Radiergummi)]

Summary

Replaces Laravel cache tags with tag versioning. Laravel tags are part of the cache key (an entry stored with [a, b] can only be read with exactly [a, b]), which made several operations silently do nothing or clear far too much.

How it works now

• Entries are stored under a key derived only from the request, together with the versions of their tags.
• Every tag has a version, a random token in the cache. Flushing a tag writes a new token, so every entry carrying it becomes a miss.
• Versions are read before the response is built, so a flush that happens while a response is being built invalidates it too.
• Flushes wait until every open database transaction, on every connection, has ended, so no other request can cache uncommitted data under the new version. They run after rollbacks too, because the data may have been written outside that transaction or on another connection. A failed deferred flush is reported, not thrown, so the commit and other after-commit callbacks are unaffected.
• Works on every cache store (file, database, DynamoDB, Redis, …). The failover store is refused.

Bugs fixed on master

• response-cache:clear / ResponseCache::flush() without tags did nothing on taggable stores. With default tags configured, delete($uri) and the command also did nothing.
• Any flush wiped the whole store on non-taggable stores (the old default file).
• flush(['x']) merged in the default tags, so flushing one tag cleared everything.
• Strategy tags that depended on the response were written but never found.
• RESPONSE_CACHE_TTL and RESPONSE_CACHE_ENABLED from .env threw a TypeError under strict_types.
• A tag binding to a model with an integer key (e.g. user:{user}) threw a TypeError under strict_types.
• On Laravel 13, where new apps set cache.serializable_classes to false, cached responses could not be read back from Redis, database or file stores, so nothing was ever served from the cache. Entries are now stored as plain data (status, headers, content).

Breaking changes (v2)

The README has a full Upgrading to v2 section. The main changes:

• CacheStrategy::tags(Request $request): the response parameter is gone. There is a new CacheStrategy::isCacheable(Request $request).
• flush() flushes everything, flush([]) flushes nothing, and default tags are no longer merged in.
• ResponseCache::has() is removed. put() now takes a Snapshot (from lookup() or snapshot()) instead of tags.
• store defaults to the app's default cache store, and there is a new tag_ttl option (30 days).
• Requests rejected by isCacheable (e.g. POST) no longer emit Miss.
• Custom serialization through a Repository subclass is removed.

The README also has a new Limitations section (data read before the snapshot, read replicas, store failover, DynamoDB, local stores, hit rate).

Test plan

• composer test: 73 passing. New unit tests for Repository and new feature tests in InvalidationTest cover:
  • every confirmed bug
  • flushing while a response is built
  • commit, rollback, nested transactions, transactions on a second connection, flushes from rollback callbacks, failed commits, and
    application tests wrapped in RefreshDatabase/DatabaseTransactions
  • a failed deferred flush being reported without breaking the commit
  • every audience and query variant
  • an evicted version, and an entry outliving tag_ttl
  • get() not writing to the store
  • a non-taggable store, and the refused failover store
• composer analyze (PHPStan) is clean.
• vendor/bin/pint --test is clean.
• End-to-end, in Docker: a fresh Laravel 13.38 app on PHP 8.4 with the package installed from this branch, run against Redis 7, Memcached 1.6, Postgres 17 (database store) and the file store. A scripted run over real HTTP passed 65/65 checks:
  • hits, observer flushes inside transactions, and flushes across audiences and query variants
  • response-cache:clear with and without tags (from the CLI), delete(), and foreign keys surviving a flush-all
  • a flush while a response is being built, a 2-second held transaction, a rollback, and a rollback on an unrelated connection
  • an evicted version key, non-cacheable POST requests, and 30 concurrent cold requests
  • tag_ttl expiry
  • Memcached stopped mid-run: reads degrade to misses, an immediate flush fails, and a deferred flush is reported while the commit completes

🤖 Generated with Claude Code

https://claude.ai/code/session_01GGNGyJLoFTM5C474gZPW5q