Alternative Laravel Cache Laravel Package

Getting Started

• Install with composer require <vendor>/<package>:^6.4. 6.4.0 builds on the 6.3.3 compatibility patch (no more direct reliance on Illuminate\Cache\CanFlushLocks, which is Laravel 13-only), so the package still installs and boots on Laravel 12 and earlier. If you were pinned to 6.3.2 or holding back laravel/framework, 6.4.0 is the version to move to.
• First place to look after upgrading: config/cache.php. 6.4.0 makes the file, Redis and Memcached stores honour config('cache.serializable_classes'), and adds a package-level config('cache.serializable_base_classes'). If neither key exists in your config yet, decide deliberately what belongs there rather than leaving it empty by accident.
• Second place: anywhere you touch the file cache store. It now uses Laravel's Filesystem instead of Flysystem, matching the framework's own file store, so custom wrappers, path assumptions, or permission handling around storage/framework/cache/data are the most likely breakage surface.
• Minimal smoke test before wiring anything real:

  // 1. serialization allowlist
  Cache::put('demo', new App\Support\DemoDto(1), 60);
  dump(Cache::get('demo')); // object round-trips? or silently null?
  
  // 2. file store still reads/writes
  Cache::store('file')->put('demo-file', ['ok' => true], 60);
  dump(Cache::store('file')->get('demo-file'));
  
  // 3. lock flush behaviour (carried over from 6.3.3)
  Cache::lock('demo-lock', 10)->get(fn () => 'ok');
  Artisan::call('cache:clear');
  dump(Cache::lock('demo-lock', 10)->get()); // still acquirable?
  

• First real use case: replacing your ad-hoc unserialize() allowlists / allowed_classes juggling in a custom cache repository with the package's config-driven serialization. One config key, applied consistently across file/Redis/Memcached, instead of per-store guesswork.

Implementation Patterns

• Allowlist your cacheable value objects. Put your DTOs, value objects, and cache payload classes in cache.serializable_classes. Cache small, explicit classes — not whole Eloquent models with relation graphs — and treat the list as a security boundary, because it is what gates deserialization of whatever is sitting in Redis or on disk.
• Use serializable_base_classes for the "many subclasses" case. If you have a family of objects (e.g. every App\Domain\Events\* or anything implementing a marker interface), listing each concrete class becomes unmaintainable. This package-only key exists for exactly that; keep it as tight as you can — abstract bases and narrow interfaces, not stdClass or a broad root interface.
• Deploy/ops pipeline. Keep the lock-flush call from 6.3.x in your release script, and add a cache flush on the deploy that introduces or changes the serialization config. Old entries written under a different allowlist will not deserialize the way you expect.
• Test-environment reset. Route cache flushes through the package so lock release and serialization config are exercised in one place. Assert on state, not exit codes: Cache::lock($key, 1)->get() should succeed after a flush, and a cached DTO should come back as the DTO class (not __PHP_Incomplete_Class, not null).
• Multi-store awareness. File in local, Redis in production, array in tests. File/Redis/Memcached honour the new config; the array store never serializes, so a green test suite on array proves nothing about allowlist behaviour. Add at least one test that runs against file or redis.
• Custom store / decorator authors. 6.4.0 "adds missing methods to stores to reflect actual Laravel's stores." If you subclass or decorate a store, diff the method list against the package's store before upgrading — missing methods are a fatal-error class of breakage, not a soft one.
• Version pinning in CI. Keep the Laravel 12/13 matrix for cache/lock-touching code. 6.3.3 existed because those two lines diverge on lock flushing, and 6.4.0's serializable_classes handling is another place where framework version can matter.

Gotchas and Tips

• Silent cache misses are the headline failure mode. A class that isn't in the allowlist doesn't always throw — depending on store and path you get null back or a __PHP_Incomplete_Class. A cache that "stopped working" right after upgrading usually means the payload class isn't listed. Assert on the returned type, not just non-null.
• Changing the allowlist invalidates existing entries. Entries serialized before the config change can no longer be hydrated. Flush the relevant store as part of the same deploy, and don't tighten the allowlist in production without a plan for the entries already on disk/in Redis.
• Flysystem → Filesystem in the file store is a real internal swap. Check: does anything in your code rely on Flysystem adapters, visibility, or streams for the file cache? Do the cache directories still have the right owner/permissions? If you extended or mocked the file store, your test doubles may no longer line up.
• Config key names differ by origin. cache.serializable_classes mirrors the framework's key; cache.serializable_base_classes is package-specific. Don't assume every Laravel version ships or reads both — guard on framework version or config()->has() when your app supports a wide range.
• Array store hides problems. As above: it never serializes, so tests on array pass while Redis fails in production. Test the serialization path against a store that actually round-trips bytes.
• Debug tip: pull the raw value from the store (Redis::get($key), or read the file under storage/framework/cache/data) and inspect the serialized payload. If the class name is right but hydration fails, it's an allowlist problem; if the payload is missing, it's a store/keyspace problem — different bugs.
• Don't over-widen the base-class list. It's the easy escape hatch when allowlist curation gets annoying, but it reopens exactly the deserialization risk the allowlist was meant to close. Prefer a narrow marker interface over a broad one.
• Lock-flush behaviour still needs asserting. The 6.3.3 change removed direct CanFlushLocks usage; 6.4.0 doesn't restore it. After any flush, test that the lock is actually gone rather than trusting a successful return, and avoid referencing CanFlushLocks in your own code (interface_exists() guard if you must).
• Extension point: keep the package calls (flush, serialization config consumption) behind a thin service class. Both the lock-flush surface and the serialization config surface have moved in the last two releases; a single wrapper keeps the next bump a one-file edit.