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:

<?php
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 store
Tries 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.

<?php
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.

Back

User Authentication

Queues