Apcu Adapter Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require cache/apcu-adapter
   

   No additional configuration is required—APCu must be enabled in your PHP environment (extension=apcu in php.ini).

2. First Usage:

   use Cache\Adapter\Apcu\ApcuCachePool;
   
   $cache = new ApcuCachePool();
   $item = $cache->getItem('key');
   $item->set('value')->expiresAfter(3600); // Cache for 1 hour
   $cache->save($item);
   

3. Key Use Case: Replace Laravel’s default cache driver (e.g., file, redis) in config/cache.php:

   'apcu' => [
       'driver' => 'cache',
       'store' => 'apcu',
   ],
   

   Then use it via Laravel’s cache facade:

   Cache::put('key', 'value', 3600); // Uses ApcuCachePool under the hood
   

Implementation Patterns

Core Workflows

1. Tag-Based Cache Invalidation:

   $cache = new ApcuCachePool();
   $cache->getItem('user:1')->tag(['users', 'premium']);
   $cache->save($item);
   // Later, clear all items tagged 'users':
   $cache->deleteItemsMatchingTag('users');
   

2. Hierarchical Caching: Leverage APCu’s prefixing to simulate namespaces:

   $cache = new ApcuCachePool('prefix_');
   $cache->getItem('config')->set('value');
   

3. Laravel Integration:

   • Service Provider: Bind the pool in AppServiceProvider:

     $this->app->bind('cache.store', function ($app) {
         return new ApcuCachePool();
     });
     

   • Cache Tags in Laravel: Use Cache::tags() for tag-based invalidation:

     Cache::tags(['users'])->put('user:1', $data);
     Cache::tags(['users'])->flush(); // Clears all tagged items
     

Performance Patterns

• Short-Lived Caches: Use expiresAfter() for transient data (e.g., API responses):

  $item->expiresAfter(60); // 1-minute TTL
  

• Bulk Operations:

  $cache->deleteItems(['key1', 'key2']); // Delete multiple keys
  $cache->getItems(['key1', 'key2']);   // Fetch multiple keys
  

Advanced Use Cases

• Cache Warming: Preload critical data during bootstrapping:

  $cache = new ApcuCachePool();
  $cache->save($cache->getItem('menu')->set(loadMenu()));
  

• Fallback Logic: Combine with other PSR-6 adapters (e.g., cache/array-adapter) for fallback:

  $pool = new CachePool([
      new ApcuCachePool(),
      new ArrayCachePool(), // Fallback
  ]);
  

Gotchas and Tips

Pitfalls

1. APCu Limitations:

   • Memory Constraints: APCu stores data in RAM. Monitor usage with apcu_cache_info().
   • No Persistence: Data is lost on server restart. Use for short-lived or regeneratable data.
   • Key Length: APCu keys are limited to 250 bytes (UTF-8). Avoid overly long keys.

2. Tagging Quirks:

   • Tags are not automatically synced across multiple ApcuCachePool instances (e.g., in clustered environments).
   • Use a single pool instance globally to avoid tag inconsistencies.

3. TTL Handling:

   • Passing null to expiresAfter() now defaults to 0 (infinite TTL), but older versions may behave differently. Test thoroughly.

Debugging

• Inspect APCu Cache:

  var_dump(apcu_cache_info('user')); // Check cache stats
  var_dump(apcu_fetch('key'));      // Debug raw APCu storage
  

• Enable APCu Logging: Add to php.ini:

  apc.logtime = 1
  apc.enable_cli = 1
  

Extension Points

1. Custom Pool Configuration: Override defaults (e.g., TTL behavior) by extending ApcuCachePool:

   class CustomApcuPool extends ApcuCachePool {
       protected function getDefaultTTL() {
           return 7200; // Default to 2 hours
       }
   }
   

2. APCu Prefix Isolation: Use unique prefixes per environment (e.g., dev_, prod_) to avoid collisions:

   $cache = new ApcuCachePool(env('APP_ENV') . '_');
   

3. Integration with Laravel Events: Listen to cache events (e.g., CacheStoreEvent) to log or transform cached data:

   Cache::store('apcu')->extend(function ($store) {
       $store->beforeSave(function ($key, $value) {
           // Pre-process data
       });
   });
   

Tips

• Benchmark Against Other Drivers: Compare APCu with file, redis, or database for your use case. APCu excels at low-latency, in-memory operations.
• Use for Session Storage: Laravel’s session.driver can use apcu for high-performance sessions (if APCu is enabled).
• Avoid Global State: Instantiate ApcuCachePool once (e.g., as a singleton) to share tag metadata across requests.