Filesystem Adapter Laravel Package

Getting Started

Start by installing the package via Composer: composer require cache/filesystem-adapter. Then set up a basic filesystem-based cache pool using Flysystem’s local adapter—ideal for small-to-medium applications or local development environments where APCu or Redis aren’t available or overkill. The simplest working example:

use League\Flysystem\Adapter\Local;
use League\Flysystem\Filesystem;
use Cache\Adapter\Filesystem\FilesystemCachePool;

$filesystem = new Filesystem(new Local(sys_get_temp_dir()));
$pool = new FilesystemCachePool($filesystem);

Store and fetch values like any PSR-6 implementation: $pool->getItem('key')->set('value')->expiresAfter(3600);.

Implementation Patterns

• Use in development or single-server deployments where shared caches (Redis/Memcached) aren’t needed. Great for local testing, CLI tools, or cron jobs that need cross-request state.
• Mount the cache directory in a phpunit.xml <php> block for isolated test environments, ensuring tests don’t interfere with each other.
• Wrap the pool in a service or factory (e.g., CacheManager) to abstract configuration—especially useful when swapping adapters (e.g., filesystem ↔ Redis) in config/cache.php.
• Use tags for granular cache invalidation (e.g., ->tag(['user:123', 'posts'])) when building admin panels or multi-entity caches where a subset needs clearing.
• Override the folder via $pool->setFolder('runtime/cache') to keep cache files in a non-public, writable path—avoiding web-root exposure.

Gotchas and Tips

• Filesystem-based caches aren’t safe for concurrent writes; race conditions can occur with high traffic on shared keys (e.g., addItem, deleteItem). Prefer for read-heavy or low-concurrency workloads.
• The cache uses PSR-6’s clear() to wipe all items under the pool’s folder—careful when using setFolder() with overlapping paths across multiple pools.
• By default, cache files are stored with filemtime for expiration—ensure your server’s filesystem supports sub-second precision if using short TTLs (< 1s).
• Avoid caching large data structures (e.g., > 1MB items); serialize overhead + disk I/O makes filesystem much slower than in-memory stores.
• To debug, inspect runtime/cache/ (or your custom folder) directly—each item maps to a .cache file, and tag groups are stored in subdirectories like tag/.
• Since the package is unmaintained (last release 2022), consider migrating to modern alternatives like symfony/cache with FilesystemAdapter for better support and features (e.g., caching PSR-16 and PSR-6 side-by-side).