Laminas Cache Storage Deprecated Factory Laravel Package

Getting Started

Minimal Steps to Begin

1. Install the Package Add to your composer.json:

   composer require laminas/laminas-cache-storage-deprecated-factory
   

   Ensure your project uses laminas/laminas-cache:^3.0 (not v4+).

2. Locate Legacy Usage Search your codebase for:

   use Laminas\Cache\StorageFactory;
   

   or instantiations like:

   $factory = new \Laminas\Cache\StorageFactory();
   

3. First Use Case: Replace the Factory Replace the deprecated factory with the temporary one:

   use Laminas\Cache\Storage\DeprecatedFactory;
   
   $factory = new DeprecatedFactory();
   

4. Verify Adapter Compatibility Test with your existing adapter configurations (e.g., Apcu, Redis, Filesystem). Example:

   $options = [
       'adapter' => [
           'name' => 'filesystem',
           'options' => [
               'cache_dir' => storage_path('framework/cache'),
           ],
       ],
   ];
   $cache = $factory->createService($options);
   

Implementation Patterns

Usage Patterns in Laravel

1. Service Provider Integration Bind the deprecated factory in a Laravel service provider to replace legacy instantiations:

   use Laminas\Cache\Storage\DeprecatedFactory;
   use Illuminate\Support\ServiceProvider;
   
   class CacheServiceProvider extends ServiceProvider
   {
       public function register()
       {
           $this->app->singleton('laminas.cache.deprecated_factory', function () {
               return new DeprecatedFactory();
           });
       }
   }
   

2. Facade Wrapper (Optional) Create a facade to abstract Laminas Cache usage:

   // app/Facades/LaminasCache.php
   namespace App\Facades;
   
   use Illuminate\Support\Facades\Facade;
   
   class LaminasCache extends Facade
   {
       protected static function getFacadeAccessor()
       {
           return 'laminas.cache.deprecated_factory';
       }
   }
   

3. Configuration-Driven Cache Setup Use Laravel’s config to define cache adapters and inject them via the factory:

   // config/laminas-cache.php
   'adapters' => [
       'default' => [
           'adapter' => 'filesystem',
           'options' => [
               'cache_dir' => storage_path('framework/cache'),
           ],
       ],
   ],
   

   Then resolve in a service:

   $factory = app('laminas.cache.deprecated_factory');
   $cache = $factory->createService(config('laminas-cache.adapters.default'));
   

4. Migration Workflow

   • Step 1: Replace StorageFactory with DeprecatedFactory in all instantiations.
   • Step 2: Update adapter configurations to v3.x syntax (if needed).
   • Step 3: Test cache-dependent features (e.g., sessions, rate limiting).
   • Step 4: Gradually migrate to laminas-cache v3.x APIs in your codebase.

5. Leveraging Laminas Service Manager (Optional) If your Laravel app uses Laminas Service Manager (e.g., for microservices), configure the factory in the Laminas DI container:

   $container->setFactory('Laminas\Cache\Storage\Factory', DeprecatedFactory::class);
   

Gotchas and Tips

Pitfalls

1. Not a Long-Term Solution

   • This package is temporary and not compatible with laminas-cache v4+. Plan to migrate away once all dependencies support v3.x.

2. Adapter-Specific Quirks

   • Some adapters (e.g., Apcu, Redis) may have subtle behavioral differences between v2.x and v3.x. Test thoroughly:

     // Example: Redis adapter may require updated options
     $options = [
         'adapter' => [
             'name' => 'redis',
             'options' => [
                 'host' => '127.0.0.1',
                 'port' => 6379,
                 'database' => 0,
                 // v3.x may require additional options like 'serializer'
             ],
         ],
     ];
     

3. PHP Version Lock-In

   • The package supports PHP 8.1–8.4. Ensure your Laravel app’s PHP version is within this range.

4. Laminas Dependency Bloat

   • Introduces laminas-servicemanager and laminas-stdlib as dependencies. Audit your composer.json for conflicts.

5. Facade Collisions

   • If your app uses both Laravel’s Cache facade and Laminas Cache, ensure namespaces are distinct to avoid ambiguity.

Debugging Tips

1. Verify Factory Instantiation

   • Log the factory class to confirm the deprecated version is loaded:

     $factory = new \Laminas\Cache\Storage\DeprecatedFactory();
     \Log::debug(get_class($factory)); // Should output: Laminas\Cache\Storage\DeprecatedFactory
     

2. Check Adapter Creation

   • Validate that adapters are created correctly:

     $cache = $factory->createService($options);
     \Log::debug(get_class($cache)); // Should output: Laminas\Cache\Storage\Adapter\PluginManager
     

3. Test Cache Operations

   • Verify basic CRUD operations:

     $cache->setItem('key', 'value');
     $item = $cache->getItem('key');
     \Log::debug($item->getData()); // Should output: 'value'
     

4. Handle Deprecation Warnings

   • The package may emit deprecation notices. Suppress them in development if needed:

     error_reporting(E_ALL & ~E_DEPRECATED);
     

Extension Points

1. Custom Factory Extensions

   • Extend DeprecatedFactory to add pre/post-processing logic:

     class CustomDeprecatedFactory extends \Laminas\Cache\Storage\DeprecatedFactory
     {
         public function createService(array $options)
         {
             $service = parent::createService($options);
             // Add custom logic (e.g., logging, metrics)
             return $service;
         }
     }
     

2. Adapter-Specific Overrides

   • Override adapter configurations dynamically:

     $factory = new DeprecatedFactory();
     $options['adapter']['options']['custom_key'] = 'custom_value';
     $cache = $factory->createService($options);
     

3. Integration with Laravel Events

   • Listen for cache events (e.g., cache.hit, cache.miss) to log or monitor usage:

     \Event::listen('cache.hit', function ($key, $item) {
         \Log::info("Cache hit for key: {$key}");
     });
     

4. Fallback to Laravel Cache

   • Implement a fallback mechanism if Laminas Cache fails:

     try {
         $cache = $factory->createService($options);
     } catch (\Exception $e) {
         $cache = \Cache::store('file'); // Fallback to Laravel's cache
     }
     

Configuration Quirks

1. Adapter Naming

   • Ensure adapter names match exactly (case-sensitive):

     // Correct:
     'adapter' => ['name' => 'filesystem']
     // Incorrect (will fail):
     'adapter' => ['name' => 'Filesystem']
     

2. Option Validation

   • laminas-cache v3.x may enforce stricter option validation. Refer to the Laminas Cache v3 docs for required options.

3. Service Manager Configuration

   • If using Laminas Service Manager, ensure the factory is registered before other cache-related services.

4. Laravel Caching Conflicts

   • Avoid naming conflicts with Laravel’s cache drivers (e.g., file, redis). Use unique names like laminas_filesystem.