Tenant-safe cache invalidation with tags

Prerequisites

• ▹A tag-capable cache store (Redis or Memcached via Laravel's cache tags) — the database and file drivers do not support tags.
• ▹Tenant context resolvable at cache-access time (the same context your queries use).
• ▹The current deploy SHA or schema version available at runtime (for key versioning).

Procedure

1. 1

   Prefix every key with the tenant

   The single most common multi-tenant cache bug is a global key — `user-roles`, `settings` — warmed by whichever tenant hit it first and then served to everyone. Route all cache access through a wrapper that prefixes the active tenant so a collision is structurally impossible.

   final class TenantCache
   {
       public function remember(string $key, int $ttl, Closure $cb): mixed
       {
           $tenant = app(TenantContext::class)->requireId();
           // Every key is physically namespaced by tenant — no cross-tenant hit.
           return Cache::remember("t:{$tenant}:{$key}", $ttl, $cb);
       }
   }

2. 2

   Group related keys with tags

   Tags let one write invalidate exactly the keys it affects, instead of flushing the whole store or trying to enumerate keys by hand. Tag by tenant and by the entity the cache derives from, so a change to one order clears that order's caches and nothing else.

   $tenant = app(TenantContext::class)->requireId();
   
   Cache::tags(["t:{$tenant}", "order:{$orderId}"])
       ->remember("order-summary:{$orderId}", 600, fn () => $this->build($orderId));
   
   // On update, flush precisely — only this order's tagged entries.
   Cache::tags(["order:{$orderId}"])->flush();

3. 3

   Version keys by schema and deploy

   When a deploy changes the shape of a cached value, old entries must not be read by new code. Fold a schema version and the deploy SHA into the key so a changed contract simply misses and rebuilds, rather than deserialising into the wrong shape.

   $v = config('cache.schema_version').':'.config('app.deploy_sha');
   Cache::remember("v{$v}:t:{$tenant}:{$key}", $ttl, $cb);

4. 4

   Invalidate before you warm — and treat a partial warm as an alarm

   When a change triggers a rebuild, invalidate the stale entries first, then prefill. Reversed, the prefill builds values the invalidation immediately deletes. A prefill that only partially completes must page — a half-warm cache serves a view assembled from fresh and stale values at once.

   Cache::tags(["order:{$orderId}"])->flush();     // 1. invalidate first
   $result = $this->warm($orderId);                // 2. then prefill
   
   if ($result->failedKeys) {
       // A partial warm is not a warning to log — it is a page to answer.
       Alert::page('cache prefill partial', ['order' => $orderId, 'failed' => $result->failedKeys]);
   }

5. 5

   Always keep a TTL as the backstop

   Tags give you precision; a TTL gives you safety. Never cache with `forever`/`rememberForever` on data that can change — if an invalidation is ever missed, the TTL guarantees the wrong value self-heals instead of persisting indefinitely. Precision from tags, correctness insurance from the TTL.