Cache Implementations Laravel Package

Getting Started

The PSR-16 Cache Implementations package (psr-discovery/cache-implementations) simplifies integration of PSR-16 compliant cache backends in Laravel. To start, install via Composer:

composer require psr-discovery/cache-implementations

For Laravel-specific use, pair with laravel/cache and configure in config/cache.php under the stores array. Example:

'stores' => [
    'redis' => [
        'driver' => 'redis',
        'connection' => 'cache',
        // ... other config
    ],
    'psr' => [
        'driver' => 'psr',
        'implementation' => 'Laminas\Cache\Storage\Adapter\Memory', // or 'Neos\Cache\Cache'
    ],
],

First use case: Replace a custom cache wrapper with a PSR-16 adapter (e.g., Laminas\Cache or Neos\Cache) for standardized caching across services.

Implementation Patterns

Laravel Integration

1. Cache Configuration: Use the psr driver in Laravel’s config/cache.php to delegate to supported PSR-16 implementations (e.g., Laminas\Cache, Neos\Cache). Example:

   'psr' => [
       'driver' => 'psr',
       'implementation' => 'Laminas\Cache\Storage\Adapter\Filesystem', // Filesystem, Memory, Redis, etc.
       'options' => [
           'cache_dir' => storage_path('framework/cache'),
       ],
   ],
   

   • Laminas Cache: Supports ^3.0–^4.0 (now expanded to ^4.0).
   • Neos Cache: Supports ^5.0–^8.0 (newly expanded).

2. Service Provider Binding: Bind the PSR-16 cache to Laravel’s container in a service provider:

   use Psr\Cache\CacheItemPoolInterface;
   use PsrDiscovery\CacheImplementations\Factory;
   
   public function register()
   {
       $this->app->singleton(CacheItemPoolInterface::class, function ($app) {
           return Factory::createCache('Laminas\Cache\Storage\Adapter\Redis', [
               'host' => config('cache.redis.host'),
               'port' => config('cache.redis.port'),
           ]);
       });
   }
   

3. Usage in Controllers/Jobs: Inject CacheItemPoolInterface and use PSR-16 methods:

   public function __construct(private CacheItemPoolInterface $cache) {}
   
   public function storeData()
   {
       $item = $this->cache->getItem('key');
       $item->set('value');
       $this->cache->save($item);
   }
   

Workflows

• Hybrid Caching: Combine Laravel’s native drivers (e.g., file, redis) with PSR-16 adapters for flexibility.
• Testing: Mock CacheItemPoolInterface in tests using PHPUnit\Framework\TestCase:

  $this->app->instance(CacheItemPoolInterface::class, $mockCache);
  

Gotchas and Tips

Breaking Changes (1.2.0)

• PHP 8.2 Requirement: Upgrade PHP to 8.2+ (Laravel 10+ compatible). Older versions will fail installation.
  • Fix: Update php in .php-version or server config.

Configuration Quirks

1. Neos/Laminas Version Mismatches:

   • Ensure installed versions align with supported ranges (e.g., neos/cache:^7.0 for Neos Cache).
   • Debug: Check composer.json for version conflicts:

     composer why neos/cache
     

2. PSR-16 Adapter Options:

   • Some adapters (e.g., Laminas\Cache\Storage\Adapter\Filesystem) require specific options like cache_dir. Omit these and the adapter may fail silently.
   • Tip: Refer to PSR-16 Discovery docs for adapter-specific configs.

3. Laravel Cache Driver Overrides:

   • If using the psr driver in config/cache.php, ensure no duplicate bindings exist in service providers to avoid conflicts.

Debugging

• Adapter Not Found:

  • Verify the FQCN (e.g., Laminas\Cache\Storage\Adapter\Redis) matches the installed package’s namespace.
  • Fix: Run composer dump-autoload after adding new cache implementations.

• Performance Issues:

  • Laminas\Cache\Storage\Adapter\Memory is in-memory only (cleared on restart). Use Filesystem or Redis for persistence.
  • Tip: Profile with Laravel Debugbar or laravel-debugbar to compare PSR-16 vs. native drivers.

Extension Points

1. Custom Adapters: Extend the package by adding your own PSR-16 implementations. Register them via:

   Factory::addImplementation('My\Cache\Adapter', MyCacheAdapter::class);
   

2. Dynamic Configuration: Use Laravel’s Cache::extend() to dynamically configure PSR-16 stores:

   Cache::extend('dynamic_psr', function ($app) {
       return Factory::createCache('Laminas\Cache\Storage\Adapter\Redis', [
           'host' => env('REDIS_HOST'),
       ]);
   });
   

3. Fallback Logic: Implement fallback caches for critical data:

   try {
       $value = $this->cache->get('critical_key');
   } catch (\Psr\Cache\InvalidArgumentException $e) {
       $value = $this->fallbackCache->get('critical_key');
   }