Namespaced Cache Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require php-cache/namespaced-cache
   

   Add to config/cache.php under stores (if not using default):

   'namespaced' => [
       'driver' => 'namespaced',
       'store' => 'file', // or 'redis', 'database', etc.
   ],
   

2. First Use Case

   use PhpCache\NamespacedCache\NamespacedCache;
   
   $cache = new NamespacedCache(app('cache.store'), 'my_namespace');
   $cache->set('key', 'value', 60); // Stores as `my_namespace:key`
   $value = $cache->get('key'); // Retrieves `my_namespace:key`
   

3. Where to Look First

   • README for basic usage.
   • src/NamespacedCache.php for core logic (e.g., how keys are prefixed).
   • tests/ for edge cases (e.g., nested namespaces, invalid keys).

Implementation Patterns

Workflows

1. Namespace Hierarchy Use dot notation for hierarchical namespaces (e.g., user:123:settings):

   $cache = new NamespacedCache(app('cache.store'), 'user.123.settings');
   

2. Dynamic Namespaces Generate namespaces dynamically (e.g., per user or tenant):

   $userCache = new NamespacedCache(app('cache.store'), "user:{$userId}");
   

3. Fallback to Global Cache For shared keys across namespaces, prefix with global::

   $cache->set('global:config', $config); // Accessible in all namespaces
   

Integration Tips

• Laravel Service Provider Bind the decorator to a custom cache key for reusability:

  $this->app->bind('cache.namespace', function ($app, $params) {
      return new NamespacedCache($app['cache.store'], $params[0]);
  });
  

  Usage:

  $cache = app('cache.namespace', ['user.123']);
  

• Cache Tags Combine with Laravel’s cache tags for namespace-aware invalidation:

  $cache->tags(['user:123'])->put('settings', $data);
  

• Middleware Attach namespaces to requests (e.g., for tenant isolation):

  $request->cacheNamespace = "tenant:{$request->tenantId}";
  $cache = new NamespacedCache(app('cache.store'), $request->cacheNamespace);
  

Gotchas and Tips

Pitfalls

1. Key Collisions Avoid using : in keys if the underlying store (e.g., Redis) treats it as a separator. Use underscores or URL-encode:

   $cache->set('user:profile', $data); // May fail in Redis
   $cache->set('user_profile', $data); // Safer
   

2. Namespace Depth Limits Some stores (e.g., Memcached) may fail with excessively long prefixed keys. Keep namespaces concise:

   // Bad: "user.123.orders.2023"
   // Good: "user_123_orders"
   

3. Tag Invalidation Quirks Cache tags are not automatically namespaced. Manually prefix tags:

   $cache->tags(["{$namespace}:settings"])->flush();
   

Debugging

• Verify Prefixed Keys Check the raw cache store to confirm keys are prefixed correctly:

  $store = app('cache.store');
  $store->get('my_namespace:key'); // Debug output
  

• Disable Namespacing Temporarily For testing, bypass the decorator:

  $cache = new NamespacedCache($store, '');
  

Extension Points

1. Custom Key Formatter Override the default : separator by extending NamespacedCache:

   class CustomNamespacedCache extends NamespacedCache {
       protected function getPrefix() {
           return '__'; // Custom separator
       }
   }
   

2. Multi-Store Support Chain multiple namespaces for fallback logic:

   $primary = new NamespacedCache($store, 'primary');
   $fallback = new NamespacedCache($store, 'fallback');
   $value = $primary->get('key') ?? $fallback->get('key');
   

3. Event Listeners Hook into cache events (e.g., CacheStore::itemStored) to log namespaced operations:

   Cache::store('namespaced')->extend(function ($store) {
       $store->listen(function ($event) {
           Log::debug("Namespaced cache event: {$event->key}");
       });
   });
   

Config Quirks

• Store-Specific Behavior Test with your target store (e.g., Redis vs. file). Some stores may handle prefixes differently.
• Default Namespace Set a default namespace in the decorator’s constructor or via DI:

  $cache = new NamespacedCache($store, config('cache.default_namespace'));