genealabs / laravel-model-caching
Automatic caching for Eloquent models.
Installs: 3 506 065
Dependents: 32
Suggesters: 0
Security: 0
Stars: 2 257
Watchers: 41
Forks: 216
Open Issues: 47
Requires
- php: >=8.1
- genealabs/laravel-pivot-events: ^10.0|^11.0
- illuminate/cache: ^10.0|^11.0
- illuminate/config: ^10.0|^11.0
- illuminate/console: ^10.0|^11.0
- illuminate/container: ^10.0|^11.0
- illuminate/database: ^10.0|^11.0
- illuminate/http: ^10.0|^11.0
- illuminate/support: ^10.0|^11.0
Requires (Dev)
- doctrine/dbal: ^3.3
- fakerphp/faker: ^1.11
- laravel/legacy-factories: ^1.3
- laravel/nova: ^4.0
- orchestra/testbench: ^8.0|^9.0
- orchestra/testbench-browser-kit: ^8.0
- php-coveralls/php-coveralls: ^2.2
- phpunit/phpunit: ^10.0
- slevomat/coding-standard: ^7.0|^8.14
- squizlabs/php_codesniffer: ^3.6
- symfony/thanks: ^1.2
- dev-master
- 11.0.1
- 11.0.0
- 0.13.9
- 0.13.8
- 0.13.7
- 0.13.6
- 0.13.5
- 0.13.4
- 0.13.3
- 0.13.2
- 0.13.1
- 0.13.0
- 0.12.5
- 0.12.4
- 0.12.3
- 0.12.2
- 0.12.1
- 0.12.0
- 0.11.7
- 0.11.6
- 0.11.5
- 0.11.4
- 0.11.3
- 0.11.2
- 0.11.1
- 0.11.0
- 0.10.2
- 0.10.1
- 0.10.0
- 0.9.0
- 0.8.10
- 0.8.9
- 0.8.8
- 0.8.7
- 0.8.6
- 0.8.5
- 0.8.4
- 0.8.3
- 0.8.2
- 0.8.1
- 0.8.0
- 0.7.4
- 0.7.3
- 0.7.2
- 0.7.1
- 0.7.0
- 0.6.3
- 0.6.2
- 0.6.1
- 0.6.0
- 0.5.6
- 0.5.5
- 0.5.4
- 0.5.3
- 0.5.2
- 0.5.1
- 0.5.0
- 0.4.24
- 0.4.23
- 0.4.22
- 0.4.21
- 0.4.20
- 0.4.19
- 0.4.18
- 0.4.17
- 0.4.16
- 0.4.15
- 0.4.14
- 0.4.13
- 0.4.12
- 0.4.11
- 0.4.10
- 0.4.9
- 0.4.8
- 0.4.7
- 0.4.6
- 0.4.5
- 0.4.4
- 0.4.3
- 0.4.2
- 0.4.1
- 0.4.0
- 0.3.7
- 0.3.6
- 0.3.5
- 0.3.4
- 0.3.3
- 0.3.2
- 0.3.1
- 0.3.0
- 0.2.64
- 0.2.63
- 0.2.62
- 0.2.61
- 0.2.60
- 0.2.59
- 0.2.58
- 0.2.57
- 0.2.56
- 0.2.55
- 0.2.54
- 0.2.53
- 0.2.52
- 0.2.51
- 0.2.50
- 0.2.49
- 0.2.48
- 0.2.47
- 0.2.46
- 0.2.45
- 0.2.44
- 0.2.43
- 0.2.42
- 0.2.41
- 0.2.40
- 0.2.39
- 0.2.38
- 0.2.37
- 0.2.36
- 0.2.35
- 0.2.34
- 0.2.33
- 0.2.32
- 0.2.31
- 0.2.30
- 0.2.29
- 0.2.28
- 0.2.27
- 0.2.26
- 0.2.25
- 0.2.24
- 0.2.23
- 0.2.22
- 0.2.21
- 0.2.20
- 0.2.19
- 0.2.18
- 0.2.17
- 0.2.16
- 0.2.15
- 0.2.14
- 0.2.13
- 0.2.12
- 0.2.11
- 0.2.10
- 0.2.9
- 0.2.8
- 0.2.7
- 0.2.6
- 0.2.5
- 0.2.4
- 0.2.3
- 0.2.2
- 0.2.1
- 0.2.0
- 0.1.0
- dev-dependabot/composer/slevomat/coding-standard-tw-7.0
- dev-laravel-9
- dev-dependabot/add-v2-config-file
- dev-feature/implement-query-builder-override-fix
- dev-develop
- dev-feature/allow-flushing-by-database
- dev-feature/add-nova-tests
- dev-feature/update-to-laravel-6
- dev-feature/performance-improvements
- dev-laravel-5.5
- dev-laravel-5.6
This package is auto-updated.
Last update: 2024-10-15 13:55:57 UTC
README
Supporting This Package
This is an MIT-licensed open source project with its ongoing development made possible by the support of the community. If you'd like to support this, and our other packages, please consider becoming a sponsor.
We thank the following sponsors for their generosity, please take a moment to check them out:
Impetus
I created this package in response to a client project that had complex, nested
forms with many <select>
's that resulted in over 700 database queries on one
page. I needed a package that abstracted the caching process out of the model
for me, and one that would let me cache custom queries, as well as cache model
relationships. This package is an attempt to address those requirements.
Features
- automatic, self-invalidating relationship (only eager-loading) caching.
- automatic, self-invalidating model query caching.
- automatic use of cache tags for cache providers that support them (will flush entire cache for providers that don't).
Cache Drivers
This package is best suited for taggable cache drivers:
+ Redis + MemCached + APC + Array
It will not work with non-taggable drivers:
- Database - File - DynamoDB
Requirements
- PHP 7.3+
- Laravel 8.0+
- Please note that prior Laravel versions are not supported and the package - versions that are compatible with prior versions of Laravel contain bugs. - Please only use with the versions of Laravel noted above to be compatible.
Possible Package Conflicts
Any packages that override newEloquentModel()
from the Model
class will
likely conflict with this package. Of course, any packages that implement their
own Querybuilder class effectively circumvent this package, rendering them
incompatible.
The following are packages we have identified as conflicting:
- grimzy/laravel-mysql-spatial
- fico7489/laravel-pivot
- chelout/laravel-relationship-events
- spatie/laravel-query-builder
- dwightwatson/rememberable
- kalnoy/nestedset
Things That Don't Work Currently
The following items currently do no work with this package:
- caching of lazy-loaded relationships, see #127. Currently lazy-loaded belongs-to relationships are cached. Caching of other relationships is in the works. - using select() clauses in Eloquent queries, see #238 (work-around discussed in the issue) - using transactions. If you are using transactions, you will likely have to manually flush the cache, see [issue #305](https://github.com/GeneaLabs/laravel-model-caching/issues/305).
Installation
Be sure to not require a specific version of this package when requiring it:
composer require genealabs/laravel-model-caching
Gotchas If Using With Lumen
The following steps need to be figured out by you and implemented in your Lumen app. Googling for ways to do this provided various approaches to this.
- Register the package to load in Lumen:
$app->register(GeneaLabs\LaravelModelCaching\Providers\Service::class);
- Make sure your Lumen app can load config files.
- Publish this package's config file to the location your app loads config files from.
Upgrade Notes
0.6.0
The environment and config variables for disabling this package have changed.
-
If you have previously published the config file, publish it again, and adjust as necessary:
php artisan modelCache:publish --config
-
If you have disabled the package in your .env file, change the entry from
MODEL_CACHE_DISABLED=true
toMODEL_CACHE_ENABLED=false
.
0.5.0
The following implementations have changed (see the respective sections below):
- model-specific cache prefix
Configuration
Recommended (Optional) Custom Cache Store
If you would like to use a different cache store than the default one used by
your Laravel application, you may do so by setting the MODEL_CACHE_STORE
environment variable in your .env
file to the name of a cache store configured
in config/cache.php
(you can define any custom cache store based on your
specific needs there). For example:
MODEL_CACHE_STORE=redis2
Usage
For best performance a taggable cache provider is recommended (redis, memcached). While this is optional, using a non-taggable cache provider will mean that the entire cache is cleared each time a model is created, saved, updated, or deleted.
For ease of maintenance, I would recommend adding a BaseModel
model that
uses Cachable
, from which all your other models are extended. If you
don't want to do that, simply extend your models directly from CachedModel
.
Here's an example BaseModel
class:
<?php namespace App; use GeneaLabs\LaravelModelCaching\Traits\Cachable; abstract class BaseModel { use Cachable; // }
Multiple Database Connections
Thanks to @dtvmedia for suggestion this feature. This is actually a more robust solution than cache-prefixes.
Keeping keys separate for multiple database connections is automatically handled. This is especially important for multi-tenant applications, and of course any application using multiple database connections.
Optional Cache Key Prefix
Thanks to @lucian-dragomir for suggesting this feature! You can use cache key prefixing to keep cache entries separate for multi-tenant applications. For this it is recommended to add the Cachable trait to a base model, then set the cache key prefix config value there.
Here's is an example:
<?php namespace GeneaLabs\LaravelModelCaching\Tests\Fixtures; use GeneaLabs\LaravelModelCaching\Traits\Cachable; use Illuminate\Database\Eloquent\Model; use Illuminate\Database\Eloquent\Relations\BelongsTo; use Illuminate\Database\Eloquent\Relations\BelongsToMany; class BaseModel extends Model { use Cachable; protected $cachePrefix = "test-prefix"; }
The cache prefix can also be set in the configuration to prefix all cached models across the board:
'cache-prefix' => 'test-prefix',
Exception: User Model
I would not recommend caching the user model, as it is a special case, since it
extends Illuminate\Foundation\Auth\User
. Overriding that would break functionality.
Not only that, but it probably isn't a good idea to cache the user model anyway,
since you always want to pull the most up-to-date info on it.
Experimental: Cache Cool-down In Specific Models
In some instances, you may want to add a cache invalidation cool-down period. For example you might have a busy site where comments are submitted at a high rate, and you don't want every comment submission to invalidate the cache. While I don't necessarily recommend this, you might experiment it's effectiveness.
To use it, it must be enabled in the model (or base model if you want to use it on multiple or all models):
class MyModel extends Model { use Cachable; protected $cacheCooldownSeconds = 300; // 5 minutes // ... }
After that it can be implemented in queries:
(new Comment) ->withCacheCooldownSeconds(30) // override default cooldown seconds in model ->get();
or:
(new Comment) ->withCacheCooldownSeconds() // use default cooldown seconds in model ->get();
Disabling Caching of Queries
There are two methods by which model-caching can be disabled:
- Use
->disableCache()
in a query-by-query instance. - Set
MODEL_CACHE_ENABLED=false
in your.env
file. - If you only need to disable the cache for a block of code, or for non-
eloquent queries, this is probably the better option:
$result = app("model-cache")->runDisabled(function () { return (new MyModel)->get(); // or any other stuff you need to run with model-caching disabled });
Recommendation: use option #1 in all your seeder queries to avoid pulling in
cached information when reseeding multiple times.
You can disable a given query by using disableCache()
anywhere in the query chain. For example:
$results = $myModel->disableCache()->where('field', $value)->get();
Manual Flushing of Specific Model
You can flush the cache of a specific model using the following artisan command:
php artisan modelCache:clear --model=App\Model
This comes in handy when manually making updates to the database. You could also trigger this after making updates to the database from sources outside your Laravel app.
Summary
That's all you need to do. All model queries and relationships are now cached!
In testing this has optimized performance on some pages up to 900%! Most often you should see somewhere around 100% performance increase.
Commitment to Quality
During package development I try as best as possible to embrace good design and development practices, to help ensure that this package is as good as it can be. My checklist for package development includes:
- ✅ Achieve as close to 100% code coverage as possible using unit tests.
- ✅ Eliminate any issues identified by SensioLabs Insight and Scrutinizer.
- ✅ Be fully PSR1, PSR2, and PSR4 compliant.
- ✅ Include comprehensive documentation in README.md.
- ✅ Provide an up-to-date CHANGELOG.md which adheres to the format outlined at https://keepachangelog.com.
- ✅ Have no PHPMD or PHPCS warnings throughout all code.
Contributing
Please observe and respect all aspects of the included Code of Conduct https://github.com/GeneaLabs/laravel-model-caching/blob/master/CODE_OF_CONDUCT.md.
Reporting Issues
When reporting issues, please fill out the included template as completely as possible. Incomplete issues may be ignored or closed if there is not enough information included to be actionable.
Submitting Pull Requests
Please review the Contribution Guidelines https://github.com/GeneaLabs/laravel-model-caching/blob/master/CONTRIBUTING.md. Only PRs that meet all criterium will be accepted.
If you ❤️ open-source software, give the repos you use a ⭐️.
We have included the awesome symfony/thanks
composer package as a dev
dependency. Let your OS package maintainers know you appreciate them by starring
the packages you use. Simply run composer thanks after installing this package.
(And not to worry, since it's a dev-dependency it won't be installed in your
live environment.)