Flysystem Cached Adapter Laravel Package

Technical Evaluation

Architecture Fit

• Use Case Alignment: Ideal for Laravel applications requiring metadata caching (e.g., file sizes, last modified timestamps, checksums) to reduce redundant filesystem/database calls. Fits well in:
  • Media-heavy apps (e.g., e-commerce, CMS, asset pipelines).
  • High-read-low-write storage backends (S3, local FS, FTP).
  • Performance-critical workflows (e.g., thumbnail generation, file validation).
• Laravel Synergy: Complements Laravel’s built-in Storage facade (via league/flysystem-* adapters) and integrates with caching drivers (Redis, Memcached, file cache).
• Abstraction Layer: Decorator pattern ensures backward compatibility with existing Flysystem adapters without modifying core logic.

Integration Feasibility

• Low Coupling: Wraps existing Flysystem adapters (e.g., Local, S3, Ftp) with minimal boilerplate.

  use League\Flysystem\Cached\CachedAdapter;
  use League\Flysystem\Adapter\LocalAdapter;
  
  $adapter = new CachedAdapter(
      new LocalAdapter('/path/to/storage'),
      new \League\Flysystem\Cached\Storage\Psr6CacheStorage(
          $cachePool // PSR-6 cache (e.g., Redis)
      )
  );
  

• Laravel-Specific: Can be injected into Laravel’s Filesystem via service providers or config overrides.
• Dependency Graph: Lightweight (~500 LOC); no breaking changes to Laravel’s core.

Technical Risk

• Stale Cache: Risk of inconsistent metadata if cache isn’t invalidated properly (e.g., after file uploads/deletions).
  • Mitigation: Implement cacheInvalidator (e.g., League\Flysystem\Cached\CacheInvalidator) or use Laravel’s cache tags.
• Cache Bloat: Unbounded metadata caching could bloat memory for large filesystems.
  • Mitigation: Configure TTL (e.g., CacheStorage options) or use size-based pruning.
• Deprecation Risk: Last release in 2018; may lack compatibility with newer PHP/Flysystem versions.
  • Mitigation: Fork or patch if critical bugs arise (MIT license permits this).
• Testing Overhead: Requires cache invalidation tests to ensure metadata consistency.

Key Questions

1. Cache Strategy:
   • Should we use per-file TTL (e.g., 5 mins) or global invalidation (e.g., on Storage::put)?
   • How will we handle concurrent writes (e.g., race conditions in cache updates)?
2. Adapter Support:
   • Which Flysystem adapters (e.g., S3, Database) will we prioritize for caching?
   • Do we need custom logic for non-standard metadata (e.g., custom file attributes)?
3. Observability:
   • How will we monitor cache hit/miss ratios and stale metadata incidents?
4. Fallback Mechanism:
   • Should the system degrade gracefully (e.g., bypass cache on errors) or fail fast?

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • Primary Use: Wrap Laravel’s Storage facade adapters (e.g., local, s3) with CachedAdapter.
  • Cache Backend: Leverage Laravel’s cache config (Redis/Memcached recommended for production).
  • Service Container: Bind CachedAdapter as a singleton or context-bound service.
• Compatibility:
  • PHP 8.0+: May require polyfills for older PHP versions (e.g., array_key_first).
  • Flysystem v3: Confirmed compatibility; v2 may need adjustments.
  • Laravel Filesystem: Works with Filesystem::adapter() or custom adapters.

Migration Path

1. Phase 1: Proof of Concept
   • Replace a single adapter (e.g., local) in a non-critical module.
   • Validate cache hit ratio and performance gains (e.g., microtime benchmarks).
2. Phase 2: Core Integration
   • Update Laravel’s config/filesystems.php to use CachedAdapter for read-heavy disks.
   • Example:

     'disks' => [
         'local' => [
             'driver' => 'custom',
             'adapter' => CachedAdapter::class,
             'source' => storage_path('app'),
             'cache' => 'redis',
         ],
     ],
     

3. Phase 3: Full Rollout
   • Extend to all read-heavy adapters (e.g., s3, ftp).
   • Implement cache invalidation hooks (e.g., Storage::afterWriting).

Compatibility

• Backward Compatibility: Zero changes to existing code using Storage facade.
• Forward Compatibility: Risk of breaking if Flysystem introduces API changes (monitor updates).
• Fallback: Provide a non-cached adapter as a fallback in config (e.g., cache_ttl: 0).

Sequencing

Operational Impact

Maintenance

• Cache Management:
  • Requires TTL tuning (e.g., 1 min for dynamic files, 24h for static assets).
  • Manual invalidation needed for bulk operations (e.g., Storage::deleteDirectory).
• Dependency Updates:
  • Monitor league/flysystem and psr/cache for breaking changes.
  • Potential need to fork if upstream stalls (MIT license allows this).
• Logging:
  • Log cache hits/misses to identify stale metadata or performance regressions.

Support

• Common Issues:
  • Stale metadata: Users see outdated file sizes/mod times.
    • Resolution: Implement CacheInvalidator or Laravel cache tags.
  • Cache corruption: Silent failures if cache backend is unavailable.
    • Resolution: Add circuit breaker logic (fallback to non-cached adapter).
• Debugging:
  • Use Storage::disk()->has() and Storage::disk()->lastModified() to verify metadata.
  • Enable debugbar or laravel-debugbar to inspect cache storage.

Scaling

• Horizontal Scaling:
  • Cache backend (Redis/Memcached) must support multi-instance writes.
  • Consider local cache (e.g., file driver) for edge cases where distributed cache is unavailable.
• Performance:
  • Expected gains: 30–70% reduction in metadata calls (varies by workload).
  • Bottlenecks: Cache invalidation overhead for high-write workloads.
• Resource Usage:
  • Memory: Cache stores metadata (not file contents); monitor memory_get_usage().
  • Disk: Local cache may require cleanup for old entries.

Failure Modes

Ramp-Up

• Developer Onboarding:
  • Document cache invalidation patterns (e.g., when to call cacheInvalidator->invalidate()).
  • Provide benchmark scripts to compare cached vs. non-cached performance.
• Operational Training:
  • Train SREs on cache monitoring (e.g., Redis memory usage, hit ratio).
  • Document rollout rollback procedure (disable caching in config).
• Key Metrics to Track:
  • Cache hit ratio (hits / (hits + misses)).
  • Metadata fetch latency (P99).
  • Cache size growth over time.