cache-management

name	cache-management
description	Implement production-grade caching with cache keys/TTLs/consistency classes per query, SWR (stale-while-revalidate), explicit invalidation, and comprehensive testing for stale reads and cache warmup. Use when adding caching to queries, implementing cache invalidation, or ensuring cache consistency and performance.

Cache Management Skill

Context (Input)

Use this skill when:

• Adding caching to repositories or expensive queries
• Implementing cache invalidation via domain events
• Defining cache keys, TTLs, and consistency requirements
• Implementing stale-while-revalidate (SWR) pattern
• Testing cache behavior (stale reads, cold start, invalidation)
• Reducing database load with caching

Task (Function)

Implement production-ready caching with proper key design, TTL management, event-driven invalidation, and comprehensive testing.

Success Criteria:

• Cache policy declared for each query (key, TTL, consistency class)
• Decorator pattern with CachedXxxRepository wrapping MongoXxxRepository
• Event-driven invalidation via domain event subscribers
• Best-effort invalidation (try/catch, never fail business operations)
• Comprehensive unit tests for all cache paths
• Cache observability (hit/miss/error logging)
• make ci outputs "✅ CI checks successfully passed!"

---

⚠️ CRITICAL CACHE POLICY

╔═══════════════════════════════════════════════════════════════╗
║  ALWAYS use Decorator Pattern for caching (wrap repositories) ║
║  ALWAYS use CacheKeyBuilder service (prevent key drift)       ║
║  ALWAYS invalidate via Domain Events (decouple from business) ║
║  ALWAYS use TagAwareCacheInterface for cache tags             ║
║  ALWAYS wrap cache ops in try/catch (best-effort, no failures)║
║                                                               ║
║  ❌ FORBIDDEN: Caching in repository, implicit invalidation   ║
║  ✅ REQUIRED:  Decorator pattern, event-driven invalidation   ║
╚═══════════════════════════════════════════════════════════════╝

Non-negotiable requirements:

• Use Decorator Pattern: CachedXxxRepository wraps MongoXxxRepository
• Use centralized CacheKeyBuilder service (in Shared/Infrastructure/Cache)
• Invalidate via Domain Event Subscribers (one subscriber per event)
• Wrap ALL cache operations in try/catch (never fail business operations)
• Use TagAwareCacheInterface (not CacheInterface) for tag support
• Configure test cache pools with tags: true in config/packages/test/cache.yaml
• Log cache operations for observability

File Locations (This Codebase)

Component	Location
CacheKeyBuilder	src/Shared/Infrastructure/Cache/CacheKeyBuilder.php
CachedCustomerRepository	src/Core/Customer/Infrastructure/Repository/CachedCustomerRepository.php
Created Invalidation Sub	src/Core/Customer/Application/EventSubscriber/CustomerCreatedCacheInvalidationSubscriber.php
Updated Invalidation Sub	src/Core/Customer/Application/EventSubscriber/CustomerUpdatedCacheInvalidationSubscriber.php
Deleted Invalidation Sub	src/Core/Customer/Application/EventSubscriber/CustomerDeletedCacheInvalidationSubscriber.php
Cache Pool Config	config/packages/cache.yaml
Test Cache Config	config/packages/test/cache.yaml
Services Config	config/services.yaml
Repository Unit Tests	tests/Unit/Customer/Infrastructure/Repository/CachedCustomerRepositoryTest.php
Subscriber Unit Tests	tests/Unit/Customer/Application/EventSubscriber/*CacheInvalidation*Test.php

---

TL;DR - Cache Management Checklist

Before Implementing Cache:

• Identified slow query worth caching (use query-performance-analysis)
• Cache policy declared (key pattern, TTL, consistency class)
• Cache tags defined for invalidation strategy
• Domain events defined for cache invalidation triggers

Architecture Setup:

• Created CachedXxxRepository decorator class
• Created CacheKeyBuilder service (or extended existing one)
• Created cache invalidation event subscribers (one per event)
• Configured services.yaml with explicit cache pool injection

During Implementation:

• Decorator wraps inner repository (not extends)
• CacheKeyBuilder used for all cache keys (prevents drift)
• Cache operations wrapped in try/catch (best-effort)
• Event subscribers use same CacheKeyBuilder for tags
• Logging added for cache hits/misses/errors
• Repository uses TagAwareCacheInterface (required for tags)

Testing:

• Test cache pool configured with tags: true
• Unit tests for cache invalidation subscribers
• Integration tests for stale reads after writes
• Test: Cache error fallback to database works

Before Merge:

• All cache tests pass
• Cache observability verified (logs present)
• CI checks pass (make ci)
• No cache-related stale data issues

---

Quick Start: Cache in 7 Steps

Step 1: Declare Cache Policy

Before writing code, declare the complete policy:

/**
 * Cache Policy for Customer By ID Query
 *
 * Key Pattern: customer.{id}
 * TTL: 600s (10 minutes)
 * Consistency: Stale-While-Revalidate
 * Invalidation: Via domain events (CustomerCreated/Updated/Deleted)
 * Tags: [customer, customer.{id}]
 * Notes: Read-heavy operation, tolerates brief staleness
 */

Step 2: Create CacheKeyBuilder Service

Location: src/Shared/Infrastructure/Cache/CacheKeyBuilder.php

final readonly class CacheKeyBuilder
{
    public function build(string $namespace, string ...$parts): string
    {
        return $namespace . '.' . implode('.', $parts);
    }

    public function buildCustomerKey(string $customerId): string
    {
        return $this->build('customer', $customerId);
    }

    public function buildCustomerEmailKey(string $email): string
    {
        return $this->build('customer', 'email', $this->hashEmail($email));
    }

    /**
     * Build cache key for collections (filters normalized + hashed)
     * @param array<string, string|int|float|bool|array|null> $filters
     */
    public {
        ();  
         ->(
            ,
            ,
            (, (, \JSON_THROW_ON_ERROR))
        );
    }

    
     {
         (, ());
    }
}

Step 3: Create Cached Repository Decorator

Location: src/Core/{Entity}/Infrastructure/Repository/Cached{Entity}Repository.php

/**
 * Cached Customer Repository Decorator
 *
 * Responsibilities:
 * - Read-through caching with Stale-While-Revalidate (SWR)
 * - Cache key management via CacheKeyBuilder
 * - Graceful fallback to database on cache errors
 * - Delegates ALL persistence operations to inner repository
 *
 * Cache Invalidation:
 * - Handled by *CacheInvalidationSubscriber classes via domain events
 * - This class only reads from cache, never invalidates (except delete)
 */
final class CachedCustomerRepository implements CustomerRepositoryInterface
{
    public function __construct(
        private CustomerRepositoryInterface $inner,  // Wraps MongoCustomerRepository
        private TagAwareCacheInterface $cache,
        private CacheKeyBuilder $cacheKeyBuilder,
        private LoggerInterface $logger
    ) {}

    /**
     * Proxy all other method calls to inner repository
     * Required for API Platform's collection provider compatibility
     * @param array<int, mixed> $arguments
     */
    public function __call(string $method, array $arguments): mixed
    {
        return $this->inner->{$method}(...$arguments);
    }

    public function find(mixed $id, int  = , ?  = ): ?
    {
         = ->cacheKeyBuilder->(() );

         {
             ->cache->(
                ,
                fn (ItemInterface ) => ->(, , , , ),
                beta:   
            );
        }  (\ ) {
            ->(, );
             ->inner->(, , );  
        }
    }

     {
         = ->cacheKeyBuilder->();

         {
             ->cache->(
                ,
                fn (ItemInterface ) => ->(, , )
            );
        }  (\ ) {
            ->(, );
             ->inner->();
        }
    }

     {
        ->inner->();
        
    }

     {
        
         {
            ->cache->([
                ,
                ,
                ,
            ]);
            ->logger->(, [
                 => ->(),
                 => ,
                 => ,
            ]);
        }  (\ ) {
            ->logger->(, [
                 => ->(),
                 => ->(),
                 => ,
            ]);
        }
        ->inner->();
    }

     {
        ->();  
        ->([, ]);

        ->logger->(, [
             => ,
             => ,
             => ,
        ]);

         ->inner->(, , );
    }

     {
        ->();  
         = ->cacheKeyBuilder->();
        ->([, , ]);

        ->logger->(, [
             => ,
             => ,
        ]);

         ->inner->();
    }

     {
        ->logger->(, [
             => ,
             => ->(),
             => ,
        ]);
    }
}

Step 4: Create Event Subscribers for Invalidation

Location: src/Core/{Entity}/Application/EventSubscriber/{Event}CacheInvalidationSubscriber.php

IMPORTANT: Create ONE subscriber per event (CustomerCreated, CustomerUpdated, CustomerDeleted).

/**
 * Customer Updated Event Cache Invalidation Subscriber
 * Handles email change edge case (both old and new email caches)
 */
final readonly class CustomerUpdatedCacheInvalidationSubscriber implements DomainEventSubscriberInterface
{
    public function __construct(
        private TagAwareCacheInterface $cache,
        private CacheKeyBuilder $cacheKeyBuilder,
        private LoggerInterface $logger
    ) {}

    public function __invoke(CustomerUpdatedEvent $event): void
    {
        // Best-effort: don't fail business operation if cache is down
        try {
            $tagsToInvalidate = $this->buildTagsToInvalidate($event);
            $this->cache->invalidateTags($tagsToInvalidate);
            $this->logSuccess($event);
        } catch (\Throwable $e) {
            $this->logError($event, $e);
        }
    }

    /** @return array<class-string> */
     {
         [::];
    }

    
     {
         = [
             . ->(),
             . ->cacheKeyBuilder->(->()),
            ,
        ];

        
         (->() && ->() !== ) {
            [] =  . ->cacheKeyBuilder->(->());
        }

         ;
    }

     {
        ->logger->(, [
             => ->(),
             => ->(),
             => ->(),
             => ,
             => ,
        ]);
    }

     {
        ->logger->(, [
             => ->(),
             => ->(),
             => ->(),
             => ,
        ]);
    }
}

Simpler subscriber for Created/Deleted events:

final readonly class CustomerCreatedCacheInvalidationSubscriber implements DomainEventSubscriberInterface
{
    public function __construct(
        private TagAwareCacheInterface $cache,
        private CacheKeyBuilder $cacheKeyBuilder,
        private LoggerInterface $logger
    ) {}

    public function __invoke(CustomerCreatedEvent $event): void
    {
        try {
            $this->cache->invalidateTags([
                'customer.' . $event->customerId(),
                'customer.email.' . $this->cacheKeyBuilder->hashEmail($event->customerEmail()),
                'customer.collection',
            ]);
            $this->logger->info('Cache invalidated after customer creation', [
                'customer_id' => $event->customerId(),
                'event_id' => $event->eventId(),
                'operation' => ,
                 => ,
            ]);
        }  (\ ) {
            ->logger->(, [
                 => ->(),
                 => ->(),
                 => ->(),
                 => ,
            ]);
        }
    }

    
     {
         [::];
    }
}

Step 5: Configure services.yaml

Location: config/services.yaml

services:
  # Base repository - used by API Platform for collections
  App\Core\Customer\Infrastructure\Repository\MongoCustomerRepository:
    public: true

  # Cached repository - wraps base repository with caching
  App\Core\Customer\Infrastructure\Repository\CachedCustomerRepository:
    arguments:
      $inner: '@App\Core\Customer\Infrastructure\Repository\MongoCustomerRepository'
      $cache: '@cache.customer'

  # Alias interface to cached repository for dependency injection
  App\Core\Customer\Domain\Repository\CustomerRepositoryInterface:
    alias: App\Core\Customer\Infrastructure\Repository\CachedCustomerRepository
    public: true

  # Cache invalidation event subscribers - explicitly inject cache.customer
  App\Core\Customer\Application\EventSubscriber\CustomerCreatedCacheInvalidationSubscriber:
    arguments:
      $cache: '@cache.customer'

  App\Core\Customer\Application\EventSubscriber\CustomerUpdatedCacheInvalidationSubscriber:
    arguments:
      $cache: '@cache.customer'

  App\Core\Customer\Application\EventSubscriber\CustomerDeletedCacheInvalidationSubscriber:
    arguments:
      $cache: '@cache.customer'

  # CacheKeyBuilder - auto-registered via App\ namespace

CRITICAL: Always explicitly inject the named cache pool (@cache.customer) instead of relying on autowiring.

Step 6: Configure Cache Pools

Production - config/packages/cache.yaml:

framework:
  cache:
    app: cache.adapter.redis
    default_redis_provider: '%env(resolve:REDIS_URL)%'

    pools:
      app:
        adapter: cache.adapter.redis
        default_lifetime: 86400 # 24 hours
        provider: '%env(resolve:REDIS_URL)%'
      cache.customer:
        adapter: cache.adapter.redis
        default_lifetime: 600 # 10 minutes
        provider: '%env(resolve:REDIS_URL)%'
        tags: true # REQUIRED for TagAwareCacheInterface

Test - config/packages/test/cache.yaml:

framework:
  cache:
    app: cache.adapter.array
    default_redis_provider: null
    pools:
      app:
        adapter: cache.adapter.array
        provider: null
      cache.customer:
        adapter: cache.adapter.array
        provider: null
        tags: true # CRITICAL: Must have tags: true for TagAwareCacheInterface!

CRITICAL: Test cache pools MUST have tags: true for $cache->invalidateTags() to work!

Step 7: Verify with CI

make ci

---

The Three Pillars of Cache Management

1. Cache Policies (Keys, TTLs, Consistency)

What: Declare cache configuration before implementation

Key Elements:

• Cache key pattern (namespace + identifier)
• TTL (based on data freshness requirements)
• Consistency class (Strong, Eventual, SWR)
• Cache tags (for invalidation)

Example Policy Decision Matrix:

Data Type	TTL	Consistency	Invalidation
User profile	5-10 min	SWR	On update/delete
Product catalog	1 hour	SWR	On product change
Configuration	1 day	Strong	Manual/deployment
Search results	1 min	Eventual	Time-based only

See: reference/cache-policies.md for complete guide

2. Invalidation Strategies (Explicit, Never Implicit)

What: Explicit cache clearing on write operations

Strategies:

• Write-through: Invalidate immediately after writes
• Tag-based: Batch invalidation using cache tags
• Event-driven: Invalidate via domain events
• Time-based: TTL-only (for static data)

Critical Rule: ALWAYS invalidate explicitly on create/update/delete

// ✅ CORRECT
$this->repository->save($customer);
$this->cache->invalidateTags(["customer.{$id}"]);

// ❌ WRONG - Missing invalidation
$this->repository->save($customer);
// Cache now stale until TTL expires!

See: reference/invalidation-strategies.md

3. Testing (Stale Reads, Cold Start, Invalidation)

What: Comprehensive test coverage for all cache behaviors

Required Tests:

• ✅ Stale reads after writes
• ✅ Cache warmup on cold start
• ✅ TTL expiration behavior
• ✅ Tag-based invalidation
• ✅ SWR background refresh (if applicable)

See: examples/cache-testing.md

---

Stale-While-Revalidate (SWR) Pattern

When to use: High-traffic queries that tolerate brief staleness

How it works:

1. Serve cached data immediately (even if stale)
2. Refresh cache in background
3. Return fresh data on next request

Implementation:

public function findById(string $id): ?Customer
{
    return $this->cache->get(
        "customer.{$id}",
        fn($item) => $this->loadFromDatabase($id, $item),
        beta: 1.0  // Enable probabilistic early expiration
    );
}

See: reference/swr-pattern.md for complete implementation with background refresh

---

Integration with Hexagonal Architecture

Domain Layer

• NO caching - Pure business logic
• Domain entities are cache-agnostic
• Domain events carry data needed for cache invalidation

Application Layer

• Command Handlers publish domain events (not invalidate directly)
• Event Subscribers handle cache invalidation via domain events

Infrastructure Layer

• CachedXxxRepository decorates MongoXxxRepository (read-through caching)
• MongoXxxRepository handles persistence only
• Cache invalidation triggered by domain events, NOT in save()

Architecture Flow:

┌─────────────────────────────────────────────────────────────┐
│  Command Handler                                            │
│  └─ repository.save(customer)                               │
│  └─ eventBus.publish(CustomerUpdatedEvent)                  │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  CachedCustomerRepository (Decorator)                       │
│  └─ inner.save(customer)  // delegates to Mongo             │
│  └─ (NO invalidation here!)                                 │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  CustomerUpdatedCacheInvalidationSubscriber                 │
│  └─ cache.invalidateTags([...])  // event-driven!           │
└─────────────────────────────────────────────────────────────┘

Why Event-Driven Invalidation?

1. Decoupling: Repository doesn't know about cache invalidation strategy
2. Testability: Easier to test invalidation logic separately
3. Flexibility: Can add more invalidation logic without touching repository
4. Consistency: Same event triggers multiple side effects (cache, notifications, etc.)

---

Cache Observability

Log cache operations:

$this->logger->info('Cache miss - loading from database', [
    'cache_key' => $cacheKey,
    'customer_id' => $id,
    'operation' => 'cache.miss',
]);

Track metrics:

• Cache hit rate: cache.hit.total / (cache.hit.total + cache.miss.total)
• Cache miss rate: cache.miss.total / total_requests
• Cache operation latency: cache.operation.duration_ms
• Invalidation frequency: cache.invalidation.total

See: observability-instrumentation for complete instrumentation patterns

---

Common Pitfalls

❌ DON'T

• Don't cache without declaring policy first
• Don't cache without TTL
• Don't cache in Domain layer
• Don't use implicit invalidation (use events!)
• Don't share cache keys between different queries
• Don't cache sensitive data (PII, passwords, tokens)
• Don't cache without testing all paths
• Don't forget to log cache operations
• Don't invalidate in repository save() method (use event subscribers!)
• Don't forget to handle email changes (invalidate both old and new email caches)

✅ DO

• Declare complete cache policy before coding
• Use cache tags for flexible invalidation
• Test invalidation explicitly
• Use SWR for read-heavy, stale-tolerant data
• Invalidate on all writes (create, update, delete)
• Log all cache operations
• Monitor cache hit rate in production
• Add observability (logs, metrics)
• Use __call() magic method for API Platform compatibility
• Wrap ALL cache operations in try/catch

---

Unit Testing Patterns

Test Structure for Cached Repository

final class CachedCustomerRepositoryTest extends UnitTestCase
{
    private CustomerRepositoryInterface&MockObject $innerRepository;
    private TagAwareCacheInterface&MockObject $cache;
    private CacheKeyBuilder&MockObject $cacheKeyBuilder;
    private LoggerInterface&MockObject $logger;
    private CachedCustomerRepository $repository;

    protected function setUp(): void
    {
        parent::setUp();
        $this->innerRepository = $this->createMock(CustomerRepositoryInterface::class);
        $this->cache = $this->createMock(TagAwareCacheInterface::class);
        $this->cacheKeyBuilder = $this->createMock(CacheKeyBuilder::class);
        $this->logger = $this->createMock(LoggerInterface::class);

        $this->repository = new (
            ->innerRepository,
            ->cache,
            ->cacheKeyBuilder,
            ->logger
        );
    }

Required Test Cases for Cached Repository

// 1. Cache key built correctly
public function testFindUsesCacheWithCorrectKey(): void
{
    $customerId = (string) $this->faker->ulid();
    $cacheKey = 'customer.' . $customerId;
    $customer = $this->createMock(Customer::class);

    $this->cacheKeyBuilder->expects($this->once())
        ->method('buildCustomerKey')
        ->with($customerId)
        ->willReturn($cacheKey);

    $this->cache->expects($this->once())
        ->method('get')
        ->with($cacheKey, $this->isType('callable'), 1.0)
        ->willReturn($customer);

    $result = $this->repository->find($customerId);
    self::(, );
}


 {
     = () ->faker->();
     = ->(::);

    ->cache->(->())
        ->()
        ->( ());

    ->logger->(->())
        ->()
        ->(, ->());

    ->innerRepository->(->())
        ->()
        ->();

     = ->repository->();
    ::(, );
}


 {
     = () ->faker->();
     = ->(::);

    ->(->())->()->();
    ->(->())->()->([,  . ]);

    ->cache->(->())
        ->()
        ->(fn(, ) => ());

    
}


 {
     = ->(::);
    ->()->();
    ->()->();

    ->cache->(->())
        ->()
        ->([, , ]);

    ->innerRepository->(->())->()->();

    ->repository->();
}


 {
    ->cache->()
        ->( ());

    ->logger->(->())->();
    ->innerRepository->(->())->();

    ->repository->();  
}

Required Test Cases for Event Subscribers

// 1. Correct events subscribed
public function testSubscribedToReturnsCorrectEvents(): void
{
    $subscribedEvents = $this->subscriber->subscribedTo();
    self::assertContains(CustomerUpdatedEvent::class, $subscribedEvents);
}

// 2. Cache invalidated with correct tags
public function testInvokeInvalidatesCacheWithCorrectTags(): void
{
    $event = new CustomerUpdatedEvent(customerId: $customerId, currentEmail: '[e-mail]');

    $this->cache->expects($this->once())
        ->method('invalidateTags')
        ->with(['customer.' . $customerId, 'customer.email.hash123', 'customer.collection']);

    ($this->subscriber)($event);
}

// 3. Email change invalidates BOTH old and new email caches
public function testInvokeInvalidatesCacheWithEmailChange(): void
{
    $event =  (
        customerId: ,
        currentEmail: ,
        previousEmail: 
    );

    ->cache->(->())
        ->()
        ->(->(function () {
             (, )
                && (, );
        }));

    (->subscriber)();
}


 {
    ->cache->()
        ->( ());

    ->logger->(->())->();
    ->logger->(->())->();

    (->subscriber)();  
}

---

Integration with Other Skills

Identify queries to cache:

• query-performance-analysis - Find slow queries

Add observability:

• observability-instrumentation - Cache metrics and logs

Test cache behavior:

• testing-workflow - Test framework guidance

Architecture placement:

• implementing-ddd-architecture - Layer separation

---

Quick Reference

Pattern	Code Example
Read-through cache	$cache->get($key, fn($item) => $loadFromDb())
Set TTL	$item->expiresAfter(300) (seconds)
Set cache tag	$item->tag(['entity', 'entity.id'])
Invalidate by tag	$cache->invalidateTags(['entity.id'])
Clear all cache	$cache->clear()
Build cache key	"{prefix}.{id}" (namespace + identifier)
Enable SWR	$cache->get($key, $callback, beta: 1.0)

---

Additional Resources

Reference Documentation

• Cache Policies - TTL selection, consistency classes, policy matrix
• Invalidation Strategies - Write-through, tag-based, event-driven patterns
• SWR Pattern - Complete stale-while-revalidate implementation

Complete Examples

• Cache Implementation - Full repository with caching, invalidation, observability
• Cache Testing - Complete test suite for all cache behaviors

---

For detailed implementation patterns, invalidation strategies, and test patterns → See supporting files in reference/ and examples/ directories.