- Can I use cache/filesystem-adapter as a drop-in Laravel cache driver?
- No. The package exposes a PSR-6 FilesystemCachePool, while Laravel's cache layer expects an Illuminate\Contracts\Cache\Store implementation with get, many, put, putMany, increment, decrement, forever, forget, flush and getPrefix. Using it inside Laravel means writing a custom store class that wraps the pool, and increment/decrement can only be emulated with a non-atomic read-modify-write. For a standard application, driver => 'file' in config/cache.php is the simpler and better-tested choice.
- How do I install cache/filesystem-adapter in a Laravel project?
- Run composer require cache/filesystem-adapter:^3.0, then wire the pool yourself as shown in the README: build a League\Flysystem\Filesystem with a LocalFilesystemAdapter and pass it to FilesystemCachePool. There is no Laravel service provider, config file or facade to publish, so you bind and alias the pool in your own provider. Check PHP and Laravel constraints with composer why-not before committing to it.
- Does cache/filesystem-adapter support Flysystem 3 and Laravel 10, 11 and 12?
- Version 3 declares support for both Flysystem 2.x and 3.x, and Laravel 10, 11 and 12 ship Flysystem 3.x. The current README example imports League\Flysystem\Local\LocalFilesystemAdapter, which is the 3.x API, although older documentation referenced the removed Flysystem 1.x League\Flysystem\Adapter\Local class. Confirm the actually resolved versions with composer show cache/filesystem-adapter and a short install spike before depending on it.
- What is the difference between this package and Laravel's built-in file cache driver?
- Laravel's file store is first-party: it is wired into the Cache facade, follows the framework's TTL, prefix and failure semantics, and is tested against Laravel's own contracts. This package is a framework-agnostic PSR-6 pool that stores items on any Flysystem filesystem, SHA-256 hashes keys into 256 shard directories, and supports tags. Pick it only when you genuinely need PSR-6 compatibility or a non-local Flysystem mount, otherwise it duplicates behaviour Laravel already owns.
- Does FilesystemCachePool support cache tags and tag invalidation?
- Yes, the pool implements the PSR-6 tag-aware interfaces, which Laravel's native file store does not offer. Tag index entries are persisted as ordinary files inside the same cache folder, so the sharded layout and folder validation rules apply to them too. If you subclass and override getFilePath(), you must return a deterministic path for internal tag-index keys as well as normal items.
- How are cache keys stored on disk and why SHA-256 hashing?
- Version 3 hashes every key with SHA-256 and writes the entry into one of 256 shard directories, which keeps filenames portable across filesystems and stops any single directory from holding the whole cache. Entries live under the pool folder, 'cache' by default, or whatever path you pass to the constructor. Nothing in the package sweeps expired files from disk, so you must plan your own reclamation or garbage collection strategy.
- Can I store the cache on S3 or another remote Flysystem mount?
- Yes, and that is the one genuinely differentiated capability here. Because storage is delegated to a Flysystem Filesystem, the pool can target object storage or a remote mount that Laravel's local file driver cannot address. Use setFilesystem() to swap the Filesystem instance at runtime, which also creates the current cache directory on the replacement, and setFolder() to change the folder with slash normalization and rejection of root or parent-directory segments.
- How do I customize the on-disk file layout with getFilePath()?
- Subclass FilesystemCachePool and override the protected getFilePath(string $key) method. Call parent::getFilePath() first so the portable key hash is preserved, then prefix or nest the returned path, for example adding a tenant segment per pool. Every returned path must be deterministic, stay below getFolder(), and cover internal tag-index keys as well as regular cache items.
- Is cache/filesystem-adapter safe for concurrent writes in production?
- Treat it cautiously. Filesystem writes are not atomic, so addItem and deleteItem races are possible when several processes write concurrently, and clear() or flush scoped to a folder can delete entries belonging to another pool sharing that folder. PSR-6 pools throw CacheException on I/O faults such as a full disk or bad permissions, so wrap calls in a try/catch boundary if a cache miss must never become a 500.
- Is cache/filesystem-adapter actively maintained, and what are the alternatives?
- Maintenance is a real concern: the repository is read-only as a monorepo split, has no upstream security patch stream, and release recency should be verified on Packagist rather than assumed. If PSR-6 over a filesystem is a contractual requirement, symfony/cache with its FilesystemAdapter provides PSR-6 and PSR-16 with active maintenance. If you only need caching inside Laravel, use the native file or Redis store and document the rationale for not adopting this package.