Download the PHP package mikebronner/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.2–8.5 and Laravel 11–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())

🚫 What Does Not Get Cached

• Lazy-loaded relationships — only eager-loaded (with()) relationships are cached. Use with() to benefit from caching.
• Queries using select() clauses — custom column selections bypass the cache.
• Queries inside transactions — cache is not automatically flushed when a transaction commits; call flushCache() manually if needed.
• inRandomOrder() queries — caching is automatically disabled since results should differ each time.

💾 Cache Drivers

📋 Requirements

• PHP 8.2+
• Laravel 11, 12, or 13

📦 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.

Practical guidance:

• Always enable TTL on expires_at.
• 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.
• If you need faster physical cleanup than Laravel's long-lived cache TTL allows, 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:

💡 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 will not flush the cache. After the window expires, the next write triggers a flush and re-warms the cache. 🔄

🛡️ 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:

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. 🎯

🔗 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 (with a cache-store prefix) — only the model-cache keys are scanned and deleted; other keys on the same connection are left intact. 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 un-prefixed Redis — 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) and rely on automatic invalidation (see above) to stay fresh. There is no per-query TTL option. If you need time-based expiry, use the cool-down period feature or flush the cache on a schedule via the Artisan command.

🧪 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. Because the Cachable trait wraps Eloquent's builder, PHPStan may report "undefined method" errors for methods like cache() or flushCache() on your models. To resolve these, add a @mixin annotation to your cached model:

If you use a custom Eloquent builder that gets wrapped by CachedBuilder, PHPStan cannot infer the custom methods from the CachedBuilder return type. Add a @return override annotation on your model's newEloquentBuilder() method, or add @mixin YourCustomBuilder to the model class.

The package ships with a phpstan-baseline.neon that suppresses internal analysis errors in the package's own test fixtures. These do not affect consumer projects.

🤝 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.

🔐 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!