Download the PHP package genealabs/laravel-model-caching without Composer

🚀 Model Caching for Laravel

🗂️ Table of Contents

• 📖 Summary
• 📦 Installation
• 🚀 Getting Started
• ⚙️ Configuration
• 🤝 Contributing
• ⬆️ Upgrading
• 🔐 Security
• 📚 Further Reading

📖 Summary

Automatic, self-invalidating Eloquent model and relationship caching. Add a trait to your models and all query results are cached automatically — no manual cache keys, no forgetting to invalidate. When a model is created, updated, or deleted the relevant cache entries are flushed for you.

⚡ Typical performance improvements range from 100–900% reduction in database queries on read-heavy pages. 🧪 Backed by 335+ integration tests across PHP 8.3–8.5 and Laravel 12–13.

Use this package when your application makes many repeated Eloquent queries and you want a drop-in caching layer that stays in sync with your data without any manual bookkeeping.

🔄 Before & After

❌ Without this package — manual cache keys, manual invalidation:

✅ With this package — add the trait, query normally:

✅ What Gets Cached

• Model queries (get, first, find, all, paginate, pluck, value, exists)
• Aggregations (count, sum, avg, min, max)
• Eager-loaded relationships (via with())
• Lazy-loaded relationships, such as $post->comments, are cached the same way as eager-loaded ones when the related model uses Cachable. The related model's query also runs through CachedBuilder, so you do not need with() to get caching.
• Custom column selections: select(), addSelect() and raw expressions are cached. The selected columns form part of the cache key.

🚫 What Does Not Get Cached

• inRandomOrder() queries — caching is automatically disabled since results should differ each time.
• lockForUpdate() and sharedLock() queries. They read from the database directly, and their results are never written to the cache.
• A query that eager-loads a relation whose related model does not use Cachable. That one relation stops the whole query from being cached: the base model's query is not cached, whatever other relations the same with() call lists. For example, Post::with('author') is not cached when Author is a plain model. Check this first when caching seems to stop working. Each eager-loaded relation still runs a query of its own, and that query is cached or not by its own rules. The check covers first-level relations only: in with('comments.replies') it checks Comment, but not Reply.
• A macro or custom Eloquent builder method called with a closure, or with an object that has no __toString(), also inside an array argument. The key cannot tell two such arguments apart, so the query runs live. Two kinds of object are keyed and cached: an enum passed directly, by its value or name, and a query builder or relation, by its own query. A value JSON cannot encode, such as NAN or a string that is not valid UTF-8, also runs live.

💾 Cache Drivers

📋 Requirements

• PHP 8.3+
• Laravel 12 or 13
• PHP 8.6 needs Laravel 13. Laravel 12 does not support PHP 8.6, because its session handler fails there. Laravel 13 fixes it.

📦 Installation

✨ The service provider is auto-discovered. No additional setup is required.

🚀 Getting Started

Add the Cachable trait to your models. The recommended approach is a base model that all other models extend:

Alternatively, extend the included CachedModel directly:

🎉 That's it — all Eloquent queries and eager-loaded relationships on these models are now cached and automatically invalidated.

⚠️ Note: You can cache the User model — the Cachable trait does not conflict with Laravel's authentication. Just avoid using cache cool-down periods on it, and ensure user updates always go through Eloquent (not raw DB::table() queries) so cache invalidation fires correctly.

🌍 Real-World Example

Consider a blog with posts, comments, and tags:

When a new comment is created, the cache for Post and Comment queries is automatically invalidated — no manual Cache::forget() calls needed. 🧹

⚙️ Configuration

Publish the config file:

This creates config/laravel-model-caching.php:

🔧 Environment Variables

📝 Note: The cache-prefix option is set directly in the config file (not via an environment variable). For dynamic prefixes (e.g. multi-tenant), use the per-model $cachePrefix property shown below.

💾 Custom Cache Store

To use a dedicated cache store for model caching, define one in config/cache.php and reference it:

☁️ DynamoDB Cache Store

DynamoDB is supported when your selected Laravel cache store uses the dynamodb driver:

Define the store in config/cache.php using the same fields Laravel documents for the DynamoDB cache driver:

If your application does not already require it, install the AWS SDK:

Enable DynamoDB TTL on the table's expires_at attribute as described in the Laravel cache docs.

How invalidation works on DynamoDB

Model invalidation on DynamoDB uses logical namespace versioning instead of native cache tags:

• modelCache:clear rotates a package-wide namespace key.
• Model and relationship invalidation rotate per-tag namespace keys.
• Cached query rows become unreachable immediately after the namespace changes.
• Old query rows are not deleted eagerly; DynamoDB removes them later through TTL.

This package does not issue table scans or destructive flushes on DynamoDB.

TTL guidance

Laravel's DynamoDB cache store writes forever() entries with a long-lived expiration instead of a truly unbounded item. In current Laravel releases that window is several years, which means stale DynamoDB rows are bounded but can linger for a long time after invalidation.

When a query resolves a TTL (see Cache Expiration (TTL)), its row gets that expiration instead. Laravel stops serving the row once the expiration passes, even before DynamoDB's TTL process deletes it.

Practical guidance:

• Always enable TTL on expires_at. Without it, DynamoDB never deletes expired or invalidated rows.
• Treat DynamoDB cache invalidation as logical invalidation first and physical cleanup later.
• Expect dead query rows to accumulate temporarily on write-heavy or high-churn models.
• Set a model cache TTL if you want invalidated query rows to become eligible for deletion sooner than Laravel's long-lived forever expiration.
• If you need faster physical cleanup than DynamoDB's TTL process gives, Redis is usually a better fit.

Operational notes

• Namespace control keys do not grow without bound. The package stores one global namespace key plus one key per normalized tag hash.
• Multi-tag invalidation is not atomic. Tags are rotated one at a time, so a crash in the middle of an invalidation can leave a partial namespace rotation. A later invalidation will still converge the cache to the latest version.
• Tag control keys hash the raw tag string, so long or punctuation-heavy tags are supported. Namespace collisions are limited to theoretical SHA-1 collisions.
• Cache cool-down metadata intentionally bypasses namespace versioning and stays on the raw cache store.

Troubleshooting

• modelCache:clear did not shrink the DynamoDB table: expected. The command makes old rows unreachable; it does not physically delete every row.
• Stale rows are still visible in DynamoDB: expected until TTL removes them.
• Frequent invalidations increase table size: expected on high-churn models because stale rows remain until TTL cleanup.
• Connection failures during reads: enable MODEL_CACHE_FALLBACK_TO_DB=true if you want query paths to fall back to the database during cache outages.
• Connection failures during modelCache:clear: the command now returns a non-zero exit code and prints the cache error instead of silently succeeding.

When to use DynamoDB vs Redis

• Use DynamoDB when you are already operating in AWS-native or serverless environments, want a managed cache store without running Redis, or need a simple multi-AZ DynamoDB-backed cache layer.
• Use Redis when you need lower latency, higher write churn, native tag support, or faster physical cleanup of invalidated cache data.

🏷️ Cache Key Prefix

For multi-tenant applications you can isolate cache entries per tenant. Set the prefix globally in config:

Or per-model via a property:

🔌 Multiple Database Connections

When use-database-keying is enabled (the default), cache keys automatically include the database connection and name. This keeps cache entries separate across connections without any extra configuration.

🚫 Disabling Cache

There are three ways to bypass caching:

1. Per-query (only affects this query chain, not subsequent queries):

2. Globally via environment:

3. For a block of code:

runDisabled() restores the setting when the closure returns or throws. Writes inside the closure do not invalidate anything, on purpose, and flushCache() does nothing there either. Invalidate after the closure returns:

💡 Tip: Use option 1 in seeders to avoid pulling stale cached data during reseeds.

❄️ Cache Cool-Down Period

In high-traffic scenarios (e.g. frequent comment submissions) you may want to prevent every write from immediately flushing the cache. Cool-down requires two steps:

Declare the default duration on the model (this alone does nothing — it just sets the value):

Activate the cool-down by calling withCacheCooldownSeconds() in your query. This writes the cool-down window into the cache store:

Once activated, writes during the cool-down window do not flush the cache. That covers model events, destroy(), pivot operations and every builder write in the Cache Invalidation table, increment() included. An explicit flushCache() or ModelCache::invalidate(), and a write through a different model class on the same table, still flush, because the window belongs to one model class. A model that declares $cachePrefix keeps its window under that prefix, and every write checks it there, pivot writes included, whatever prefix the other model declares.

After the window expires, the next cached read of the model flushes its cache and ends the window, even if no write comes first. A write after expiry flushes as well. 🔄

🛡️ Graceful Fallback

When enabled, if the cache backend (e.g. Redis) is unavailable the package logs a warning and falls back to querying the database directly — your application continues to function without caching rather than throwing an exception.

🧹 Cache Invalidation

Cache is automatically flushed when:

Builder writes flush with or without model events, so saveQuietly(), deleteQuietly() and withoutEvents() still invalidate. A write that skips the model's builder does not: DB::table(...), or a base query builder taken with toBase() or getQuery(). Call ModelCache::invalidate(Post::class) after one of those.

A flush does not wait for a database transaction to commit. A model write flushes on its Eloquent model event, which fires during the transaction, not on commit. Builder writes flush when their statement runs. A rollback does not undo a flush that already happened. Before the transaction ends, a read can cache rows that the commit or rollback then changes. Call ModelCache::invalidate(Post::class) after the transaction ends where that matters.

Cache tags are generated for the primary model, each eager-loaded relationship, joined tables, and morph-to target types, so only the relevant entries are invalidated. 🎯

A subquery passed to joinSub(), leftJoinSub(), rightJoinSub(), crossJoinSub(), straightJoinSub(), joinLateral(), leftJoinLateral(), fromSub(), whereIn(), orWhereIn(), whereNotIn() or orWhereNotIn() tags the table it reads as well. That includes calls by named argument and calls made inside a beforeQuery() callback. straightJoinSub() exists on Laravel 13 only.

For a model whose newBaseQueryBuilder() returns its own builder class, such as one from staudenmeir/laravel-cte, the tag is added for calls made through the model's query and for calls made inside a custom Eloquent builder's own methods. A subquery on such a model is not tagged in these cases:

• It is added to the base builder directly, through toBase(), getQuery() or a beforeQuery() callback.
• A custom Eloquent builder defines its own method with one of those names, calls it from another of its own methods, and that method does not call its parent. A builder that extends CachedBuilder and defines one of those methods without calling its parent is not tagged either.
• A custom Eloquent builder registers a local macro with one of those names and uses it inside the same method call.
• A custom Eloquent builder calls one of those methods from its own methods in a different letter case, such as whereIN(). Calls through the model's query are matched in any letter case.

After a write to that table, call ModelCache::invalidate() for the model that ran the query.

Joined tables include the pivot or intermediate table of a belongsToMany, morphToMany, hasManyThrough, or hasOneThrough relationship. Writing rows of that table through its own Cachable model therefore invalidates cached reads of the relationship.

An eager-loaded belongsToMany or morphToMany relationship tags its pivot table as well. A write to the pivot table through a Cachable model, or through a Cachable custom pivot class, therefore invalidates the query that eager-loads it. A many-to-many relationship eager-loaded through a morphTo, such as with('commentable.tags'), does not tag its pivot table. After a write to that pivot table outside the relationship, call ModelCache::invalidate() for the model that ran the query.

A pivot attach, detach, sync or updateExistingPivot through the relationship flushes the pivot table's tags itself. That holds with model events off, and when the related model does not use Cachable. An active cool-down window on either model holds that flush back.

🔗 BelongsToMany with Custom Pivot Models

Cache invalidation works for BelongsToMany relationships using custom pivot models (->using(CustomPivot::class)) as long as either the parent or the related model uses the Cachable trait.

🧹 Manual Cache Flushing

Artisan command — single model:

Artisan command — all models:

ℹ️ Scope of the full clear (no --model) — how much is removed depends on the cache driver:

• Redis (any cache-store prefix, including none) — only this package's entries and cool-down keys are deleted, found through the genealabs:laravel-model-caching: prefix on every tag and cool-down key it writes. Every other key is left intact, including the application's own entries under the same store prefix. This honors both the connection-level client prefix (database.redis.options.prefix) and the cache-store prefix, and works on the phpredis and Predis clients, single-node or cluster (CROSSSLOT-safe).
• DynamoDB — rotates a package-wide namespace key; no destructive table scan (see the DynamoDB section).
• Memcached, file, database, or array — these cannot scope a clear by prefix, so the entire cache store is flushed. Give the model cache a dedicated store (see the Custom Cache Store section) so a full clear never touches unrelated data.

🔧 Programmatic via Facade:

⏰ Cache Expiration (TTL)

Cached queries are stored indefinitely (rememberForever) by default and rely on automatic invalidation (see above) to stay fresh. This is the right choice for most applications — Redis and Memcached already manage stale-record eviction and memory usage on their own, so a blanket expiration setting isn't needed just to bound memory.

TTL exists as an opt-in safety net for the different problem of data written outside Eloquent entirely — a script, a direct SQL statement, another process — where nothing ever calls flushCache() or the modelCache:clear Artisan command. For a model like that, an expiration bounds how long a stale read can persist, without you having to remember to invalidate manually on every external write.

Global TTL, via config or environment variable, applies to every cachable model unless overridden:

Per-model TTL overrides the global value for one model. It also works with no global TTL set at all:

Valid values. Both levels follow the same rules:

Eager loads. A cached query result holds its eager-loaded models too. So the query takes the shortest TTL among its root model and every model it eager loads, nested eager loads (with('books.publisher')) and morphTo targets included. Each of those models contributes its own TTL, or the global TTL when it sets none. A model that contributes no TTL does not lower the result, and a model opted out with 0 does not force the whole query to cache forever. For example, Author::with('books')->get() expires after 3600 seconds when Book sets $cacheTtlSeconds = 3600, even though Author sets no TTL. A query with no TTL at any level keeps the forever-cache behavior unchanged.

Model::all() counts the relations in the model's default $with as eager loads, for both its TTL and its cache tags. So a cached Author::all() on an Author with protected $with = ['books'] takes Book's TTL, and an Eloquent write to a Book flushes it.

⬆️ Upgrade note: all() entries for models that declare $with now carry the tags of those relations. Those entries read cold once after you upgrade, then cache as before. No cache key or tag format changes.

Redis. An expired item leaves its entry behind in each cache tag's set, because Laravel's Redis tag sets do not expire with the items. Schedule Laravel's cache:prune-stale-tags Artisan command to remove those entries, for example hourly:

TTL and the cool-down period above solve different problems and can be used together: cool-down debounces how often a write flushes the cache, while TTL bounds how long a value can live when nothing flushes it at all.

🧪 Testing

In your test suite you can either disable model caching entirely or use the array cache driver:

🚫 Disable caching in tests:

✅ Use the array driver (useful for testing cache behavior itself):

👷 Queue Workers

The package has no special queue or Horizon integration. Cached queries inside queued jobs work the same as in HTTP requests. Cache invalidation triggered in a web request is immediately visible to queue workers (assuming a shared cache store like Redis). No additional configuration is needed.

🔍 Static Analysis (Larastan / PHPStan)

The package is compatible with Larastan at level 5 and above. With no annotation, the scopes disableCache() and withCacheCooldownSeconds() resolve anywhere in a query chain, and flushCache() resolves on a model instance.

A query chain that ends in a CachedBuilder method does not. Larastan types Post::where(...) as Eloquent's own builder, so ->flushCache() and ->cache() on it are reported as undefined methods. CachedBuilder is not generic, so naming it as your model's builder type trades these errors for others: Larastan then no longer finds the scopes above, and query results lose their model type. Use the calls that resolve instead:

Both are also safe with caching disabled, through MODEL_CACHE_ENABLED=false or inside runDisabled(): they do nothing there. A chained flushCache() or cache() is not. With caching disabled the model returns Eloquent's own builder, so the chained call throws BadMethodCallException. If you suppress the PHPStan error on a chain in your own project, that runtime case still applies.

The package's own source carries pre-existing level-5 findings, recorded in phpstan-baseline.neon so CI can enforce the level from here on. That baseline is internal to this repository and does not affect analysis of your project, because your own phpstan.neon decides which paths are analysed and vendor/ is not one of them.

🤝 Contributing

Contributions are welcome! 🎉 Please review the Contribution Guidelines and observe the Code of Conduct before submitting a pull request.

⬆️ Upgrading

For breaking changes and upgrade instructions between versions, see the Releases page on GitHub.

PHP 8.2 support is dropped

PHP 8.2 is no longer supported. Move to PHP 8.3 or later before you take this release. Composer refuses to install it on PHP 8.2.

The php constraint and the CI matrix now start at PHP 8.3. No cache key, cache tag, or runtime behaviour changes.

Laravel 11 support is dropped

Laravel 11 is no longer supported. Move to Laravel 12 or 13 before you take this release. Composer refuses to install it on Laravel 11.

Laravel 11 stopped receiving security fixes on 12 March 2026. This package supports the overlap of the actively maintained Laravel and PHP versions, so the illuminate/* constraints and the CI matrix now name Laravel 12 and 13 only.

This removes leftover compatibility rather than introducing a break. The 13.0 release already moved this package's major line. Laravel 11 was kept past it instead of being dropped at the time.

PHP 8.2 was unaffected by that release. No cache key, cache tag, or runtime behaviour changes.

Carbon bindings are re-keyed once

Every cached query holding a Carbon binding reads cold once after this upgrade. No action is needed. The old entries are not read again and expire on their own TTL.

A Carbon binding used to be written into the cache key by Carbon's own __toString(), because Carbon is Stringable. It is now formatted as Y-m-d-H-i-s, which is what DateTime and DateTimeImmutable bindings have always used.

The reason is that __toString() is governed by Carbon::setToStringFormat(), a process-global setter any application may call. One such call silently re-keyed every affected query, orphaning the existing entries with no error and a cache miss that looked like nothing at all. A Carbon release changing the default format had the same reach. Formatting the value ourselves removes that input from the key.

Only Carbon bindings are affected. No other cache key or cache tag changes.

🔐 Security

Please review the Security Policy for information on supported versions and how to report vulnerabilities.

📚 Further Reading

The test suite serves as living documentation — browse it for detailed examples of every supported query type, relationship pattern, and edge case. 📖

Built with ❤️ for the Laravel community using lots of ☕️ by Mike Bronner.

This is an MIT-licensed open-source project. Its continued development is made possible by the community. If you find it useful, please consider 💖 becoming a sponsor and ⭐ing it on GitHub.

🙏 Thank you to all contributors who have helped make this package better!