Laravel Model Caching Laravel Package

Getting Started

• Install with composer require ghostcompiler/laravel-model-caching. v1.0.0 is the first tagged/stable release, so pin it ("^1.0") and treat the linked changelog as the only release artifact — there is no migration guide because this is the baseline.
• Publish the config and review it before use: php artisan vendor:publish --tag=model-caching (confirm the tag/name against the package README, since the release notes don't enumerate it).
• Pick a cache store that supports tags (Redis or Memcached) in every environment where you expect automatic invalidation. The file and database stores do not support cache tags and will silently weaken invalidation behavior.
• Add the package's Cachable trait to the models you want cached (verify the exact namespace from the README — it is typically a Traits\Cachable import). After that, normal Eloquent calls are cached transparently; you don't rewrite queries.
• First use case: take your slowest read-heavy endpoint (homepage feed, product/category listing, dashboard aggregates) and add the trait to its primary model. Measure the query count before/after — this is the fastest way to confirm the package is engaged and the store supports the required features.

Implementation Patterns

• Opt-in per model, not global. Add the trait only to models with expensive, read-mostly queries. Leave write-heavy or low-cardinality models uncached to avoid invalidation churn.
• Keep query code unchanged. Post::latest()->take(10)->get() is cached as a unit. Eager-loaded relations (with('author', 'comments')) are cached as part of the result set, so relation access after retrieval is free.
• Disable selectively per query using the package's cache-bypass (commonly ->disableCache()) for admin views, exports, or strongly consistent reads (e.g., right after a write in the same request).
• Tune per model via model properties — typically $cachePrefix (avoid key collisions across models/tenants) and a cooldown/TTL setting (often $cacheCooldownSeconds) to prevent stampedes on hot keys.
• Invalidate manually after bulk writes. For jobs, imports, or console commands that bypass model events, explicitly flush the relevant cache (via the package's flush API or Cache::tags(...)->flush()).
• Warm caches deliberately. Run a small artisan command or queued job after deploy to prime the hottest keys rather than letting the first users pay the cold-cache cost.
• Testing. Force a non-caching store (e.g., array) or disable the trait behavior in phpunit.xml so tests assert database state, not stale cache. Add at least one test that exercises invalidation end-to-end.
• Multi-tenant apps. Include tenant/team ID in $cachePrefix; otherwise tag-scoped invalidation can bleed across tenants.

Gotchas and Tips

• Query-builder writes bypass model events. Model::where(...)->update() / ->delete() do not fire Eloquent events, so automatic invalidation is skipped. Either iterate model instances or call the flush API immediately after.
• Transactions. Invalidation may occur before commit or inside the transaction; wrap carefully and flush after commit (e.g., DB::afterCommit) to avoid caching pre-commit or rolling-back state.
• Tag support is not optional in practice. On file/database stores, tag-based invalidation degrades or fails. Standardize on Redis in staging/prod and verify with a real invalidation test.
• refresh() / fresh() still hit the database. Don't assume these are cached; use them intentionally when you need guaranteed-fresh data.
• Mass assignment / updateOrCreate / seeders. These can leave stale entries. Flush after running seeders, factories, or data migrations, and consider flushing in CI setup.
• Relation invalidation is broader than you may expect. Touching a related model can invalidate the parent's cached result sets; keep prefixes specific and avoid caching models with very wide relationship graphs unless measured.
• Debugging stale data. Inspect the generated cache key (the package typically exposes a key method) and confirm the tag namespace. If keys don't change as expected, check $cachePrefix and the configured store.
• Pagination. Cached pages are keyed per page; deep pagination can balloon the key space. Cache only the first few pages or aggregate views.
• Extension points. Use $cachePrefix, cooldown/TTL settings, and cache events/hooks rather than forking. If you need custom keys or selective invalidation, build it on the package's public flush/tag API.
• v1.0.0 caveat. This is the initial stable tag with no substantive changelog body. Validate invalidation in your own stack (Redis, queue workers, Octane if used) before rolling out broadly, and watch upstream for 1.0.x fixes. If you run Octane or long-lived workers, confirm cache state is not held in-process across requests.