Cache File Laravel Package

Getting Started

• composer require yiisoft/cache-file. The only runtime contract that matters is psr/simple-cache (Psr\SimpleCache\CacheInterface) — there is no Laravel or Yii runtime dependency you need to boot.
• Read two things, in this order: the PSR-16 spec (it is one page) and src/FileCache.php. This package is essentially a single class; the README plus that file is the entire API surface. Confirm the constructor/with* argument names in the exact version you pin, since the 1.x → 2.x line changed how the cache directory and permissions are configured.
• Minimum viable wiring: point it at a writable directory that Laravel does not own (storage/framework/cache/yiifile, not the file driver's directory), then use it as a black-box PSR-16 store:

$cache = new \Yiisoft\Cache\File\FileCache(storage_path('framework/cache/yiifile'));
$cache->set('report.42', $payload, 300);
$payload = $cache->get('report.42');

• Bind it once so it is injectable everywhere:

$this->app->singleton(CacheInterface::class, fn () =>
    new \Yiisoft\Cache\File\FileCache(storage_path('framework/cache/yiifile'))
);

• First real use case: a class that must stay framework-agnostic — an SDK client, an importer, a package you intend to publish — that needs caching but cannot type-hint Illuminate\Contracts\Cache\Repository. Type-hint CacheInterface, inject FileCache in Laravel, inject an in-memory PSR-16 in tests, and the class never learns about either framework.

Implementation Patterns

• Portable-service pattern (the reason to use this at all). Depend on Psr\SimpleCache\CacheInterface in your application code; let the container choose FileCache in production. This is the only pattern where this package earns its place in a Laravel codebase.
• Adapter pattern, if you want the Cache:: facade. Register a custom driver via Cache::extend('yiifile', ...) returning an Illuminate\Cache\Repository backed by a Store that delegates to FileCache. Worth it only if multiple developers will expect Cache::remember() ergonomics; otherwise you have written a shim to regain features you deliberately left behind.
• Side-by-side, not instead-of. Keep Laravel's file/redis driver for framework concerns (sessions, queues, view cache, rate limiting) and use this store for one narrow, explicit concern: long-lived generated artifacts, third-party API response caching, or a shared cache between a Laravel app and a non-Laravel sibling process.
• Explicit directory partitioning. Give each tenant, queue worker, or deployment its own subdirectory (.../yiifile/{tenant}). File-backed caches degrade badly when a single directory accumulates tens of thousands of entries and multiple writers contend on locks.
• Treat cleanup as a scheduled job. Call clear() from a scheduled command or on deploy, and prune by mtime for the rest. Do not rely on inline garbage collection to keep the directory small — its probability-based sweep is a best-effort heuristic, not a policy.
• Test against the contract, not the class. Run your suite with an in-memory PSR-16 implementation and keep one integration test that exercises FileCache against a sys_get_temp_dir() directory, so serialization and TTL behaviour are covered without slowing the suite.

Gotchas and Tips

• It is not a Laravel cache store. No tags, no remember/rememberForever, no increment/decrement, no flush prefix scoping. PSR-16 clear() wipes the whole directory. If you find yourself reimplementing those, you probably wanted Cache::store('file').
• Values must be serializable. The store persists PHP-serialized values; closures, resources, and open handles will fail or silently degrade. Large payloads mean large files and slower reads — this is a filesystem, not a memory tier.
• Deserialization is an attack surface. Anything that can write into the cache directory can potentially influence unserialize(). Keep the directory outside the webroot, tighten permissions, and pin allowed_classes behaviour if you are on a shared host.
• Directory must exist and be writable by the PHP user. www-data vs. your CLI user is the classic failure: artisan warms the cache, FPM cannot read or overwrite it, and you get permission-denied or silently stale hits. Run php artisan as the same user, or chmod the tree once and verify.
• TTL is evaluated lazily at read time and expired files are only removed opportunistically. Expired ≠ deleted. Anything measuring disk usage should expect overhead beyond live entries.
• Deploys leave stale entries behind. Keys are hashed into filenames, so old values survive a code change and will be served if the key is unchanged. Invalidate by versioning the key or the directory on deploy — do not assume a new release implies a cold cache.
• Hashed keys mean blind debugging. You cannot ls and recognise a key. When investigating, read the file mtime and contents directly, or temporarily log the key→path mapping. Use a stable key prefix (v2:tenant:) so you can reason about generations.
• Filesystem assumptions break on NFS and ephemeral containers. File locking is only as reliable as the underlying FS, and a container rebuild silently discards the cache. Do not put anything here you cannot recompute cheaply on cold start.
• Small-project risk. Thirteen stars and a single maintainer path means you should pin an exact version in composer.json, review the diff on upgrade, and have a one-line fallback (swap the PSR-16 implementation) ready. Because your code only depends on CacheInterface, that fallback is genuinely cheap — which is the strongest argument for using this package the way described above.