Laminas Cache Storage Adapter Filesystem Laravel Package

Technical Evaluation

Architecture Fit

• PSR-6/PSR-16 Compliance: The adapter fully supports PSR-6 (Cache Interface) and PSR-16 (Simple Cache Interface), making it a seamless fit for Laravel’s built-in caching abstractions (e.g., Illuminate\Cache\CacheManager). This ensures compatibility with Laravel’s caching contracts (CacheStore, CacheRepository).
• Laminas Cache Integration: Designed as part of the Laminas Cache ecosystem, it integrates cleanly with Laravel’s Laminas-based caching (if used via laminas/laminas-cache bridge). However, Laravel’s native file cache driver already exists, so this would serve as an alternative or extension rather than a replacement.
• TTL Granularity: Supports per-item TTL (Time-To-Live), which is more precise than Laravel’s default file cache (which historically used global TTLs). This is valuable for fine-grained cache invalidation in performance-critical applications.
• Metadata Handling: Introduces a dedicated Metadata object, improving cache analytics (e.g., tracking lastAccessTime, creationTime). Laravel’s default file cache lacks this granularity, making this adapter more suitable for observability-heavy applications.

Integration Feasibility

• Laravel Cache Driver Compatibility:
  • Can be registered as a custom cache driver in Laravel’s config/cache.php under drivers.
  • Requires minimal boilerplate (e.g., extending Illuminate\Cache\Repository or using Laravel’s CacheManager with a custom store).
  • Potential Challenge: Laravel’s default file driver uses a different serialization strategy (e.g., .cache vs. .dat suffixes in v3.0.0). Migration may require cache directory cleanup or backward-compatibility handling.
• Dependency Conflicts:
  • Requires laminas/laminas-cache (v4+), which may introduce version conflicts if the project uses older Laminas versions.
  • PHP 8.1+ required (Laravel 9+ is compatible, but older Laravel versions may need adjustments).
• Serializer Support:
  • Supports custom serializers (e.g., JMS\Serializer, Symfony\Component\Serializer), which is useful for complex objects (e.g., Closures, resources). Laravel’s default file cache relies on PHP’s serialize(), which may fail for unserializable objects.

Technical Risk

Key Questions for Stakeholders

1. Why replace Laravel’s default file cache?

   • Is this for PSR compliance, metadata tracking, or serializer flexibility?
   • Are there scalability or observability gaps in the current implementation?

2. Cache Migration Strategy

   • How will existing .cache/.dat files be handled during transition?
   • Should a dual-write phase (old + new cache) be implemented for zero downtime?

3. Performance vs. Features Tradeoff

   • Is the filesystem I/O overhead acceptable for the added features (e.g., TTL granularity)?
   • Would a hybrid approach (e.g., use this for metadata-heavy caches, default for others) work?

4. Long-Term Maintenance

   • Who will handle Laminas dependency updates (e.g., security patches)?
   • Is the team comfortable with Laminas’ roadmap (e.g., PHP 8.5+ support)?

Integration Approach

Stack Fit

• Laravel Version Compatibility:
  • Laravel 9+: Native support (PHP 8.1+).
  • Laravel 8.x: Possible with PHP 8.1+ and laminas/laminas-cache v4.
  • Laravel <8: Not recommended (PHP 7.4+ may work but lacks modern features).
• Existing Laravel Cache Drivers:
  • Primary Use Case: Custom driver for PSR-6 compliance or advanced metadata.
  • Secondary Use Case: Fallback for unserializable objects (e.g., Closures in queues).
• Alternatives Considered:
  • Laravel’s default file driver (simpler, but lacks PSR-6/TTL granularity).
  • symfony/cache-filesystem-adapter (similar but Symfony-centric).

Migration Path

1. Phase 1: Proof of Concept

   • Register the adapter as a custom driver in config/cache.php:

     'drivers' => [
         'laminas_filesystem' => [
             'driver' => 'laminas-filesystem',
             'path' => storage_path('framework/cache/laminas'),
             'options' => [
                 'unserializable_classes' => [App\Models\UnserializableModel::class],
             ],
         ],
     ],
     

   • Extend Laravel’s CacheManager to support the new driver:

     // app/Providers/AppServiceProvider.php
     Cache::extend('laminas_filesystem', function ($app) {
         return Cache::repository(new LaminasFilesystemStore(
             $app['config']['cache.stores.laminas_filesystem']
         ));
     });
     

   • Test: Verify Cache::put(), Cache::get(), and Cache::tags() work with TTLs.

2. Phase 2: Dual-Write Migration

   • For existing caches, implement a migration script to:
     • Read old .cache/.dat files.
     • Rewrite them using the new adapter’s format (.cache suffix, serialized metadata).
   • Example:

     php artisan cache:migrate-laminas
     

3. Phase 3: Deprecation of Legacy Cache

   • Once validated, update config/cache.php to default to the new driver.
   • Monitor for cache misses during transition.

Compatibility

• Laravel Cache Tags:
  • The adapter supports PSR-6 tags, so Laravel’s Cache::tags()->put() will work.
  • Caveat: Tag suffixes are fixed (unlike Laravel’s default, which uses ::).
• Cache Events:
  • Laravel’s CacheEvents (e.g., CacheStored, CacheMissed) will fire as usual.
• Queue Jobs:
  • If using serialized jobs, ensure unserializable_classes is configured to avoid unserialize() errors.

Sequencing

Operational Impact

Maintenance

• Dependency Updates:
  • laminas/laminas-cache is actively maintained (last release: 2026-03-10), but updates may require testing for BC breaks (e.g., v3.0.0’s .cache suffix change).
  • Mitigation: Use composer require laminas/laminas-cache:^3.0 with strict version pinning.
• Cache Directory Management:
  • Automatic Cleanup: The adapter supports TTL-based expiration, but Laravel’s cache:clear may need adjustments to handle the new .cache files.
  • Manual Intervention: Large cache directories may require manual pruning (e.g., find /path/to/cache -name "*.cache" -mtime +30 -delete).
• Logging:
  • Add cache operation logging (e.g., monolog channel) to track hits/misses:

    Cache::extend('laminas_filesystem', function () {
        $store = new LaminasFilesystemStore($config);
        $store->set