Cache Bundle Laravel Package

Getting Started

Start by confirming your runtime can even install 6.0.0 — this release is a hard gate, not a soft one:

php -v                      # must be >= 8.1
composer why-not vendor/package 6.0.0
composer require vendor/package:^6.0

Check three things in composer.json before you run the update:

1. "php": "^8.1" in your own require block (or a config.platform.php override), otherwise Composer may happily resolve a mix your CI can't run.
2. Nothing in your dependency tree pins symfony/* to ^4.0 — 6.0.0 dropped Symfony 4, so those constraints will now conflict and you'll need to bump the offending package first.
3. If you use the Memcache driver, plan the migration before the upgrade (see Gotchas) — it is removed, not deprecated.

Where to look first, in order: the README's upgrade section, CHANGELOG.md for the 6.0.0 entry, and the adapter/driver directory to see which backends still exist. If the package publishes config, run php artisan vendor:publish --tag=<package>-config and diff the result against your existing config file — removed keys won't error, they'll just be silently ignored.

First useful use case: bind the cache pool in a service provider and use it cache-aside for an expensive query, so you get value on day one and a clear rollback point:

$this->app->singleton(CacheItemPoolInterface::class, fn ($app) => new Pool(
    $app->make(DriverFactory::class)->create($app['config']['cache.stores.redis'])
));

Then $pool->getItem('users:active')->isHit() in a repository class. Once that path is covered by a test using the array/null adapter, expand to tags and TTLs.

Implementation Patterns

Wrap, don't scatter. The package's pool is a low-level primitive; give it one seam in your app (App\Support\Cache\PoolFactory or a bound interface) and inject that. When the next 6.x release touches adapters, you change one file.

Keep Laravel's cache and this package on speaking terms. The most common integration is a decorator around Eloquent queries rather than a wholesale replacement of the framework cache:

final class CachedUsers implements UserReader
{
    public function __construct(
        private UserReader $inner,
        private CacheItemPoolInterface $pool,
    ) {}

    public function active(): array
    {
        $item = $this->pool->getItem('users:active');
        if (!$item->isHit()) {
            $this->pool->save($item->set($this->inner->active())->expiresAfter(300));
        }
        return $item->get();
    }
}

Interface-segregated decorators like this are also the cleanest way to migrate driver-by-driver: swap the binding per environment.

Adapter selection via config, not code. Map a config key (cache.driver) to a factory switch, with array/null for testing and local environments. Keep the mapping in one place so the Memcache removal is a one-line deletion rather than a hunt.

Invalidation strategy up front. Decide between TTL-only expiry, tag-based invalidation, or explicit deleteItems() on write paths, and write it down. Most cache bugs are stale-data bugs, not driver bugs. If you use tags, remember they're usually not supported by every backend — verify per adapter rather than assuming.

Testing pattern. Use the in-memory adapter in phpunit.xml env, assert behaviour (isHit() before/after save) rather than asserting on cache internals, and add one integration test per real backend behind a group that CI runs only when the service container is available.

Warm-up and versioning. Namespace your keys with a schema version (users:v2:active). Bumping the version on deploy is a cheaper, safer invalidation than flushing a shared Redis instance that other services also use.

Gotchas and Tips

Memcache is gone, not deprecated. Memcache (the old PECL extension, no "d") is removed in 6.0.0. You must move to Memcached (different extension, different API). Watch for: ext-memcached not installed in your base image, libmemcached missing on Alpine, serialization format differences (old cached values will be garbage after the switch — flush or re-key), and key-length limits differing between the two. Budget a cache-cold deploy.

PHP 8.1 types can bite subclasses. This release "uses PHP 8.1 features and types," which in practice means added parameter types, return types, readonly, enums, and possibly never/static returns. If you subclass any package class or implement its interfaces, untyped overrides that used to be tolerated will now throw fatal signature errors. Grep your codebase for extends/implements referencing the package namespace before upgrading. You cannot paper over these with #[\ReturnTypeWillChange] — you need to actually add the types.

Symfony 4 removal is a transitive-dependency problem, not a direct one. Most people who hit it won't have symfony/* in their own require. Use composer why symfony/console (or composer depends) to find which package is holding you back, and upgrade that package first. -W (--with-all-dependencies) is usually needed here.

Mocking gotchas. If a method now returns static or has a union return type, hand-rolled test doubles and older PHPUnit getMockBuilder chains can break. Prefer createMock()/createStub() from a current PHPUnit, and check that your test PHP version matches production — 8.1 vs 8.2 differences in readonly semantics will show up as odd failures.

Debugging misses. When something "isn't caching," check in this order: is the item actually saved (return value of save()), does the adapter support the TTL you passed (some silently cap or reject long TTLs), is the key being transformed (hashing/prefixing), and is the clock consistent between app servers. Log isHit() misses with key names in non-production for a day after migrating.

Extension points. Custom adapters and decorators are the intended extension seam — implement the package's adapter interface rather than reaching into concrete driver classes, so future driver changes don't cascade. If you maintained a private Memcache adapter, this is the moment to port it to Memcached; don't vendor a copy of the removed code, because 6.x internals are now typed against PHP 8.1 and will drift.

Config quirks. Removed config keys fail silently. After upgrading, diff a freshly published config against yours and delete orphans explicitly — leaving a memcache block in place is the kind of thing that survives for two years and confuses the next person.