Laminas Cache Storage Adapter Apcu Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require laminas/laminas-cache-storage-adapter-apcu
   

2. Verify APCu is enabled in your PHP environment (php -m | grep apcu).
3. Basic usage (PSR-6 compatible):

   use Laminas\Cache\Storage\Adapter\Apcu as ApcuAdapter;
   
   $adapter = new ApcuAdapter();
   $adapter->setItem('key', 'value');
   $item = $adapter->getItem('key');
   

First Use Case: Caching Database Queries

$cache = new ApcuAdapter(['namespace' => 'db_queries']);
$cache->setItem('user_123', $userData, 3600); // Cache for 1 hour
$user = $cache->getItem('user_123')->get();

Implementation Patterns

Core Workflows

1. PSR-6 Cache Integration:

   // Laravel service provider binding
   $this->app->bind(\Psr\Cache\CacheItemPoolInterface::class, function ($app) {
       return new \Laminas\Cache\Storage\Adapter\Apcu(['namespace' => 'laravel']);
   });
   

2. Tag-Based Invalidation (APCu-specific):

   $adapter = new ApcuAdapter(['tags' => ['users']]);
   $adapter->setItem('user_123', $userData);
   $adapter->clearByTags(['users']); // Invalidate all tagged items
   

3. Fallback Strategies:

   $adapter = new ApcuAdapter(['fallback' => new FilesystemAdapter()]);
   

Laravel-Specific Patterns

1. Cache Configuration:

   // config/cache.php
   'apcu' => [
       'driver' => 'apcu',
       'namespace' => env('CACHE_APCU_NAMESPACE', 'laravel'),
       'tags' => ['users', 'products'],
   ],
   

2. Dynamic Cache Prefixes:

   $cache = Cache::store('apcu')->get('key', function () {
       return Model::query()->first();
   });
   

3. Cache Events:

   Cache::store('apcu')->extend('apcu', function ($item) {
       return (new ApcuItem($item->key(), $item->value(), $item->expiration()));
   });
   

Performance Optimization

• Use setItem() with TTL for automatic expiration:

  $adapter->setItem('key', $value, 60); // 60 seconds
  

• Batch operations for bulk cache management:

  $adapter->setItems([
      'key1' => 'value1',
      'key2' => 'value2',
  ], 3600);
  

Gotchas and Tips

Common Pitfalls

1. APCu Extension Requirements:

   • Ensure apcu.enable_cli=1 in php.ini for CLI applications.
   • Minimum APCu version: 5.1.10 (check with php -r "echo APCU_VERSION;").

2. Namespace Collisions:

   • Always define a namespace to avoid key conflicts:

     $adapter = new ApcuAdapter(['namespace' => 'app_']);
     

3. Memory Limits:

   • APCu is in-memory; monitor usage with apcu_cache_info().
   • Set apcu.cache_by_default=0 in php.ini to avoid unintended caching.

4. Tag Invalidation Quirks:

   • Tags are APCu-specific; ensure all adapters support them if mixing cache backends.

Debugging Tips

1. Check Cache Hits/Misses:

   $stats = apcu_cache_info();
   var_dump($stats['cache_list']);
   

2. Verify Item Existence:

   if (!$adapter->hasItem('key')) {
       // Handle miss
   }
   

3. Clear Cache Safely:

   $adapter->clear(); // Clears only the adapter's namespace
   apcu_clear_cache(); // Clears ALL APCu cache (use cautiously)
   

Extension Points

1. Custom Item Classes:

   class CustomApcuItem extends \Laminas\Cache\Storage\Item\ApcuItem {
       public function isHit() {
           // Custom logic
       }
   }
   $adapter = new ApcuAdapter(['itemClass' => CustomApcuItem::class]);
   

2. Plugin System:

   $adapter->addPlugin(new \Laminas\Cache\Storage\Plugin\Serializer());
   

3. Event Listeners:

   $adapter->addPlugin(new class implements \Laminas\Cache\Storage\Plugin\PluginInterface {
       public function __invoke($item, $operation) {
           // Log cache operations
       }
   });
   

Laravel-Specific Quirks

1. Cache Tags in Laravel:

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

     Cache::tags(['users'])->put('user_123', $user);
     Cache::tags(['users'])->flush();
     

2. Environment-Specific Config:

   // config/cache.php
   'apcu' => [
       'driver' => env('CACHE_DRIVER', 'apcu'),
       'namespace' => env('APP_NAME').'_".env('CACHE_APCU_NAMESPACE', ''),
   ],
   

3. Fallback to File Cache:

   // config/cache.php
   'stores' => [
       'apcu' => [
           'driver' => 'apcu',
           'fallback' => 'file',
       ],
   ],