Hierarchical Cache Laravel Package

Getting Started

Install the package to add hierarchical cache invalidation to any PSR-6 pool. It doesn’t provide a cache driver itself—instead, it wraps existing PSR-6 pools (e.g., symfony/cache, php-cache/file-cache) to enable prefix-based flushing of nested keys.

First use case: Invalidate all user-specific cache entries (e.g., |users|123|profile, |users|123|settings, |users|123|recent-activity) by clearing just |users|123|.

Get started in 3 steps:

1. composer require cache/hierarchical-cache
2. Wrap your PSR-6 pool:

   use Cache\HierarchicalCache\HierarchicalCachePool;
   $pool = new HierarchicalCachePool($yourPsr6Pool);
   

3. Use |-delimited keys and flush with a prefix ending in |:

   $pool->clear('|users|123|'); // clears all keys starting with this prefix
   

Start with the official hierarchy docs for syntax and examples.

Implementation Patterns

• Key Convention: Use | as delimiter (e.g., |products|{sku}|inventory|{warehouse} or |comments|{post_id}|{comment_id}). Leading | is required.
• Flushing Strategies:
  • Flush entire user contexts: $pool->clear('|users|123|');
  • Flush a whole product’s variants: $pool->clear('|products|sku-789|variants|');
  • Avoid trailing fragments: |users|123 won’t match anything—always end prefixes with |.
• Laravel Integration:
  • Extend CacheManager to register a custom hierarchical-redis store.
  • Wrap the underlying pool (e.g., Redis) at service creation:

    // In App\Extensions\HierarchicalRedisAdapter
    $pool = new HierarchicalCachePool(new \Cache\Adapter\Redis\RedisPool($client));
    

• Layer with Tagging: Chain TaggableCache after HierarchicalCachePool for dual invalidation (e.g., |users|123|* + tag:recent-activity).
• Testing: Wrap ArrayCachePool with HierarchicalCachePool for deterministic, in-memory tests of hierarchy logic.

Gotchas and Tips

• ⚠️ Hardcoded Delimiter: Keys must use |—no configuration exists. Keys without leading | break hierarchy (e.g., users|123 won’t match |users|123|*).
• ⚠️ Trailing | is mandatory: clear('|users|123') hits no items; clear('|users|123|') flushes |users|123|profile, |users|123|orders|*, etc.
• Performance Trap: clear() scans all items in the underlying pool (O(n)). Avoid broad prefixes like | or |app| on production caches—preflight with dump() in non-prod.
• Pool Requirements: Underlying pool must support reliable iteration (getItems(), hasItem(), deleteItem()). Avoid pools with aggressive LRU eviction that skip items during iteration.
• Optimize for Backends: Extend HierarchicalCachePool and override getKeysMatching() to use native prefix scans (e.g., Redis KEYS "|users|*" or memcached scan), bypassing full pool iteration.
• Maintenance Status: Last updated in 2022 (0 dependents). For new projects, benchmark alternatives like Symfony’s TagAwareAdapter (PSR-6) or CacheManager with custom invalidation logic—especially if PSR-16 is acceptable.