Flexycache Bundle Laravel Package

Getting Started

The v0.1.1 release note is a single line — "An adapter is now used for cache clearing" — so treat this as a behavioural change to how the package invalidates its cache, not a documented feature. Before writing any code against it:

1. Confirm what the adapter is. Open composer.json for the package name, then read the service provider (src/*ServiceProvider.php) and look for a bind/singleton call for something like CacheAdapter, CacheClearer, or CacheStore. That binding is the contract you now interact with.
2. Diff the release. composer update --dry-run plus git diff v0.1.0..v0.1.1 in vendor/ will show exactly which class previously performed the clearing and whether it still exists. At v0.1.x there is no stability promise, so verify rather than assume.
3. Check for publishable config. php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider" — the adapter is almost certainly selected or configured there (driver name, store name, TTL, prefix).
4. First use case. The typical day-to-day flow is: content changes → the package's cache must be dropped → previously the package called Cache::forget()/flush() directly, now it delegates to the adapter. Your first task is to reproduce that flow in a feature test and confirm the cache is actually invalidated on v0.1.1.

If the README has not been updated for the adapter, don't infer the API from the release note alone — read the source, and pin the version in composer.json ("vendor/package": "0.1.1") until you're confident.

Implementation Patterns

Bind a custom adapter via the container. The value of the adapter indirection is that you can substitute your own implementation without touching package internals. In AppServiceProvider::register():

$this->app->bind(\Vendor\Package\Contracts\CacheAdapter::class, \App\Cache\TenantAwareCacheAdapter::class);

Confirm the exact interface name in src/Contracts first — this is the extension point the release introduces, and it is the main thing worth wiring up.

Decorate rather than replace. If the package ships a default adapter, wrap it instead of rewriting it — you keep upstream behaviour and add logging/metrics:

final class LoggingCacheAdapter implements CacheAdapter
{
    public function __construct(private CacheAdapter $inner) {}

    public function clear(): void
    {
        Log::info('package cache cleared', ['store' => config('package.cache.store')]);
        $this->inner->clear();
    }
}

Drive clearing from domain events, not controllers. Register an observer (saved/deleted) or listen to your own domain events and call the package's clearing path there. Cache invalidation triggered from a controller is the classic source of "stale after import/seed/queue job" bugs.

Per-environment adapter selection. Point the package at the array store in phpunit.xml and at Redis in production. Laravel's cache tags work on Redis/Memcached but not on file or database — if the adapter uses tags internally, file will silently degrade or throw.

Queue and scheduler integration. If clearing happens in a job, remember the job serialises the container-resolved dependencies fresh on each run; if it happens in a long-running process (Octane, Horizon worker), the adapter instance is resolved once — make it stateless or resolve per call.

Testing pattern. Use Cache::spy() or bind a fake adapter into the container and assert clear() was called, rather than asserting on cache contents. That keeps the test valid regardless of which store CI uses.

Gotchas and Tips

• This is likely a breaking change, disguised as a patch. A v0.1.1 bump that swaps the clearing mechanism can break any subclass or call site that relied on the old behaviour. There is no 0.2.0 here — at 0.x, semver gives you no guarantees. Read the diff before deploying.
• Config caching bites. Bindings registered in a service provider that reads env() directly will break under php artisan config:cache. Use config('package.cache.*') only, and re-run php artisan config:clear after changing the adapter binding.
• php artisan cache:clear is not the same thing. It flushes the whole store. The adapter exists to clear the package's entries. If you've "fixed" a stale-cache issue by running cache:clear in production, you have not exercised the new adapter path and won't know if it works.
• Store/prefix mismatches. If the adapter's configured store differs from the store the package writes to, clearing succeeds and does nothing. Assert on the configured store name in a test.
• Tags on unsupported drivers. file and database stores throw BadMethodCallException on tags(). If v0.1.1 introduced tag-based clearing, production on file will fail at the first invalidation — usually in a queue worker, hours later.
• Debugging checklist: (1) app(CacheAdapter::class)::class via tinker — is it the class you bound? (2) config('package.cache') — is the store correct? (3) does the call site still exist, or did v0.1.1 move it? (4) is a stale bootstrap/cache/config.php masking your binding?
• Extension points to prefer: the adapter contract, the published config file, and the package's events (if any). Avoid extending concrete classes — at 0.x they will move.
• Upgrade hygiene: add a test that asserts the package cache is empty after a model update. That single test protects you through the next several 0.x releases, which will very likely move this mechanism again.