Cache and Locks
Configuration
To use MongoDB as a backend for Laravel Cache and Locks,
add a store configuration by specifying the mongodb
driver in config/cache.php
:
'stores' => [ 'mongodb' => [ 'driver' => 'mongodb', 'connection' => 'mongodb', 'collection' => 'cache', 'lock_connection' => 'mongodb', 'lock_collection' => 'cache_locks', 'lock_lottery' => [2, 100], 'lock_timeout' => 86400, ], ],
To configure the mongodb
database connection, see the Connections section.
The following table describes a list of cache and lock options and their default values:
Setting | Description |
---|---|
driver | Required. Specifies the lock driver to use. Must be mongodb . |
connection | Required. The database connection used to store cache items. It must be a mongodb connection. |
collection | Default cache . Name of the MongoDB collection to store cache items. |
lock_connection | Default to the cache connection . The database connection used to store locks. It must be a mongodb connection. |
lock_collection | Default cache_locks . Name of the MongoDB collection to store locks. |
lock_lottery | Default [2, 100] . Probability [chance, total] of pruning expired cache items. Set to [0, 0] to disable. |
lock_timeout | Default 86400 . Time-to-live of the locks, in seconds. |
Set Up Auto-Expiration Indexes
The TTL indexes integrated into MongoDB automatically
delete documents when they expire. Their use is optional with the mongodb
driver, but recommended. The indexes provide better performance by delegating the
deletion of expired documents to MongoDB instead of requiring the application to
perform this task.
Create the indexes with a migration that calls the
createTTLIndex()
methods provided by both the cache, and the lock stores:
use Illuminate\Database\Migrations\Migration; use Illuminate\Support\Facades\Cache; return new class extends Migration { public function up(): void { $store = Cache::store('mongodb'); $store->createTTLIndex(); $store->lock('')->createTTLIndex(); } };
Then run the migration:
php artisan migrate
Alternatively, you can create the index by using MongoDB Shell (mongosh
):
db.cache.createIndex( /* Field that holds the expiration date */ { expires_at: 1 }, /* Delay to remove items after expiration */ { expireAfterSeconds: 0 } )
If you use Locks, disable lock_lottery
by setting the probability to 0
:
'stores' => [ 'mongodb' => [ 'driver' => 'mongodb', 'connection' => 'mongodb', 'lock_lottery' => [0, 100], // Disabled ], ],
Using MongoDB Cache
The Laravel cache can be used to store any serializable data using the facade
Illuminate\Support\Facades\Cache
.
This example performs the following actions:
Gets the cache repository with the
mongodb
storeTries to read and return the cache item named
foo
If missing, calls the closure to compute the value, stores the value forever, and returns it
use Illuminate\Support\Facades\Cache; $value = Cache::store('mongodb')->get('foo', function () { return [1, 2, 3]; });
By default, cached objects do not expire. However, it is possible to define an expiry time, as shown in the following example:
Cache::store('mongodb')->set('foo', 'abc', '1 day');
Incrementing and decrementing a value is also supported if the value is
initialized before. The following example initializes the counter to 3
,
adds 5, and removes 2.
Cache::store('mongodb')->set('counter', 3); Cache::store('mongodb')->increment('counter', 5); Cache::store('mongodb')->decrement('counter', 2);
Note
The Laravel Integration supports incrementing and decrementing with integer and float values.
For more information about using the cache, see the Laravel Cache documentation.
Configuring MongoDB as the Default Cache
To use the mongodb
store by default, change the default store in
config/cache.php
.
return [ 'default' => env('CACHE_STORE', 'mongodb'), 'stores' => [ 'mongodb' => [ 'driver' => 'mongodb', 'connection' => 'mongodb', ], ], ];
Note
We have deliberately omitted all optional parameters in the previous example, so the default values are applied.
The CACHE_STORE
variable can be set in your environment or in
the .env
file. Update or remove it as follows:
CACHE_STORE=mongodb
Then you can use the Illuminate\Support\Facades\Cache
facade and
automatic injection:
use Illuminate\Support\Facades\Cache; Cache::get('foo', 5);
The following example shows how to use automatic injection of the cache manager by using the default store. The example creates a controller that increments a counter each time it is invoked.
namespace App\Http\Controllers; use App\Contracts\CacheManager; class CountController extends Controller { public function __construct( private CacheManager $cache, ) {} public function hit(): int { return $this->cache->increment('counter'); } }
Using MongoDB Lock
Atomic locks allow for the manipulation of distributed locks without worrying about race conditions. The following example implements an atomic lock:
use Illuminate\Support\Facades\Cache; $lock = Cache::store('mongodb')->lock('foo', 10); if ($lock->get()) { // Lock acquired for 10 seconds... $lock->release(); }
For more information on using locks, see the Laravel Locks documentation.