Cache Assist Laravel Package

Getting Started

Start by pulling the package in and confirming what it actually registers — CacheAssist is small, so there's no admin UI or migration to worry about, but you do need to know the exact helper signatures before wiring it into hot paths.

composer require smorken/cache-assist

Then, in order:

1. Read src/ before the README. With a low-star, zero-dependent package, the source is the spec. Look for the service provider (CacheAssistServiceProvider) to see what's bound into the container, and any config/cache-assist.php to see whether keys, TTLs, or a default store are configurable.
2. Check for a facade or helper file. Many small Laravel cache utilities ship either a CacheAssist facade or a global helper (cache_assist()), or they expose a trait you use on models/services. Identify which style this package uses before writing code around it.
3. Publish config if offered:

php artisan vendor:publish --tag=cache-assist-config

4. Run php artisan config:clear after any config edit — a stale cached config is the single most common "the package does nothing" cause.

First use case: take one expensive read — a dashboard aggregate, a menu tree, a settings lookup — and replace the raw call with the package's remember-style helper. Something along the lines of:

// before
$stats = Cache::remember('dashboard.stats', 600, fn () => $this->computeStats());

// after (verify exact method name in src/)
$stats = CacheAssist::remember('dashboard.stats', 600, fn () => $this->computeStats());

The payoff is consistency: one place decides how keys are namespaced, how TTLs default, and how entries are invalidated. Don't roll it out everywhere on day one — prove it on a single call site, then expand.

Implementation Patterns

Wrap reads, not writes. The core value of a cache-assist layer is the remember pattern. Keep cache population inside the closure so the cache is always derived from the source of truth:

public function activePlans(): Collection
{
    return CacheAssist::remember(
        CacheAssist::key('plans', 'active'),
        now()->addHour(),
        fn () => Plan::where('active', true)->orderBy('price')->get()
    );
}

Centralise key construction. Hardcoded string keys are how caches rot. If the package exposes a key builder, use it everywhere so that a rename or a tenant suffix is a one-line change:

CacheAssist::key('user', $user->id, 'permissions');
// => "cache-assist:user:42:permissions"

If it doesn't ship a key builder, define your own thin wrapper in a base service class and still route everything through the package's store handles — this keeps invalidation and TTL policy in one seam.

Invalidate via model events, not controllers. The reliable pattern is to forget cache in saved/deleted observers. That way seeders, queue jobs, and tinker all stay consistent:

static::saved(fn (Plan $plan) => CacheAssist::forget(
    CacheAssist::key('plans', 'active')
));

Use tags where the driver supports them for bulk invalidation of related entries, e.g. everything under a tenant or a model type:

CacheAssist::tags(['plans'])->remember('plans.active', 3600, $callback);
// later
CacheAssist::tags(['plans'])->flush();

Compose with existing infrastructure. Route cache warming through a queued job or an artisan command so deploy hooks can prime the hot keys. Don't warm caches synchronously in a request cycle.

Test with fakes. Assert cache behaviour rather than implementation:

Cache::spy();
$this->get('/dashboard');
Cache::shouldHaveReceived('remember')->once();

Where the package wraps the Cache facade, Cache::fake() and Cache::spy() still intercept calls — verify this holds for your installed version.

Gotchas and Tips

• Tags are driver-dependent. The file and database drivers silently reject tag operations. If you develop locally on file and deploy on redis, tag-based invalidation will work in production and quietly no-op (or throw) locally. Pin the same driver across environments or guard tag usage.
• Closures don't serialize. Anything you pass into the remember callback's return value must be serialisable if you're using a driver that stores PHP objects (redis, memcached, database with serialisation). Eloquent collections are fine; resources, closures, and stream handles are not.
• null TTL means forever, not "no cache." Confirm how the package handles a null or zero TTL — a wrapper that coerces null to 0 can create permanent entries you can never evict. Read the TTL handling in src/ before relying on defaults.
• Key prefix collisions across environments. If you share a Redis instance between staging and production, ensure the package's default prefix (or Laravel's CACHE_PREFIX) differs per environment. This is the classic "staging data in production cache" incident.
• Config caching in CI. After php artisan config:cache, edits to config/cache-assist.php are ignored. Add config:clear to your test bootstrap and your deploy script.
• Version pinning. With zero dependents and no star history, treat every release as potentially breaking. Pin to an exact version ("smorken/cache-assist": "1.2.3") and review the diff on upgrades — there's no community safety net catching regressions for you.
• Fork-friendly extension points. The service provider is the extension surface. If you need a different key strategy or store resolution, bind your own implementation over the package's container key rather than patching vendor/. Use a composer.json repositories VCS entry pointing at your fork if you do need to patch.
• Debugging misses. Cache::getStore() combined with driver-specific tooling (redis-cli MONITOR, php artisan cache:table for database) tells you far more than log lines. If a key isn't hitting, log the resolved key string — prefixes applied by the package and by Laravel's config both stack, and the final string is rarely what you'd guess.
• Watch invalidation scope. Over-eager flush() in an observer will wipe unrelated keys. Prefer targeted forget() on specific keys or a narrow tag, and add a test that asserts unrelated entries survive a model save.
• Document the TTL policy in your app, not the package. The package gives you a mechanism; staleness tolerance is a product decision. Write it down somewhere your team will find it.