ℹ️ Skipped - page is already crawled
| Filter | Status | Condition | Details |
|---|---|---|---|
| HTTP status | PASS | download_http_code = 200 | HTTP 200 |
| Age cutoff | PASS | download_stamp > now() - 6 MONTH | 0 months ago |
| History drop | PASS | isNull(history_drop_reason) | No drop reason |
| Spam/ban | PASS | fh_dont_index != 1 AND ml_spam_score = 0 | ml_spam_score=0 |
| Canonical | FAIL | meta_canonical IS NULL OR = '' OR = src_unparsed | com,laravel!/docs/13.x/cache s443 |
| Property | Value |
|---|---|
| URL | https://laravel.com/docs/12.x/cache |
| Last Crawled | 2026-04-07 05:27:23 (4 hours ago) |
| First Indexed | 2025-02-24 16:47:35 (1 year ago) |
| HTTP Status Code | 200 |
| Meta Title | Cache | Laravel 12.x - The clean stack for Artisans and agents |
| Meta Description | Laravel is a PHP web application framework with expressive, elegant syntax. We've already laid the foundation — freeing you to create without sweating the small things. |
| Meta Canonical | com,laravel!/docs/13.x/cache s443 |
| Boilerpipe Text | WARNING
You're browsing the documentation for an old version of Laravel. Consider upgrading your project to
Laravel 13.x
.
Introduction
Configuration
Driver Prerequisites
Cache Usage
Obtaining a Cache Instance
Retrieving Items From the Cache
Storing Items in the Cache
Removing Items From the Cache
Cache Memoization
The Cache Helper
Cache Tags
Atomic Locks
Managing Locks
Managing Locks Across Processes
Concurrency Limiting
Cache Failover
Adding Custom Cache Drivers
Writing the Driver
Registering the Driver
Events
Introduction
Some of the data retrieval or processing tasks performed by your application could be CPU intensive or take several seconds to complete. When this is the case, it is common to cache the retrieved data for a time so it can be retrieved quickly on subsequent requests for the same data. The cached data is usually stored in a very fast data store such as
Memcached
or
Redis
.
Thankfully, Laravel provides an expressive, unified API for various cache backends, allowing you to take advantage of their blazing fast data retrieval and speed up your web application.
Configuration
Your application's cache configuration file is located at
config/cache.php
. In this file, you may specify which cache store you would like to be used by default throughout your application. Laravel supports popular caching backends like
Memcached
,
Redis
,
DynamoDB
, and relational databases out of the box. In addition, a file based cache driver is available, while
array
and
null
cache drivers provide convenient cache backends for your automated tests.
The cache configuration file also contains a variety of other options that you may review. By default, Laravel is configured to use the
database
cache driver, which stores the serialized, cached objects in your application's database.
Driver Prerequisites
Database
When using the
database
cache driver, you will need a database table to contain the cache data. Typically, this is included in Laravel's default
0001_01_01_000001_create_cache_table.php
database migration
; however, if your application does not contain this migration, you may use the
make:cache-table
Artisan command to create it:
1
php
artisan
make:cache-table
2
3
php
artisan
migrate
Memcached
Using the Memcached driver requires the
Memcached PECL package
to be installed. You may list all of your Memcached servers in the
config/cache.php
configuration file. This file already contains a
memcached.servers
entry to get you started:
1
'
memcached
'
=>
[
2
//
...
3
4
'
servers
'
=>
[
5
[
6
'
host
'
=>
env
(
'
MEMCACHED_HOST
'
,
'
127.0.0.1
'
),
7
'
port
'
=>
env
(
'
MEMCACHED_PORT
'
,
11211
),
8
'
weight
'
=>
100
,
9
],
10
],
11
],
If needed, you may set the
host
option to a UNIX socket path. If you do this, the
port
option should be set to
0
:
1
'
memcached
'
=>
[
2
//
...
3
4
'
servers
'
=>
[
5
[
6
'
host
'
=>
'
/var/run/memcached/memcached.sock
'
,
7
'
port
'
=>
0
,
8
'
weight
'
=>
100
9
],
10
],
11
],
Redis
Before using a Redis cache with Laravel, you will need to either install the PhpRedis PHP extension via PECL or install the
predis/predis
package (~2.0) via Composer.
Laravel Sail
already includes this extension. In addition, official Laravel application platforms such as
Laravel Cloud
and
Laravel Forge
have the PhpRedis extension installed by default.
For more information on configuring Redis, consult its
Laravel documentation page
.
DynamoDB
Before using the
DynamoDB
cache driver, you must create a DynamoDB table to store all of the cached data. Typically, this table should be named
cache
. However, you should name the table based on the value of the
stores.dynamodb.table
configuration value within the
cache
configuration file. The table name may also be set via the
DYNAMODB_CACHE_TABLE
environment variable.
This table should also have a string partition key with a name that corresponds to the value of the
stores.dynamodb.attributes.key
configuration item within your application's
cache
configuration file. By default, the partition key should be named
key
.
Typically, DynamoDB will not proactively remove expired items from a table. Therefore, you should
enable Time to Live (TTL)
on the table. When configuring the table's TTL settings, you should set the TTL attribute name to
expires_at
.
Next, install the AWS SDK so that your Laravel application can communicate with DynamoDB:
1
composer
require
aws/aws-sdk-php
In addition, you should ensure that values are provided for the DynamoDB cache store configuration options. Typically these options, such as
AWS_ACCESS_KEY_ID
and
AWS_SECRET_ACCESS_KEY
, should be defined in your application's
.env
configuration file:
1
'
dynamodb
'
=>
[
2
'
driver
'
=>
'
dynamodb
'
,
3
'
key
'
=>
env
(
'
AWS_ACCESS_KEY_ID
'
),
4
'
secret
'
=>
env
(
'
AWS_SECRET_ACCESS_KEY
'
),
5
'
region
'
=>
env
(
'
AWS_DEFAULT_REGION
'
,
'
us-east-1
'
),
6
'
table
'
=>
env
(
'
DYNAMODB_CACHE_TABLE
'
,
'
cache
'
),
7
'
endpoint
'
=>
env
(
'
DYNAMODB_ENDPOINT
'
),
8
],
MongoDB
If you are using MongoDB, a
mongodb
cache driver is provided by the official
mongodb/laravel-mongodb
package and can be configured using a
mongodb
database connection. MongoDB supports TTL indexes, which can be used to automatically clear expired cache items.
For more information on configuring MongoDB, please refer to the MongoDB
Cache and Locks documentation
.
Cache Usage
Obtaining a Cache Instance
To obtain a cache store instance, you may use the
Cache
facade, which is what we will use throughout this documentation. The
Cache
facade provides convenient, terse access to the underlying implementations of the Laravel cache contracts:
1
<?php
2
3
namespace
App\Http\Controllers;
4
5
use
Illuminate\Support\Facades\
Cache
;
6
7
class
UserController
extends
Controller
8
{
9
/**
10
* Show a list of all users of the application.
11
*/
12
public
function
index
()
:
array
13
{
14
$value
=
Cache
::
get
(
'
key
'
);
15
16
return
[
17
//
...
18
];
19
}
20
}
Accessing Multiple Cache Stores
Using the
Cache
facade, you may access various cache stores via the
store
method. The key passed to the
store
method should correspond to one of the stores listed in the
stores
configuration array in your
cache
configuration file:
1
$value
=
Cache
::
store
(
'
file
'
)
->
get
(
'
foo
'
);
2
3
Cache
::
store
(
'
redis
'
)
->
put
(
'
bar
'
,
'
baz
'
,
600
);
//
10 Minutes
Retrieving Items From the Cache
The
Cache
facade's
get
method is used to retrieve items from the cache. If the item does not exist in the cache,
null
will be returned. If you wish, you may pass a second argument to the
get
method specifying the default value you wish to be returned if the item doesn't exist:
1
$value
=
Cache
::
get
(
'
key
'
);
2
3
$value
=
Cache
::
get
(
'
key
'
,
'
default
'
);
You may even pass a closure as the default value. The result of the closure will be returned if the specified item does not exist in the cache. Passing a closure allows you to defer the retrieval of default values from a database or other external service:
1
$value
=
Cache
::
get
(
'
key
'
,
function
()
{
2
return
DB
::
table
(
/*
...
*/
)
->
get
();
3
});
Determining Item Existence
The
has
method may be used to determine if an item exists in the cache. This method will also return
false
if the item exists but its value is
null
:
1
if
(
Cache
::
has
(
'
key
'
)) {
2
//
...
3
}
Incrementing / Decrementing Values
The
increment
and
decrement
methods may be used to adjust the value of integer items in the cache. Both of these methods accept an optional second argument indicating the amount by which to increment or decrement the item's value:
1
//
Initialize the value if it does not exist...
2
Cache
::
add
(
'
key
'
,
0
,
now
()
->
plus
(hours:
4
));
3
4
//
Increment or decrement the value...
5
Cache
::
increment
(
'
key
'
);
6
Cache
::
increment
(
'
key
'
,
$amount
);
7
Cache
::
decrement
(
'
key
'
);
8
Cache
::
decrement
(
'
key
'
,
$amount
);
Retrieve and Store
Sometimes you may wish to retrieve an item from the cache, but also store a default value if the requested item doesn't exist. For example, you may wish to retrieve all users from the cache or, if they don't exist, retrieve them from the database and add them to the cache. You may do this using the
Cache::remember
method:
1
$value
=
Cache
::
remember
(
'
users
'
,
$seconds
,
function
()
{
2
return
DB
::
table
(
'
users
'
)
->
get
();
3
});
If the item does not exist in the cache, the closure passed to the
remember
method will be executed and its result will be placed in the cache.
You may use the
rememberForever
method to retrieve an item from the cache or store it forever if it does not exist:
1
$value
=
Cache
::
rememberForever
(
'
users
'
,
function
()
{
2
return
DB
::
table
(
'
users
'
)
->
get
();
3
});
Stale While Revalidate
When using the
Cache::remember
method, some users may experience slow response times if the cached value has expired. For certain types of data, it can be useful to allow partially stale data to be served while the cached value is recalculated in the background, preventing some users from experiencing slow response times while cached values are calculated. This is often referred to as the "stale-while-revalidate" pattern, and the
Cache::flexible
method provides an implementation of this pattern.
The flexible method accepts an array that specifies how long the cached value is considered "fresh" and when it becomes "stale". The first value in the array represents the number of seconds the cache is considered fresh, while the second value defines how long it can be served as stale data before recalculation is necessary.
If a request is made within the fresh period (before the first value), the cache is returned immediately without recalculation. If a request is made during the stale period (between the two values), the stale value is served to the user, and a
deferred function
is registered to refresh the cached value after the response is sent to the user. If a request is made after the second value, the cache is considered expired, and the value is recalculated immediately, which may result in a slower response for the user:
1
$value
=
Cache
::
flexible
(
'
users
'
, [
5
,
10
],
function
()
{
2
return
DB
::
table
(
'
users
'
)
->
get
();
3
});
Retrieve and Delete
If you need to retrieve an item from the cache and then delete the item, you may use the
pull
method. Like the
get
method,
null
will be returned if the item does not exist in the cache:
1
$value
=
Cache
::
pull
(
'
key
'
);
2
3
$value
=
Cache
::
pull
(
'
key
'
,
'
default
'
);
Storing Items in the Cache
You may use the
put
method on the
Cache
facade to store items in the cache:
1
Cache
::
put
(
'
key
'
,
'
value
'
,
$seconds
=
10
);
If the storage time is not passed to the
put
method, the item will be stored indefinitely:
1
Cache
::
put
(
'
key
'
,
'
value
'
);
Instead of passing the number of seconds as an integer, you may also pass a
DateTime
instance representing the desired expiration time of the cached item:
1
Cache
::
put
(
'
key
'
,
'
value
'
,
now
()
->
plus
(minutes:
10
));
Store if Not Present
The
add
method will only add the item to the cache if it does not already exist in the cache store. The method will return
true
if the item is actually added to the cache. Otherwise, the method will return
false
. The
add
method is an atomic operation:
1
Cache
::
add
(
'
key
'
,
'
value
'
,
$seconds
);
Storing Items Forever
The
forever
method may be used to store an item in the cache permanently. Since these items will not expire, they must be manually removed from the cache using the
forget
method:
1
Cache
::
forever
(
'
key
'
,
'
value
'
);
If you are using the Memcached driver, items that are stored "forever" may be removed when the cache reaches its size limit.
Removing Items From the Cache
You may remove items from the cache using the
forget
method:
1
Cache
::
forget
(
'
key
'
);
You may also remove items by providing a zero or negative number of expiration seconds:
1
Cache
::
put
(
'
key
'
,
'
value
'
,
0
);
2
3
Cache
::
put
(
'
key
'
,
'
value
'
,
-
5
);
You may clear the entire cache using the
flush
method:
1
Cache
::
flush
();
Flushing the cache does not respect your configured cache "prefix" and will remove all entries from the cache. Consider this carefully when clearing a cache which is shared by other applications.
Cache Memoization
Laravel's
memo
cache driver allows you to temporarily store resolved cache values in memory during a single request or job execution. This prevents repeated cache hits within the same execution, significantly improving performance.
To use the memoized cache, invoke the
memo
method:
1
use
Illuminate\Support\Facades\
Cache
;
2
3
$value
=
Cache
::
memo
()
->
get
(
'
key
'
);
The
memo
method optionally accepts the name of a cache store, which specifies the underlying cache store the memoized driver will decorate:
1
//
Using the default cache store...
2
$value
=
Cache
::
memo
()
->
get
(
'
key
'
);
3
4
//
Using the Redis cache store...
5
$value
=
Cache
::
memo
(
'
redis
'
)
->
get
(
'
key
'
);
The first
get
call for a given key retrieves the value from your cache store, but subsequent calls within the same request or job will retrieve the value from memory:
1
//
Hits the cache...
2
$value
=
Cache
::
memo
()
->
get
(
'
key
'
);
3
4
//
Does not hit the cache, returns memoized value...
5
$value
=
Cache
::
memo
()
->
get
(
'
key
'
);
When calling methods that modify cache values (such as
put
,
increment
,
remember
, etc.), the memoized cache automatically forgets the memoized value and delegates the mutating method call to the underlying cache store:
1
Cache
::
memo
()
->
put
(
'
name
'
,
'
Taylor
'
);
//
Writes to underlying cache...
2
Cache
::
memo
()
->
get
(
'
name
'
);
//
Hits underlying cache...
3
Cache
::
memo
()
->
get
(
'
name
'
);
//
Memoized, does not hit cache...
4
5
Cache
::
memo
()
->
put
(
'
name
'
,
'
Tim
'
);
//
Forgets memoized value, writes new value...
6
Cache
::
memo
()
->
get
(
'
name
'
);
//
Hits underlying cache again...
The Cache Helper
In addition to using the
Cache
facade, you may also use the global
cache
function to retrieve and store data via the cache. When the
cache
function is called with a single, string argument, it will return the value of the given key:
1
$value
=
cache
(
'
key
'
);
If you provide an array of key / value pairs and an expiration time to the function, it will store values in the cache for the specified duration:
1
cache
([
'
key
'
=>
'
value
'
],
$
seconds
);
2
3
cache
([
'
key
'
=>
'
value
'
],
now
()
->
plus
(
minutes
:
10
));
When the
cache
function is called without any arguments, it returns an instance of the
Illuminate\Contracts\Cache\Factory
implementation, allowing you to call other caching methods:
1
cache
()
->
remember
(
'
users
'
,
$seconds
,
function
()
{
2
return
DB
::
table
(
'
users
'
)
->
get
();
3
});
When testing calls to the global
cache
function, you may use the
Cache::shouldReceive
method just as if you were
testing the facade
.
Cache tags are not supported when using the
file
,
dynamodb
, or
database
cache drivers.
Storing Tagged Cache Items
Cache tags allow you to tag related items in the cache and then flush all cached values that have been assigned a given tag. You may access a tagged cache by passing in an ordered array of tag names. For example, let's access a tagged cache and
put
a value into the cache:
1
use
Illuminate\Support\Facades\
Cache
;
2
3
Cache
::
tags
([
'
people
'
,
'
artists
'
])
->
put
(
'
John
'
,
$john
,
$seconds
);
4
Cache
::
tags
([
'
people
'
,
'
authors
'
])
->
put
(
'
Anne
'
,
$anne
,
$seconds
);
Accessing Tagged Cache Items
Items stored via tags may not be accessed without also providing the tags that were used to store the value. To retrieve a tagged cache item, pass the same ordered list of tags to the
tags
method, then call the
get
method with the key you wish to retrieve:
1
$john
=
Cache
::
tags
([
'
people
'
,
'
artists
'
])
->
get
(
'
John
'
);
2
3
$anne
=
Cache
::
tags
([
'
people
'
,
'
authors
'
])
->
get
(
'
Anne
'
);
Removing Tagged Cache Items
You may flush all items that are assigned a tag or list of tags. For example, the following code would remove all caches tagged with either
people
,
authors
, or both. So, both
Anne
and
John
would be removed from the cache:
1
Cache
::
tags
([
'
people
'
,
'
authors
'
])
->
flush
();
In contrast, the code below would remove only cached values tagged with
authors
, so
Anne
would be removed, but not
John
:
1
Cache
::
tags
(
'
authors
'
)
->
flush
();
Atomic Locks
To utilize this feature, your application must be using the
memcached
,
redis
,
dynamodb
,
database
,
file
, or
array
cache driver as your application's default cache driver. In addition, all servers must be communicating with the same central cache server.
Managing Locks
Atomic locks allow for the manipulation of distributed locks without worrying about race conditions. For example,
Laravel Cloud
uses atomic locks to ensure that only one remote task is being executed on a server at a time. You may create and manage locks using the
Cache::lock
method:
1
use
Illuminate\Support\Facades\
Cache
;
2
3
$lock
=
Cache
::
lock
(
'
foo
'
,
10
);
4
5
if
(
$lock
->
get
()) {
6
//
Lock acquired for 10 seconds...
7
8
$lock
->
release
();
9
}
The
get
method also accepts a closure. After the closure is executed, Laravel will automatically release the lock:
1
Cache
::
lock
(
'
foo
'
,
10
)
->
get
(
function
()
{
2
//
Lock acquired for 10 seconds and automatically released...
3
});
If the lock is not available at the moment you request it, you may instruct Laravel to wait for a specified number of seconds. If the lock cannot be acquired within the specified time limit, an
Illuminate\Contracts\Cache\LockTimeoutException
will be thrown:
1
use
Illuminate\Contracts\Cache\
LockTimeoutException
;
2
3
$lock
=
Cache
::
lock
(
'
foo
'
,
10
);
4
5
try
{
6
$lock
->
block
(
5
);
7
8
//
Lock acquired after waiting a maximum of 5 seconds...
9
}
catch
(
LockTimeoutException
$e
)
{
10
//
Unable to acquire lock...
11
}
finally
{
12
$lock
->
release
();
13
}
The example above may be simplified by passing a closure to the
block
method. When a closure is passed to this method, Laravel will attempt to acquire the lock for the specified number of seconds and will automatically release the lock once the closure has been executed:
1
Cache
::
lock
(
'
foo
'
,
10
)
->
block
(
5
,
function
()
{
2
//
Lock acquired for 10 seconds after waiting a maximum of 5 seconds...
3
});
Managing Locks Across Processes
Sometimes, you may wish to acquire a lock in one process and release it in another process. For example, you may acquire a lock during a web request and wish to release the lock at the end of a queued job that is triggered by that request. In this scenario, you should pass the lock's scoped "owner token" to the queued job so that the job can re-instantiate the lock using the given token.
In the example below, we will dispatch a queued job if a lock is successfully acquired. In addition, we will pass the lock's owner token to the queued job via the lock's
owner
method:
1
$podcast
=
Podcast
::
find
(
$id
);
2
3
$lock
=
Cache
::
lock
(
'
processing
'
,
120
);
4
5
if
(
$lock
->
get
()) {
6
ProcessPodcast
::
dispatch
(
$podcast
,
$lock
->
owner
());
7
}
Within our application's
ProcessPodcast
job, we can restore and release the lock using the owner token:
1
Cache
::
restoreLock
(
'
processing
'
,
$this
->owner
)
->
release
();
If you would like to release a lock without respecting its current owner, you may use the
forceRelease
method:
1
Cache
::
lock
(
'
processing
'
)
->
forceRelease
();
Concurrency Limiting
Laravel's atomic lock functionality also provides a few ways to limit concurrent execution of closures. Use
withoutOverlapping
when you want to allow only one running instance across your infrastructure:
1
Cache
::
withoutOverlapping
(
'
foo
'
,
function
()
{
2
//
Lock acquired after waiting a maximum of 10 seconds...
3
});
By default, the lock is held until the closure finishes executing, and the method waits up to 10 seconds to acquire the lock. You may customize these values using additional arguments:
1
Cache
::
withoutOverlapping
(
'
foo
'
,
function
()
{
2
//
Lock acquired for 120 seconds after waiting a maximum of 5 seconds...
3
}, lockFor:
120
, waitFor:
5
);
If the lock cannot be acquired within the specified wait time, an
Illuminate\Contracts\Cache\LockTimeoutException
will be thrown.
If you want controlled parallelism, use the
funnel
method to set a maximum number of concurrent executions. The
funnel
method works with any cache driver that supports locks:
1
Cache
::
funnel
(
'
foo
'
)
2
->
limit
(
3
)
3
->
releaseAfter
(
60
)
4
->
block
(
10
)
5
->
then
(
function
()
{
6
//
Concurrency lock acquired...
7
},
function
()
{
8
//
Could not acquire concurrency lock...
9
});
The
funnel
key identifies the resource being limited. The
limit
method defines the maximum concurrent executions. The
releaseAfter
method sets a safety timeout in seconds before an acquired slot is automatically released. The
block
method sets how many seconds to wait for an available slot.
If you prefer to handle the timeout via exceptions instead of providing a failure closure, you may omit the second closure. An
Illuminate\Cache\Limiters\LimiterTimeoutException
will be thrown if the lock cannot be acquired within the specified wait time:
1
use
Illuminate\Cache\Limiters\
LimiterTimeoutException
;
2
3
try
{
4
Cache
::
funnel
(
'
foo
'
)
5
->
limit
(
3
)
6
->
releaseAfter
(
60
)
7
->
block
(
10
)
8
->
then
(
function
()
{
9
//
Concurrency lock acquired...
10
});
11
}
catch
(
LimiterTimeoutException
$e
)
{
12
//
Unable to acquire concurrency lock...
13
}
If you would like to use a specific cache store for the concurrency limiter, you may invoke the
funnel
method on the desired store:
1
Cache
::
store
(
'
redis
'
)
->
funnel
(
'
foo
'
)
2
->
limit
(
3
)
3
->
block
(
10
)
4
->
then
(
function
()
{
5
//
Concurrency lock acquired using the "redis" store...
6
});
The
funnel
method requires the cache store to implement the
Illuminate\Contracts\Cache\LockProvider
interface. If you attempt to use
funnel
with a cache store that does not support locks, a
BadMethodCallException
will be thrown.
Cache Failover
The
failover
cache driver provides automatic failover functionality when interacting with the cache. If the primary cache store of the
failover
store fails for any reason, Laravel will automatically attempt to use the next configured store in the list. This is particularly useful for ensuring high availability in production environments where cache reliability is critical.
To configure a failover cache store, specify the
failover
driver and provide an array of store names to attempt in order. By default, Laravel includes an example failover configuration in your application's
config/cache.php
configuration file:
1
'
failover
'
=>
[
2
'
driver
'
=>
'
failover
'
,
3
'
stores
'
=>
[
4
'
database
'
,
5
'
array
'
,
6
],
7
],
Once you have configured a store that uses the
failover
driver, you will need to set the failover store as your default cache store in your application's
.env
file to make use of the failover functionality:
1
CACHE_STORE
=failover
When a cache store operation fails and failover is activated, Laravel will dispatch the
Illuminate\Cache\Events\CacheFailedOver
event, allowing you to report or log that a cache store has failed.
Adding Custom Cache Drivers
Writing the Driver
To create our custom cache driver, we first need to implement the
Illuminate\Contracts\Cache\Store
contract
. So, a MongoDB cache implementation might look something like this:
1
<?php
2
3
namespace
App\Extensions;
4
5
use
Illuminate\Contracts\Cache\
Store
;
6
7
class
MongoStore
implements
Store
8
{
9
public
function
get
(
$key
)
{}
10
public
function
many
(
array
$keys
)
{}
11
public
function
put
(
$key
,
$value
,
$seconds
)
{}
12
public
function
putMany
(
array
$values
,
$seconds
)
{}
13
public
function
increment
(
$key
,
$value
=
1
)
{}
14
public
function
decrement
(
$key
,
$value
=
1
)
{}
15
public
function
forever
(
$key
,
$value
)
{}
16
public
function
forget
(
$key
)
{}
17
public
function
flush
()
{}
18
public
function
getPrefix
()
{}
19
}
We just need to implement each of these methods using a MongoDB connection. For an example of how to implement each of these methods, take a look at the
Illuminate\Cache\MemcachedStore
in the
Laravel framework source code
. Once our implementation is complete, we can finish our custom driver registration by calling the
Cache
facade's
extend
method:
1
Cache
::
extend
(
'
mongo
'
,
function
(
Application
$app
)
{
2
return
Cache
::
repository
(
new
MongoStore
);
3
});
If you're wondering where to put your custom cache driver code, you could create an
Extensions
namespace within your
app
directory. However, keep in mind that Laravel does not have a rigid application structure and you are free to organize your application according to your preferences.
Registering the Driver
To register the custom cache driver with Laravel, we will use the
extend
method on the
Cache
facade. Since other service providers may attempt to read cached values within their
boot
method, we will register our custom driver within a
booting
callback. By using the
booting
callback, we can ensure that the custom driver is registered just before the
boot
method is called on our application's service providers but after the
register
method is called on all of the service providers. We will register our
booting
callback within the
register
method of our application's
App\Providers\AppServiceProvider
class:
1
<?php
2
3
namespace
App\Providers;
4
5
use
App\Extensions\
MongoStore
;
6
use
Illuminate\Contracts\Foundation\
Application
;
7
use
Illuminate\Support\Facades\
Cache
;
8
use
Illuminate\Support\
ServiceProvider
;
9
10
class
AppServiceProvider
extends
ServiceProvider
11
{
12
/**
13
* Register any application services.
14
*/
15
public
function
register
()
:
void
16
{
17
$this
->app->
booting
(
function
()
{
18
Cache
::
extend
(
'
mongo
'
,
function
(
Application
$app
)
{
19
return
Cache
::
repository
(
new
MongoStore
);
20
});
21
});
22
}
23
24
/**
25
* Bootstrap any application services.
26
*/
27
public
function
boot
()
:
void
28
{
29
//
...
30
}
31
}
The first argument passed to the
extend
method is the name of the driver. This will correspond to your
driver
option in the
config/cache.php
configuration file. The second argument is a closure that should return an
Illuminate\Cache\Repository
instance. The closure will be passed an
$app
instance, which is an instance of the
service container
.
Once your extension is registered, update the
CACHE_STORE
environment variable or
default
option within your application's
config/cache.php
configuration file to the name of your extension.
Events
To execute code on every cache operation, you may listen for various
events
dispatched by the cache:
Event Name
Illuminate\Cache\Events\CacheFlushed
Illuminate\Cache\Events\CacheFlushing
Illuminate\Cache\Events\CacheHit
Illuminate\Cache\Events\CacheMissed
Illuminate\Cache\Events\ForgettingKey
Illuminate\Cache\Events\KeyForgetFailed
Illuminate\Cache\Events\KeyForgotten
Illuminate\Cache\Events\KeyWriteFailed
Illuminate\Cache\Events\KeyWritten
Illuminate\Cache\Events\RetrievingKey
Illuminate\Cache\Events\RetrievingManyKeys
Illuminate\Cache\Events\WritingKey
Illuminate\Cache\Events\WritingManyKeys
To increase performance, you may disable cache events by setting the
events
configuration option to
false
for a given cache store in your application's
config/cache.php
configuration file:
1
'
database
'
=>
[
2
'
driver
'
=>
'
database
'
,
3
//
...
4
'
events
'
=>
false
,
5
], |
| Markdown | - [Home](https://laravel.com/)
Search
```K`
⌘K
Switch to light mode
[Skip to content](https://laravel.com/docs/12.x/cache#main-content)
- ## Prologue
- [Release Notes](https://laravel.com/docs/12.x/releases)
- [Upgrade Guide](https://laravel.com/docs/12.x/upgrade)
- [Contribution Guide](https://laravel.com/docs/12.x/contributions)
- ## Getting Started
- [Installation](https://laravel.com/docs/12.x/installation)
- [Configuration](https://laravel.com/docs/12.x/configuration)
- [Agentic Development](https://laravel.com/docs/12.x/ai)
- [Directory Structure](https://laravel.com/docs/12.x/structure)
- [Frontend](https://laravel.com/docs/12.x/frontend)
- [Starter Kits](https://laravel.com/docs/12.x/starter-kits)
- [Deployment](https://laravel.com/docs/12.x/deployment)
- ## Architecture Concepts
- [Request Lifecycle](https://laravel.com/docs/12.x/lifecycle)
- [Service Container](https://laravel.com/docs/12.x/container)
- [Service Providers](https://laravel.com/docs/12.x/providers)
- [Facades](https://laravel.com/docs/12.x/facades)
- ## The Basics
- [Routing](https://laravel.com/docs/12.x/routing)
- [Middleware](https://laravel.com/docs/12.x/middleware)
- [CSRF Protection](https://laravel.com/docs/12.x/csrf)
- [Controllers](https://laravel.com/docs/12.x/controllers)
- [Requests](https://laravel.com/docs/12.x/requests)
- [Responses](https://laravel.com/docs/12.x/responses)
- [Views](https://laravel.com/docs/12.x/views)
- [Blade Templates](https://laravel.com/docs/12.x/blade)
- [Asset Bundling](https://laravel.com/docs/12.x/vite)
- [URL Generation](https://laravel.com/docs/12.x/urls)
- [Session](https://laravel.com/docs/12.x/session)
- [Validation](https://laravel.com/docs/12.x/validation)
- [Error Handling](https://laravel.com/docs/12.x/errors)
- [Logging](https://laravel.com/docs/12.x/logging)
- ## Digging Deeper
- [Artisan Console](https://laravel.com/docs/12.x/artisan)
- [Broadcasting](https://laravel.com/docs/12.x/broadcasting)
- [Cache](https://laravel.com/docs/12.x/cache)
- [Collections](https://laravel.com/docs/12.x/collections)
- [Concurrency](https://laravel.com/docs/12.x/concurrency)
- [Context](https://laravel.com/docs/12.x/context)
- [Contracts](https://laravel.com/docs/12.x/contracts)
- [Events](https://laravel.com/docs/12.x/events)
- [File Storage](https://laravel.com/docs/12.x/filesystem)
- [Helpers](https://laravel.com/docs/12.x/helpers)
- [HTTP Client](https://laravel.com/docs/12.x/http-client)
- [Localization](https://laravel.com/docs/12.x/localization)
- [Mail](https://laravel.com/docs/12.x/mail)
- [Notifications](https://laravel.com/docs/12.x/notifications)
- [Package Development](https://laravel.com/docs/12.x/packages)
- [Processes](https://laravel.com/docs/12.x/processes)
- [Queues](https://laravel.com/docs/12.x/queues)
- [Rate Limiting](https://laravel.com/docs/12.x/rate-limiting)
- [Search](https://laravel.com/docs/12.x/search)
- [Strings](https://laravel.com/docs/12.x/strings)
- [Task Scheduling](https://laravel.com/docs/12.x/scheduling)
- ## Security
- [Authentication](https://laravel.com/docs/12.x/authentication)
- [Authorization](https://laravel.com/docs/12.x/authorization)
- [Email Verification](https://laravel.com/docs/12.x/verification)
- [Encryption](https://laravel.com/docs/12.x/encryption)
- [Hashing](https://laravel.com/docs/12.x/hashing)
- [Password Reset](https://laravel.com/docs/12.x/passwords)
- ## Database
- [Getting Started](https://laravel.com/docs/12.x/database)
- [Query Builder](https://laravel.com/docs/12.x/queries)
- [Pagination](https://laravel.com/docs/12.x/pagination)
- [Migrations](https://laravel.com/docs/12.x/migrations)
- [Seeding](https://laravel.com/docs/12.x/seeding)
- [Redis](https://laravel.com/docs/12.x/redis)
- [MongoDB](https://laravel.com/docs/12.x/mongodb)
- ## Eloquent ORM
- [Getting Started](https://laravel.com/docs/12.x/eloquent)
- [Relationships](https://laravel.com/docs/12.x/eloquent-relationships)
- [Collections](https://laravel.com/docs/12.x/eloquent-collections)
- [Mutators / Casts](https://laravel.com/docs/12.x/eloquent-mutators)
- [API Resources](https://laravel.com/docs/12.x/eloquent-resources)
- [Serialization](https://laravel.com/docs/12.x/eloquent-serialization)
- [Factories](https://laravel.com/docs/12.x/eloquent-factories)
- ## AI
- [AI SDK](https://laravel.com/docs/12.x/ai-sdk)
- [MCP](https://laravel.com/docs/12.x/mcp)
- [Boost](https://laravel.com/docs/12.x/boost)
- ## Testing
- [Getting Started](https://laravel.com/docs/12.x/testing)
- [HTTP Tests](https://laravel.com/docs/12.x/http-tests)
- [Console Tests](https://laravel.com/docs/12.x/console-tests)
- [Browser Tests](https://laravel.com/docs/12.x/dusk)
- [Database](https://laravel.com/docs/12.x/database-testing)
- [Mocking](https://laravel.com/docs/12.x/mocking)
- ## Packages
- [Cashier (Stripe)](https://laravel.com/docs/12.x/billing)
- [Cashier (Paddle)](https://laravel.com/docs/12.x/cashier-paddle)
- [Dusk](https://laravel.com/docs/12.x/dusk)
- [Envoy](https://laravel.com/docs/12.x/envoy)
- [Fortify](https://laravel.com/docs/12.x/fortify)
- [Folio](https://laravel.com/docs/12.x/folio)
- [Homestead](https://laravel.com/docs/12.x/homestead)
- [Horizon](https://laravel.com/docs/12.x/horizon)
- [Mix](https://laravel.com/docs/12.x/mix)
- [Octane](https://laravel.com/docs/12.x/octane)
- [Passport](https://laravel.com/docs/12.x/passport)
- [Pennant](https://laravel.com/docs/12.x/pennant)
- [Pint](https://laravel.com/docs/12.x/pint)
- [Precognition](https://laravel.com/docs/12.x/precognition)
- [Prompts](https://laravel.com/docs/12.x/prompts)
- [Pulse](https://laravel.com/docs/12.x/pulse)
- [Reverb](https://laravel.com/docs/12.x/reverb)
- [Sail](https://laravel.com/docs/12.x/sail)
- [Sanctum](https://laravel.com/docs/12.x/sanctum)
- [Scout](https://laravel.com/docs/12.x/scout)
- [Socialite](https://laravel.com/docs/12.x/socialite)
- [Telescope](https://laravel.com/docs/12.x/telescope)
- [Valet](https://laravel.com/docs/12.x/valet)
- ## [API Documentation](https://api.laravel.com/docs/12.x/index.html)
- ## [Changelog](https://laravel.com/docs/changelog)
> **WARNING** You're browsing the documentation for an old version of Laravel. Consider upgrading your project to [Laravel 13.x](https://laravel.com/docs/13.x/cache).
# Cache
- [Introduction](https://laravel.com/docs/12.x/cache#introduction)
- [Configuration](https://laravel.com/docs/12.x/cache#configuration)
- [Driver Prerequisites](https://laravel.com/docs/12.x/cache#driver-prerequisites)
- [Cache Usage](https://laravel.com/docs/12.x/cache#cache-usage)
- [Obtaining a Cache Instance](https://laravel.com/docs/12.x/cache#obtaining-a-cache-instance)
- [Retrieving Items From the Cache](https://laravel.com/docs/12.x/cache#retrieving-items-from-the-cache)
- [Storing Items in the Cache](https://laravel.com/docs/12.x/cache#storing-items-in-the-cache)
- [Removing Items From the Cache](https://laravel.com/docs/12.x/cache#removing-items-from-the-cache)
- [Cache Memoization](https://laravel.com/docs/12.x/cache#cache-memoization)
- [The Cache Helper](https://laravel.com/docs/12.x/cache#the-cache-helper)
- [Cache Tags](https://laravel.com/docs/12.x/cache#cache-tags)
- [Atomic Locks](https://laravel.com/docs/12.x/cache#atomic-locks)
- [Managing Locks](https://laravel.com/docs/12.x/cache#managing-locks)
- [Managing Locks Across Processes](https://laravel.com/docs/12.x/cache#managing-locks-across-processes)
- [Concurrency Limiting](https://laravel.com/docs/12.x/cache#concurrency-limiting)
- [Cache Failover](https://laravel.com/docs/12.x/cache#cache-failover)
- [Adding Custom Cache Drivers](https://laravel.com/docs/12.x/cache#adding-custom-cache-drivers)
- [Writing the Driver](https://laravel.com/docs/12.x/cache#writing-the-driver)
- [Registering the Driver](https://laravel.com/docs/12.x/cache#registering-the-driver)
- [Events](https://laravel.com/docs/12.x/cache#events)
## [Introduction](https://laravel.com/docs/12.x/cache#introduction)
Some of the data retrieval or processing tasks performed by your application could be CPU intensive or take several seconds to complete. When this is the case, it is common to cache the retrieved data for a time so it can be retrieved quickly on subsequent requests for the same data. The cached data is usually stored in a very fast data store such as [Memcached](https://memcached.org/) or [Redis](https://redis.io/).
Thankfully, Laravel provides an expressive, unified API for various cache backends, allowing you to take advantage of their blazing fast data retrieval and speed up your web application.
## [Configuration](https://laravel.com/docs/12.x/cache#configuration)
Your application's cache configuration file is located at `config/cache.php`. In this file, you may specify which cache store you would like to be used by default throughout your application. Laravel supports popular caching backends like [Memcached](https://memcached.org/), [Redis](https://redis.io/), [DynamoDB](https://aws.amazon.com/dynamodb), and relational databases out of the box. In addition, a file based cache driver is available, while `array` and `null` cache drivers provide convenient cache backends for your automated tests.
The cache configuration file also contains a variety of other options that you may review. By default, Laravel is configured to use the `database` cache driver, which stores the serialized, cached objects in your application's database.
### [Driver Prerequisites](https://laravel.com/docs/12.x/cache#driver-prerequisites)
#### [Database](https://laravel.com/docs/12.x/cache#prerequisites-database)
When using the `database` cache driver, you will need a database table to contain the cache data. Typically, this is included in Laravel's default `0001_01_01_000001_create_cache_table.php` [database migration](https://laravel.com/docs/12.x/migrations); however, if your application does not contain this migration, you may use the `make:cache-table` Artisan command to create it:
```
1php artisan make:cache-table23php artisan migratephp artisan make:cache-table php artisan migrate
```
#### [Memcached](https://laravel.com/docs/12.x/cache#memcached)
Using the Memcached driver requires the [Memcached PECL package](https://pecl.php.net/package/memcached) to be installed. You may list all of your Memcached servers in the `config/cache.php` configuration file. This file already contains a `memcached.servers` entry to get you started:
```
1'memcached' => [2 // ...34 'servers' => [5 [6 'host' => env('MEMCACHED_HOST', '127.0.0.1'),7 'port' => env('MEMCACHED_PORT', 11211),8 'weight' => 100,9 ],10 ],11],'memcached' => [ // ... 'servers' => [ [ 'host' => env('MEMCACHED_HOST', '127.0.0.1'), 'port' => env('MEMCACHED_PORT', 11211), 'weight' => 100, ], ], ],
```
If needed, you may set the `host` option to a UNIX socket path. If you do this, the `port` option should be set to `0`:
```
1'memcached' => [2 // ...34 'servers' => [5 [6 'host' => '/var/run/memcached/memcached.sock',7 'port' => 0,8 'weight' => 1009 ],10 ],11],'memcached' => [ // ... 'servers' => [ [ 'host' => '/var/run/memcached/memcached.sock', 'port' => 0, 'weight' => 100 ], ], ],
```
#### [Redis](https://laravel.com/docs/12.x/cache#redis)
Before using a Redis cache with Laravel, you will need to either install the PhpRedis PHP extension via PECL or install the `predis/predis` package (~2.0) via Composer. [Laravel Sail](https://laravel.com/docs/12.x/sail) already includes this extension. In addition, official Laravel application platforms such as [Laravel Cloud](https://cloud.laravel.com/) and [Laravel Forge](https://forge.laravel.com/) have the PhpRedis extension installed by default.
For more information on configuring Redis, consult its [Laravel documentation page](https://laravel.com/docs/12.x/redis#configuration).
#### [DynamoDB](https://laravel.com/docs/12.x/cache#dynamodb)
Before using the [DynamoDB](https://aws.amazon.com/dynamodb) cache driver, you must create a DynamoDB table to store all of the cached data. Typically, this table should be named `cache`. However, you should name the table based on the value of the `stores.dynamodb.table` configuration value within the `cache` configuration file. The table name may also be set via the `DYNAMODB_CACHE_TABLE` environment variable.
This table should also have a string partition key with a name that corresponds to the value of the `stores.dynamodb.attributes.key` configuration item within your application's `cache` configuration file. By default, the partition key should be named `key`.
Typically, DynamoDB will not proactively remove expired items from a table. Therefore, you should [enable Time to Live (TTL)](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/TTL.html) on the table. When configuring the table's TTL settings, you should set the TTL attribute name to `expires_at`.
Next, install the AWS SDK so that your Laravel application can communicate with DynamoDB:
```
1composer require aws/aws-sdk-phpcomposer require aws/aws-sdk-php
```
In addition, you should ensure that values are provided for the DynamoDB cache store configuration options. Typically these options, such as `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`, should be defined in your application's `.env` configuration file:
```
1'dynamodb' => [2 'driver' => 'dynamodb',3 'key' => env('AWS_ACCESS_KEY_ID'),4 'secret' => env('AWS_SECRET_ACCESS_KEY'),5 'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),6 'table' => env('DYNAMODB_CACHE_TABLE', 'cache'),7 'endpoint' => env('DYNAMODB_ENDPOINT'),8],'dynamodb' => [ 'driver' => 'dynamodb', 'key' => env('AWS_ACCESS_KEY_ID'), 'secret' => env('AWS_SECRET_ACCESS_KEY'), 'region' => env('AWS_DEFAULT_REGION', 'us-east-1'), 'table' => env('DYNAMODB_CACHE_TABLE', 'cache'), 'endpoint' => env('DYNAMODB_ENDPOINT'), ],
```
#### [MongoDB](https://laravel.com/docs/12.x/cache#mongodb)
If you are using MongoDB, a `mongodb` cache driver is provided by the official `mongodb/laravel-mongodb` package and can be configured using a `mongodb` database connection. MongoDB supports TTL indexes, which can be used to automatically clear expired cache items.
For more information on configuring MongoDB, please refer to the MongoDB [Cache and Locks documentation](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/cache/).
## [Cache Usage](https://laravel.com/docs/12.x/cache#cache-usage)
### [Obtaining a Cache Instance](https://laravel.com/docs/12.x/cache#obtaining-a-cache-instance)
To obtain a cache store instance, you may use the `Cache` facade, which is what we will use throughout this documentation. The `Cache` facade provides convenient, terse access to the underlying implementations of the Laravel cache contracts:
```
1<?php23namespace App\Http\Controllers;45use Illuminate\Support\Facades\Cache;67class UserController extends Controller8{9 /**10 * Show a list of all users of the application.11 */12 public function index(): array13 {14 $value = Cache::get('key');1516 return [17 // ...18 ];19 }20}<?php namespace App\Http\Controllers; use Illuminate\Support\Facades\Cache; class UserController extends Controller { /** * Show a list of all users of the application. */ public function index(): array { $value = Cache::get('key'); return [ // ... ]; } }
```
#### [Accessing Multiple Cache Stores](https://laravel.com/docs/12.x/cache#accessing-multiple-cache-stores)
Using the `Cache` facade, you may access various cache stores via the `store` method. The key passed to the `store` method should correspond to one of the stores listed in the `stores` configuration array in your `cache` configuration file:
```
1$value = Cache::store('file')->get('foo');23Cache::store('redis')->put('bar', 'baz', 600); // 10 Minutes$value = Cache::store('file')->get('foo'); Cache::store('redis')->put('bar', 'baz', 600); // 10 Minutes
```
### [Retrieving Items From the Cache](https://laravel.com/docs/12.x/cache#retrieving-items-from-the-cache)
The `Cache` facade's `get` method is used to retrieve items from the cache. If the item does not exist in the cache, `null` will be returned. If you wish, you may pass a second argument to the `get` method specifying the default value you wish to be returned if the item doesn't exist:
```
1$value = Cache::get('key');23$value = Cache::get('key', 'default');$value = Cache::get('key'); $value = Cache::get('key', 'default');
```
You may even pass a closure as the default value. The result of the closure will be returned if the specified item does not exist in the cache. Passing a closure allows you to defer the retrieval of default values from a database or other external service:
```
1$value = Cache::get('key', function () {2 return DB::table(/* ... */)->get();3});$value = Cache::get('key', function () { return DB::table(/* ... */)->get(); });
```
#### [Determining Item Existence](https://laravel.com/docs/12.x/cache#determining-item-existence)
The `has` method may be used to determine if an item exists in the cache. This method will also return `false` if the item exists but its value is `null`:
```
1if (Cache::has('key')) {2 // ...3}if (Cache::has('key')) { // ... }
```
#### [Incrementing / Decrementing Values](https://laravel.com/docs/12.x/cache#incrementing-decrementing-values)
The `increment` and `decrement` methods may be used to adjust the value of integer items in the cache. Both of these methods accept an optional second argument indicating the amount by which to increment or decrement the item's value:
```
1// Initialize the value if it does not exist...2Cache::add('key', 0, now()->plus(hours: 4));34// Increment or decrement the value...5Cache::increment('key');6Cache::increment('key', $amount);7Cache::decrement('key');8Cache::decrement('key', $amount);// Initialize the value if it does not exist... Cache::add('key', 0, now()->plus(hours: 4)); // Increment or decrement the value... Cache::increment('key'); Cache::increment('key', $amount); Cache::decrement('key'); Cache::decrement('key', $amount);
```
#### [Retrieve and Store](https://laravel.com/docs/12.x/cache#retrieve-store)
Sometimes you may wish to retrieve an item from the cache, but also store a default value if the requested item doesn't exist. For example, you may wish to retrieve all users from the cache or, if they don't exist, retrieve them from the database and add them to the cache. You may do this using the `Cache::remember` method:
```
1$value = Cache::remember('users', $seconds, function () {2 return DB::table('users')->get();3});$value = Cache::remember('users', $seconds, function () { return DB::table('users')->get(); });
```
If the item does not exist in the cache, the closure passed to the `remember` method will be executed and its result will be placed in the cache.
You may use the `rememberForever` method to retrieve an item from the cache or store it forever if it does not exist:
```
1$value = Cache::rememberForever('users', function () {2 return DB::table('users')->get();3});$value = Cache::rememberForever('users', function () { return DB::table('users')->get(); });
```
#### [Stale While Revalidate](https://laravel.com/docs/12.x/cache#swr)
When using the `Cache::remember` method, some users may experience slow response times if the cached value has expired. For certain types of data, it can be useful to allow partially stale data to be served while the cached value is recalculated in the background, preventing some users from experiencing slow response times while cached values are calculated. This is often referred to as the "stale-while-revalidate" pattern, and the `Cache::flexible` method provides an implementation of this pattern.
The flexible method accepts an array that specifies how long the cached value is considered "fresh" and when it becomes "stale". The first value in the array represents the number of seconds the cache is considered fresh, while the second value defines how long it can be served as stale data before recalculation is necessary.
If a request is made within the fresh period (before the first value), the cache is returned immediately without recalculation. If a request is made during the stale period (between the two values), the stale value is served to the user, and a [deferred function](https://laravel.com/docs/12.x/helpers#deferred-functions) is registered to refresh the cached value after the response is sent to the user. If a request is made after the second value, the cache is considered expired, and the value is recalculated immediately, which may result in a slower response for the user:
```
1$value = Cache::flexible('users', [5, 10], function () {2 return DB::table('users')->get();3});$value = Cache::flexible('users', [5, 10], function () { return DB::table('users')->get(); });
```
#### [Retrieve and Delete](https://laravel.com/docs/12.x/cache#retrieve-delete)
If you need to retrieve an item from the cache and then delete the item, you may use the `pull` method. Like the `get` method, `null` will be returned if the item does not exist in the cache:
```
1$value = Cache::pull('key');23$value = Cache::pull('key', 'default');$value = Cache::pull('key'); $value = Cache::pull('key', 'default');
```
### [Storing Items in the Cache](https://laravel.com/docs/12.x/cache#storing-items-in-the-cache)
You may use the `put` method on the `Cache` facade to store items in the cache:
```
1Cache::put('key', 'value', $seconds = 10);Cache::put('key', 'value', $seconds = 10);
```
If the storage time is not passed to the `put` method, the item will be stored indefinitely:
```
1Cache::put('key', 'value');Cache::put('key', 'value');
```
Instead of passing the number of seconds as an integer, you may also pass a `DateTime` instance representing the desired expiration time of the cached item:
```
1Cache::put('key', 'value', now()->plus(minutes: 10));Cache::put('key', 'value', now()->plus(minutes: 10));
```
#### [Store if Not Present](https://laravel.com/docs/12.x/cache#store-if-not-present)
The `add` method will only add the item to the cache if it does not already exist in the cache store. The method will return `true` if the item is actually added to the cache. Otherwise, the method will return `false`. The `add` method is an atomic operation:
```
1Cache::add('key', 'value', $seconds);Cache::add('key', 'value', $seconds);
```
#### [Storing Items Forever](https://laravel.com/docs/12.x/cache#storing-items-forever)
The `forever` method may be used to store an item in the cache permanently. Since these items will not expire, they must be manually removed from the cache using the `forget` method:
```
1Cache::forever('key', 'value');Cache::forever('key', 'value');
```
If you are using the Memcached driver, items that are stored "forever" may be removed when the cache reaches its size limit.
### [Removing Items From the Cache](https://laravel.com/docs/12.x/cache#removing-items-from-the-cache)
You may remove items from the cache using the `forget` method:
```
1Cache::forget('key');Cache::forget('key');
```
You may also remove items by providing a zero or negative number of expiration seconds:
```
1Cache::put('key', 'value', 0);23Cache::put('key', 'value', -5);Cache::put('key', 'value', 0); Cache::put('key', 'value', -5);
```
You may clear the entire cache using the `flush` method:
```
1Cache::flush();Cache::flush();
```
Flushing the cache does not respect your configured cache "prefix" and will remove all entries from the cache. Consider this carefully when clearing a cache which is shared by other applications.
### [Cache Memoization](https://laravel.com/docs/12.x/cache#cache-memoization)
Laravel's `memo` cache driver allows you to temporarily store resolved cache values in memory during a single request or job execution. This prevents repeated cache hits within the same execution, significantly improving performance.
To use the memoized cache, invoke the `memo` method:
```
1use Illuminate\Support\Facades\Cache;23$value = Cache::memo()->get('key');use Illuminate\Support\Facades\Cache; $value = Cache::memo()->get('key');
```
The `memo` method optionally accepts the name of a cache store, which specifies the underlying cache store the memoized driver will decorate:
```
1// Using the default cache store...2$value = Cache::memo()->get('key');34// Using the Redis cache store...5$value = Cache::memo('redis')->get('key');// Using the default cache store... $value = Cache::memo()->get('key'); // Using the Redis cache store... $value = Cache::memo('redis')->get('key');
```
The first `get` call for a given key retrieves the value from your cache store, but subsequent calls within the same request or job will retrieve the value from memory:
```
1// Hits the cache...2$value = Cache::memo()->get('key');34// Does not hit the cache, returns memoized value...5$value = Cache::memo()->get('key');// Hits the cache... $value = Cache::memo()->get('key'); // Does not hit the cache, returns memoized value... $value = Cache::memo()->get('key');
```
When calling methods that modify cache values (such as `put`, `increment`, `remember`, etc.), the memoized cache automatically forgets the memoized value and delegates the mutating method call to the underlying cache store:
```
1Cache::memo()->put('name', 'Taylor'); // Writes to underlying cache...2Cache::memo()->get('name'); // Hits underlying cache...3Cache::memo()->get('name'); // Memoized, does not hit cache...45Cache::memo()->put('name', 'Tim'); // Forgets memoized value, writes new value...6Cache::memo()->get('name'); // Hits underlying cache again...Cache::memo()->put('name', 'Taylor'); // Writes to underlying cache... Cache::memo()->get('name'); // Hits underlying cache... Cache::memo()->get('name'); // Memoized, does not hit cache... Cache::memo()->put('name', 'Tim'); // Forgets memoized value, writes new value... Cache::memo()->get('name'); // Hits underlying cache again...
```
### [The Cache Helper](https://laravel.com/docs/12.x/cache#the-cache-helper)
In addition to using the `Cache` facade, you may also use the global `cache` function to retrieve and store data via the cache. When the `cache` function is called with a single, string argument, it will return the value of the given key:
```
1$value = cache('key');$value = cache('key');
```
If you provide an array of key / value pairs and an expiration time to the function, it will store values in the cache for the specified duration:
```
1cache(['key' => 'value'], $seconds);23cache(['key' => 'value'], now()->plus(minutes: 10));cache(['key' => 'value'], $seconds); cache(['key' => 'value'], now()->plus(minutes: 10));
```
When the `cache` function is called without any arguments, it returns an instance of the `Illuminate\Contracts\Cache\Factory` implementation, allowing you to call other caching methods:
```
1cache()->remember('users', $seconds, function () {2 return DB::table('users')->get();3});cache()->remember('users', $seconds, function () { return DB::table('users')->get(); });
```
When testing calls to the global `cache` function, you may use the `Cache::shouldReceive` method just as if you were [testing the facade](https://laravel.com/docs/12.x/mocking#mocking-facades).
## [Cache Tags](https://laravel.com/docs/12.x/cache#cache-tags)
Cache tags are not supported when using the `file`, `dynamodb`, or `database` cache drivers.
### [Storing Tagged Cache Items](https://laravel.com/docs/12.x/cache#storing-tagged-cache-items)
Cache tags allow you to tag related items in the cache and then flush all cached values that have been assigned a given tag. You may access a tagged cache by passing in an ordered array of tag names. For example, let's access a tagged cache and `put` a value into the cache:
```
1use Illuminate\Support\Facades\Cache;23Cache::tags(['people', 'artists'])->put('John', $john, $seconds);4Cache::tags(['people', 'authors'])->put('Anne', $anne, $seconds);use Illuminate\Support\Facades\Cache; Cache::tags(['people', 'artists'])->put('John', $john, $seconds); Cache::tags(['people', 'authors'])->put('Anne', $anne, $seconds);
```
### [Accessing Tagged Cache Items](https://laravel.com/docs/12.x/cache#accessing-tagged-cache-items)
Items stored via tags may not be accessed without also providing the tags that were used to store the value. To retrieve a tagged cache item, pass the same ordered list of tags to the `tags` method, then call the `get` method with the key you wish to retrieve:
```
1$john = Cache::tags(['people', 'artists'])->get('John');23$anne = Cache::tags(['people', 'authors'])->get('Anne');$john = Cache::tags(['people', 'artists'])->get('John'); $anne = Cache::tags(['people', 'authors'])->get('Anne');
```
### [Removing Tagged Cache Items](https://laravel.com/docs/12.x/cache#removing-tagged-cache-items)
You may flush all items that are assigned a tag or list of tags. For example, the following code would remove all caches tagged with either `people`, `authors`, or both. So, both `Anne` and `John` would be removed from the cache:
```
1Cache::tags(['people', 'authors'])->flush();Cache::tags(['people', 'authors'])->flush();
```
In contrast, the code below would remove only cached values tagged with `authors`, so `Anne` would be removed, but not `John`:
```
1Cache::tags('authors')->flush();Cache::tags('authors')->flush();
```
## [Atomic Locks](https://laravel.com/docs/12.x/cache#atomic-locks)
To utilize this feature, your application must be using the `memcached`, `redis`, `dynamodb`, `database`, `file`, or `array` cache driver as your application's default cache driver. In addition, all servers must be communicating with the same central cache server.
### [Managing Locks](https://laravel.com/docs/12.x/cache#managing-locks)
Atomic locks allow for the manipulation of distributed locks without worrying about race conditions. For example, [Laravel Cloud](https://cloud.laravel.com/) uses atomic locks to ensure that only one remote task is being executed on a server at a time. You may create and manage locks using the `Cache::lock` method:
```
1use Illuminate\Support\Facades\Cache;23$lock = Cache::lock('foo', 10);45if ($lock->get()) {6 // Lock acquired for 10 seconds...78 $lock->release();9}use Illuminate\Support\Facades\Cache; $lock = Cache::lock('foo', 10); if ($lock->get()) { // Lock acquired for 10 seconds... $lock->release(); }
```
The `get` method also accepts a closure. After the closure is executed, Laravel will automatically release the lock:
```
1Cache::lock('foo', 10)->get(function () {2 // Lock acquired for 10 seconds and automatically released...3});Cache::lock('foo', 10)->get(function () { // Lock acquired for 10 seconds and automatically released... });
```
If the lock is not available at the moment you request it, you may instruct Laravel to wait for a specified number of seconds. If the lock cannot be acquired within the specified time limit, an `Illuminate\Contracts\Cache\LockTimeoutException` will be thrown:
```
1use Illuminate\Contracts\Cache\LockTimeoutException;23$lock = Cache::lock('foo', 10);45try {6 $lock->block(5);78 // Lock acquired after waiting a maximum of 5 seconds...9} catch (LockTimeoutException $e) {10 // Unable to acquire lock...11} finally {12 $lock->release();13}use Illuminate\Contracts\Cache\LockTimeoutException; $lock = Cache::lock('foo', 10); try { $lock->block(5); // Lock acquired after waiting a maximum of 5 seconds... } catch (LockTimeoutException $e) { // Unable to acquire lock... } finally { $lock->release(); }
```
The example above may be simplified by passing a closure to the `block` method. When a closure is passed to this method, Laravel will attempt to acquire the lock for the specified number of seconds and will automatically release the lock once the closure has been executed:
```
1Cache::lock('foo', 10)->block(5, function () {2 // Lock acquired for 10 seconds after waiting a maximum of 5 seconds...3});Cache::lock('foo', 10)->block(5, function () { // Lock acquired for 10 seconds after waiting a maximum of 5 seconds... });
```
### [Managing Locks Across Processes](https://laravel.com/docs/12.x/cache#managing-locks-across-processes)
Sometimes, you may wish to acquire a lock in one process and release it in another process. For example, you may acquire a lock during a web request and wish to release the lock at the end of a queued job that is triggered by that request. In this scenario, you should pass the lock's scoped "owner token" to the queued job so that the job can re-instantiate the lock using the given token.
In the example below, we will dispatch a queued job if a lock is successfully acquired. In addition, we will pass the lock's owner token to the queued job via the lock's `owner` method:
```
1$podcast = Podcast::find($id);23$lock = Cache::lock('processing', 120);45if ($lock->get()) {6 ProcessPodcast::dispatch($podcast, $lock->owner());7}$podcast = Podcast::find($id); $lock = Cache::lock('processing', 120); if ($lock->get()) { ProcessPodcast::dispatch($podcast, $lock->owner()); }
```
Within our application's `ProcessPodcast` job, we can restore and release the lock using the owner token:
```
1Cache::restoreLock('processing', $this->owner)->release();Cache::restoreLock('processing', $this->owner)->release();
```
If you would like to release a lock without respecting its current owner, you may use the `forceRelease` method:
```
1Cache::lock('processing')->forceRelease();Cache::lock('processing')->forceRelease();
```
### [Concurrency Limiting](https://laravel.com/docs/12.x/cache#concurrency-limiting)
Laravel's atomic lock functionality also provides a few ways to limit concurrent execution of closures. Use `withoutOverlapping` when you want to allow only one running instance across your infrastructure:
```
1Cache::withoutOverlapping('foo', function () {2 // Lock acquired after waiting a maximum of 10 seconds...3});Cache::withoutOverlapping('foo', function () { // Lock acquired after waiting a maximum of 10 seconds... });
```
By default, the lock is held until the closure finishes executing, and the method waits up to 10 seconds to acquire the lock. You may customize these values using additional arguments:
```
1Cache::withoutOverlapping('foo', function () {2 // Lock acquired for 120 seconds after waiting a maximum of 5 seconds...3}, lockFor: 120, waitFor: 5);Cache::withoutOverlapping('foo', function () { // Lock acquired for 120 seconds after waiting a maximum of 5 seconds... }, lockFor: 120, waitFor: 5);
```
If the lock cannot be acquired within the specified wait time, an `Illuminate\Contracts\Cache\LockTimeoutException` will be thrown.
If you want controlled parallelism, use the `funnel` method to set a maximum number of concurrent executions. The `funnel` method works with any cache driver that supports locks:
```
1Cache::funnel('foo')2 ->limit(3)3 ->releaseAfter(60)4 ->block(10)5 ->then(function () {6 // Concurrency lock acquired...7 }, function () {8 // Could not acquire concurrency lock...9 });Cache::funnel('foo') ->limit(3) ->releaseAfter(60) ->block(10) ->then(function () { // Concurrency lock acquired... }, function () { // Could not acquire concurrency lock... });
```
The `funnel` key identifies the resource being limited. The `limit` method defines the maximum concurrent executions. The `releaseAfter` method sets a safety timeout in seconds before an acquired slot is automatically released. The `block` method sets how many seconds to wait for an available slot.
If you prefer to handle the timeout via exceptions instead of providing a failure closure, you may omit the second closure. An `Illuminate\Cache\Limiters\LimiterTimeoutException` will be thrown if the lock cannot be acquired within the specified wait time:
```
1use Illuminate\Cache\Limiters\LimiterTimeoutException;23try {4 Cache::funnel('foo')5 ->limit(3)6 ->releaseAfter(60)7 ->block(10)8 ->then(function () {9 // Concurrency lock acquired...10 });11} catch (LimiterTimeoutException $e) {12 // Unable to acquire concurrency lock...13}use Illuminate\Cache\Limiters\LimiterTimeoutException; try { Cache::funnel('foo') ->limit(3) ->releaseAfter(60) ->block(10) ->then(function () { // Concurrency lock acquired... }); } catch (LimiterTimeoutException $e) { // Unable to acquire concurrency lock... }
```
If you would like to use a specific cache store for the concurrency limiter, you may invoke the `funnel` method on the desired store:
```
1Cache::store('redis')->funnel('foo')2 ->limit(3)3 ->block(10)4 ->then(function () {5 // Concurrency lock acquired using the "redis" store...6 });Cache::store('redis')->funnel('foo') ->limit(3) ->block(10) ->then(function () { // Concurrency lock acquired using the "redis" store... });
```
The `funnel` method requires the cache store to implement the `Illuminate\Contracts\Cache\LockProvider` interface. If you attempt to use `funnel` with a cache store that does not support locks, a `BadMethodCallException` will be thrown.
## [Cache Failover](https://laravel.com/docs/12.x/cache#cache-failover)
The `failover` cache driver provides automatic failover functionality when interacting with the cache. If the primary cache store of the `failover` store fails for any reason, Laravel will automatically attempt to use the next configured store in the list. This is particularly useful for ensuring high availability in production environments where cache reliability is critical.
To configure a failover cache store, specify the `failover` driver and provide an array of store names to attempt in order. By default, Laravel includes an example failover configuration in your application's `config/cache.php` configuration file:
```
1'failover' => [2 'driver' => 'failover',3 'stores' => [4 'database',5 'array',6 ],7],'failover' => [ 'driver' => 'failover', 'stores' => [ 'database', 'array', ], ],
```
Once you have configured a store that uses the `failover` driver, you will need to set the failover store as your default cache store in your application's `.env` file to make use of the failover functionality:
```
1CACHE_STORE=failoverCACHE_STORE=failover
```
When a cache store operation fails and failover is activated, Laravel will dispatch the `Illuminate\Cache\Events\CacheFailedOver` event, allowing you to report or log that a cache store has failed.
## [Adding Custom Cache Drivers](https://laravel.com/docs/12.x/cache#adding-custom-cache-drivers)
### [Writing the Driver](https://laravel.com/docs/12.x/cache#writing-the-driver)
To create our custom cache driver, we first need to implement the `Illuminate\Contracts\Cache\Store` [contract](https://laravel.com/docs/12.x/contracts). So, a MongoDB cache implementation might look something like this:
```
1<?php23namespace App\Extensions;45use Illuminate\Contracts\Cache\Store;67class MongoStore implements Store8{9 public function get($key) {}10 public function many(array $keys) {}11 public function put($key, $value, $seconds) {}12 public function putMany(array $values, $seconds) {}13 public function increment($key, $value = 1) {}14 public function decrement($key, $value = 1) {}15 public function forever($key, $value) {}16 public function forget($key) {}17 public function flush() {}18 public function getPrefix() {}19}<?php namespace App\Extensions; use Illuminate\Contracts\Cache\Store; class MongoStore implements Store { public function get($key) {} public function many(array $keys) {} public function put($key, $value, $seconds) {} public function putMany(array $values, $seconds) {} public function increment($key, $value = 1) {} public function decrement($key, $value = 1) {} public function forever($key, $value) {} public function forget($key) {} public function flush() {} public function getPrefix() {} }
```
We just need to implement each of these methods using a MongoDB connection. For an example of how to implement each of these methods, take a look at the `Illuminate\Cache\MemcachedStore` in the [Laravel framework source code](https://github.com/laravel/framework). Once our implementation is complete, we can finish our custom driver registration by calling the `Cache` facade's `extend` method:
```
1Cache::extend('mongo', function (Application $app) {2 return Cache::repository(new MongoStore);3});Cache::extend('mongo', function (Application $app) { return Cache::repository(new MongoStore); });
```
If you're wondering where to put your custom cache driver code, you could create an `Extensions` namespace within your `app` directory. However, keep in mind that Laravel does not have a rigid application structure and you are free to organize your application according to your preferences.
### [Registering the Driver](https://laravel.com/docs/12.x/cache#registering-the-driver)
To register the custom cache driver with Laravel, we will use the `extend` method on the `Cache` facade. Since other service providers may attempt to read cached values within their `boot` method, we will register our custom driver within a `booting` callback. By using the `booting` callback, we can ensure that the custom driver is registered just before the `boot` method is called on our application's service providers but after the `register` method is called on all of the service providers. We will register our `booting` callback within the `register` method of our application's `App\Providers\AppServiceProvider` class:
```
1<?php23namespace App\Providers;45use App\Extensions\MongoStore;6use Illuminate\Contracts\Foundation\Application;7use Illuminate\Support\Facades\Cache;8use Illuminate\Support\ServiceProvider;910class AppServiceProvider extends ServiceProvider11{12 /**13 * Register any application services.14 */15 public function register(): void16 {17 $this->app->booting(function () {18 Cache::extend('mongo', function (Application $app) {19 return Cache::repository(new MongoStore);20 });21 });22 }2324 /**25 * Bootstrap any application services.26 */27 public function boot(): void28 {29 // ...30 }31}<?php namespace App\Providers; use App\Extensions\MongoStore; use Illuminate\Contracts\Foundation\Application; use Illuminate\Support\Facades\Cache; use Illuminate\Support\ServiceProvider; class AppServiceProvider extends ServiceProvider { /** * Register any application services. */ public function register(): void { $this->app->booting(function () { Cache::extend('mongo', function (Application $app) { return Cache::repository(new MongoStore); }); }); } /** * Bootstrap any application services. */ public function boot(): void { // ... } }
```
The first argument passed to the `extend` method is the name of the driver. This will correspond to your `driver` option in the `config/cache.php` configuration file. The second argument is a closure that should return an `Illuminate\Cache\Repository` instance. The closure will be passed an `$app` instance, which is an instance of the [service container](https://laravel.com/docs/12.x/container).
Once your extension is registered, update the `CACHE_STORE` environment variable or `default` option within your application's `config/cache.php` configuration file to the name of your extension.
## [Events](https://laravel.com/docs/12.x/cache#events)
To execute code on every cache operation, you may listen for various [events](https://laravel.com/docs/12.x/events) dispatched by the cache:
| Event Name |
|---|
| `Illuminate\Cache\Events\CacheFlushed` |
| `Illuminate\Cache\Events\CacheFlushing` |
| `Illuminate\Cache\Events\CacheHit` |
| `Illuminate\Cache\Events\CacheMissed` |
| `Illuminate\Cache\Events\ForgettingKey` |
| `Illuminate\Cache\Events\KeyForgetFailed` |
| `Illuminate\Cache\Events\KeyForgotten` |
| `Illuminate\Cache\Events\KeyWriteFailed` |
| `Illuminate\Cache\Events\KeyWritten` |
| `Illuminate\Cache\Events\RetrievingKey` |
| `Illuminate\Cache\Events\RetrievingManyKeys` |
| `Illuminate\Cache\Events\WritingKey` |
| `Illuminate\Cache\Events\WritingManyKeys` |
To increase performance, you may disable cache events by setting the `events` configuration option to `false` for a given cache store in your application's `config/cache.php` configuration file:
```
1'database' => [2 'driver' => 'database',3 // ...4 'events' => false,5],'database' => [ 'driver' => 'database', // ... 'events' => false, ],
```
Copy as markdown
### On this page
- [Introduction](https://laravel.com/docs/12.x/cache#introduction)
- [Configuration](https://laravel.com/docs/12.x/cache#configuration)
- [Driver Prerequisites](https://laravel.com/docs/12.x/cache#driver-prerequisites)
- [Cache Usage](https://laravel.com/docs/12.x/cache#cache-usage)
- [Obtaining a Cache Instance](https://laravel.com/docs/12.x/cache#obtaining-a-cache-instance)
- [Retrieving Items From the Cache](https://laravel.com/docs/12.x/cache#retrieving-items-from-the-cache)
- [Storing Items in the Cache](https://laravel.com/docs/12.x/cache#storing-items-in-the-cache)
- [Removing Items From the Cache](https://laravel.com/docs/12.x/cache#removing-items-from-the-cache)
- [Cache Memoization](https://laravel.com/docs/12.x/cache#cache-memoization)
- [The Cache Helper](https://laravel.com/docs/12.x/cache#the-cache-helper)
- [Cache Tags](https://laravel.com/docs/12.x/cache#cache-tags)
- [Atomic Locks](https://laravel.com/docs/12.x/cache#atomic-locks)
- [Managing Locks](https://laravel.com/docs/12.x/cache#managing-locks)
- [Managing Locks Across Processes](https://laravel.com/docs/12.x/cache#managing-locks-across-processes)
- [Concurrency Limiting](https://laravel.com/docs/12.x/cache#concurrency-limiting)
- [Cache Failover](https://laravel.com/docs/12.x/cache#cache-failover)
- [Adding Custom Cache Drivers](https://laravel.com/docs/12.x/cache#adding-custom-cache-drivers)
- [Writing the Driver](https://laravel.com/docs/12.x/cache#writing-the-driver)
- [Registering the Driver](https://laravel.com/docs/12.x/cache#registering-the-driver)
- [Events](https://laravel.com/docs/12.x/cache#events)
[](https://nightwatch.laravel.com/)
Laravel is the most productive way to
build, deploy, and monitor software.
- © 2026 Laravel
- [Legal](https://laravel.com/legal)
- [Status](https://status.laravel.com/)
#### Products
- [Cloud](https://cloud.laravel.com/)
- [Forge](https://forge.laravel.com/)
- [Nightwatch](https://nightwatch.laravel.com/)
- [Vapor](https://vapor.laravel.com/)
- [Nova](https://nova.laravel.com/)
#### Packages
- [Cashier](https://laravel.com/docs/billing)
- [Dusk](https://laravel.com/docs/dusk)
- [Horizon](https://laravel.com/docs/horizon)
- [Octane](https://laravel.com/docs/octane)
- [Scout](https://laravel.com/docs/scout)
- [Pennant](https://laravel.com/docs/pennant)
- [Pint](https://laravel.com/docs/pint)
- [Sail](https://laravel.com/docs/sail)
- [Sanctum](https://laravel.com/docs/sanctum)
- [Socialite](https://laravel.com/docs/socialite)
- [Telescope](https://laravel.com/docs/telescope)
- [Pulse](https://laravel.com/docs/pulse)
- [Reverb](https://laravel.com/docs/reverb)
- [Echo](https://laravel.com/docs/broadcasting)
#### Resources
- [Documentation](https://laravel.com/docs)
- [Starter Kits](https://laravel.com/starter-kits)
- [Release Notes](https://laravel.com/docs/releases)
- [Blog](https://laravel.com/blog)
- [News](https://laravel-news.com/)
- [Community](https://laravel.com/community)
- [Larabelles](https://larabelles.com/)
- [Learn](https://laravel.com/learn)
- [Jobs](https://larajobs.com/?partner=5)
- [Careers](https://laravel.com/careers)
- [Trust](https://trust.laravel.com/)
#### Partners
- [Vehikl](https://laravel.com/partners/vehikl)
- [Jump24](https://laravel.com/partners/jump24)
- [Tighten](https://laravel.com/partners/tighten)
- [Threadable](https://laravel.com/partners/threadable)
- [Kirschbaum](https://laravel.com/partners/kirschbaum)
- [Steadfast Collective](https://laravel.com/partners/steadfast-collective)
- [CACI Limited](https://laravel.com/partners/caci-limited)
- [byte5](https://laravel.com/partners/byte5)
- [Pixel](https://laravel.com/partners/pixel)
- [UCodeSoft](https://laravel.com/partners/ucodesoft)
- [See All](https://laravel.com/partners) |
| Readable Markdown | > **WARNING** You're browsing the documentation for an old version of Laravel. Consider upgrading your project to [Laravel 13.x](https://laravel.com/docs/13.x/cache).
- [Introduction](https://laravel.com/docs/12.x/cache#introduction)
- [Configuration](https://laravel.com/docs/12.x/cache#configuration)
- [Driver Prerequisites](https://laravel.com/docs/12.x/cache#driver-prerequisites)
- [Cache Usage](https://laravel.com/docs/12.x/cache#cache-usage)
- [Obtaining a Cache Instance](https://laravel.com/docs/12.x/cache#obtaining-a-cache-instance)
- [Retrieving Items From the Cache](https://laravel.com/docs/12.x/cache#retrieving-items-from-the-cache)
- [Storing Items in the Cache](https://laravel.com/docs/12.x/cache#storing-items-in-the-cache)
- [Removing Items From the Cache](https://laravel.com/docs/12.x/cache#removing-items-from-the-cache)
- [Cache Memoization](https://laravel.com/docs/12.x/cache#cache-memoization)
- [The Cache Helper](https://laravel.com/docs/12.x/cache#the-cache-helper)
- [Cache Tags](https://laravel.com/docs/12.x/cache#cache-tags)
- [Atomic Locks](https://laravel.com/docs/12.x/cache#atomic-locks)
- [Managing Locks](https://laravel.com/docs/12.x/cache#managing-locks)
- [Managing Locks Across Processes](https://laravel.com/docs/12.x/cache#managing-locks-across-processes)
- [Concurrency Limiting](https://laravel.com/docs/12.x/cache#concurrency-limiting)
- [Cache Failover](https://laravel.com/docs/12.x/cache#cache-failover)
- [Adding Custom Cache Drivers](https://laravel.com/docs/12.x/cache#adding-custom-cache-drivers)
- [Writing the Driver](https://laravel.com/docs/12.x/cache#writing-the-driver)
- [Registering the Driver](https://laravel.com/docs/12.x/cache#registering-the-driver)
- [Events](https://laravel.com/docs/12.x/cache#events)
## [Introduction](https://laravel.com/docs/12.x/cache#introduction)
Some of the data retrieval or processing tasks performed by your application could be CPU intensive or take several seconds to complete. When this is the case, it is common to cache the retrieved data for a time so it can be retrieved quickly on subsequent requests for the same data. The cached data is usually stored in a very fast data store such as [Memcached](https://memcached.org/) or [Redis](https://redis.io/).
Thankfully, Laravel provides an expressive, unified API for various cache backends, allowing you to take advantage of their blazing fast data retrieval and speed up your web application.
## [Configuration](https://laravel.com/docs/12.x/cache#configuration)
Your application's cache configuration file is located at `config/cache.php`. In this file, you may specify which cache store you would like to be used by default throughout your application. Laravel supports popular caching backends like [Memcached](https://memcached.org/), [Redis](https://redis.io/), [DynamoDB](https://aws.amazon.com/dynamodb), and relational databases out of the box. In addition, a file based cache driver is available, while `array` and `null` cache drivers provide convenient cache backends for your automated tests.
The cache configuration file also contains a variety of other options that you may review. By default, Laravel is configured to use the `database` cache driver, which stores the serialized, cached objects in your application's database.
### [Driver Prerequisites](https://laravel.com/docs/12.x/cache#driver-prerequisites)
#### [Database](https://laravel.com/docs/12.x/cache#prerequisites-database)
When using the `database` cache driver, you will need a database table to contain the cache data. Typically, this is included in Laravel's default `0001_01_01_000001_create_cache_table.php` [database migration](https://laravel.com/docs/12.x/migrations); however, if your application does not contain this migration, you may use the `make:cache-table` Artisan command to create it:
```
1php artisan make:cache-table23php artisan migrate
```
#### [Memcached](https://laravel.com/docs/12.x/cache#memcached)
Using the Memcached driver requires the [Memcached PECL package](https://pecl.php.net/package/memcached) to be installed. You may list all of your Memcached servers in the `config/cache.php` configuration file. This file already contains a `memcached.servers` entry to get you started:
```
1'memcached' => [2 // ...34 'servers' => [5 [6 'host' => env('MEMCACHED_HOST', '127.0.0.1'),7 'port' => env('MEMCACHED_PORT', 11211),8 'weight' => 100,9 ],10 ],11],
```
If needed, you may set the `host` option to a UNIX socket path. If you do this, the `port` option should be set to `0`:
```
1'memcached' => [2 // ...34 'servers' => [5 [6 'host' => '/var/run/memcached/memcached.sock',7 'port' => 0,8 'weight' => 1009 ],10 ],11],
```
#### [Redis](https://laravel.com/docs/12.x/cache#redis)
Before using a Redis cache with Laravel, you will need to either install the PhpRedis PHP extension via PECL or install the `predis/predis` package (~2.0) via Composer. [Laravel Sail](https://laravel.com/docs/12.x/sail) already includes this extension. In addition, official Laravel application platforms such as [Laravel Cloud](https://cloud.laravel.com/) and [Laravel Forge](https://forge.laravel.com/) have the PhpRedis extension installed by default.
For more information on configuring Redis, consult its [Laravel documentation page](https://laravel.com/docs/12.x/redis#configuration).
#### [DynamoDB](https://laravel.com/docs/12.x/cache#dynamodb)
Before using the [DynamoDB](https://aws.amazon.com/dynamodb) cache driver, you must create a DynamoDB table to store all of the cached data. Typically, this table should be named `cache`. However, you should name the table based on the value of the `stores.dynamodb.table` configuration value within the `cache` configuration file. The table name may also be set via the `DYNAMODB_CACHE_TABLE` environment variable.
This table should also have a string partition key with a name that corresponds to the value of the `stores.dynamodb.attributes.key` configuration item within your application's `cache` configuration file. By default, the partition key should be named `key`.
Typically, DynamoDB will not proactively remove expired items from a table. Therefore, you should [enable Time to Live (TTL)](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/TTL.html) on the table. When configuring the table's TTL settings, you should set the TTL attribute name to `expires_at`.
Next, install the AWS SDK so that your Laravel application can communicate with DynamoDB:
```
1composer require aws/aws-sdk-php
```
In addition, you should ensure that values are provided for the DynamoDB cache store configuration options. Typically these options, such as `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`, should be defined in your application's `.env` configuration file:
```
1'dynamodb' => [2 'driver' => 'dynamodb',3 'key' => env('AWS_ACCESS_KEY_ID'),4 'secret' => env('AWS_SECRET_ACCESS_KEY'),5 'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),6 'table' => env('DYNAMODB_CACHE_TABLE', 'cache'),7 'endpoint' => env('DYNAMODB_ENDPOINT'),8],
```
#### [MongoDB](https://laravel.com/docs/12.x/cache#mongodb)
If you are using MongoDB, a `mongodb` cache driver is provided by the official `mongodb/laravel-mongodb` package and can be configured using a `mongodb` database connection. MongoDB supports TTL indexes, which can be used to automatically clear expired cache items.
For more information on configuring MongoDB, please refer to the MongoDB [Cache and Locks documentation](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/cache/).
## [Cache Usage](https://laravel.com/docs/12.x/cache#cache-usage)
### [Obtaining a Cache Instance](https://laravel.com/docs/12.x/cache#obtaining-a-cache-instance)
To obtain a cache store instance, you may use the `Cache` facade, which is what we will use throughout this documentation. The `Cache` facade provides convenient, terse access to the underlying implementations of the Laravel cache contracts:
```
1<?php23namespace App\Http\Controllers;45use Illuminate\Support\Facades\Cache;67class UserController extends Controller8{9 /**10 * Show a list of all users of the application.11 */12 public function index(): array13 {14 $value = Cache::get('key');1516 return [17 // ...18 ];19 }20}
```
#### [Accessing Multiple Cache Stores](https://laravel.com/docs/12.x/cache#accessing-multiple-cache-stores)
Using the `Cache` facade, you may access various cache stores via the `store` method. The key passed to the `store` method should correspond to one of the stores listed in the `stores` configuration array in your `cache` configuration file:
```
1$value = Cache::store('file')->get('foo');23Cache::store('redis')->put('bar', 'baz', 600); // 10 Minutes
```
### [Retrieving Items From the Cache](https://laravel.com/docs/12.x/cache#retrieving-items-from-the-cache)
The `Cache` facade's `get` method is used to retrieve items from the cache. If the item does not exist in the cache, `null` will be returned. If you wish, you may pass a second argument to the `get` method specifying the default value you wish to be returned if the item doesn't exist:
```
1$value = Cache::get('key');23$value = Cache::get('key', 'default');
```
You may even pass a closure as the default value. The result of the closure will be returned if the specified item does not exist in the cache. Passing a closure allows you to defer the retrieval of default values from a database or other external service:
```
1$value = Cache::get('key', function () {2 return DB::table(/* ... */)->get();3});
```
#### [Determining Item Existence](https://laravel.com/docs/12.x/cache#determining-item-existence)
The `has` method may be used to determine if an item exists in the cache. This method will also return `false` if the item exists but its value is `null`:
```
1if (Cache::has('key')) {2 // ...3}
```
#### [Incrementing / Decrementing Values](https://laravel.com/docs/12.x/cache#incrementing-decrementing-values)
The `increment` and `decrement` methods may be used to adjust the value of integer items in the cache. Both of these methods accept an optional second argument indicating the amount by which to increment or decrement the item's value:
```
1// Initialize the value if it does not exist...2Cache::add('key', 0, now()->plus(hours: 4));34// Increment or decrement the value...5Cache::increment('key');6Cache::increment('key', $amount);7Cache::decrement('key');8Cache::decrement('key', $amount);
```
#### [Retrieve and Store](https://laravel.com/docs/12.x/cache#retrieve-store)
Sometimes you may wish to retrieve an item from the cache, but also store a default value if the requested item doesn't exist. For example, you may wish to retrieve all users from the cache or, if they don't exist, retrieve them from the database and add them to the cache. You may do this using the `Cache::remember` method:
```
1$value = Cache::remember('users', $seconds, function () {2 return DB::table('users')->get();3});
```
If the item does not exist in the cache, the closure passed to the `remember` method will be executed and its result will be placed in the cache.
You may use the `rememberForever` method to retrieve an item from the cache or store it forever if it does not exist:
```
1$value = Cache::rememberForever('users', function () {2 return DB::table('users')->get();3});
```
#### [Stale While Revalidate](https://laravel.com/docs/12.x/cache#swr)
When using the `Cache::remember` method, some users may experience slow response times if the cached value has expired. For certain types of data, it can be useful to allow partially stale data to be served while the cached value is recalculated in the background, preventing some users from experiencing slow response times while cached values are calculated. This is often referred to as the "stale-while-revalidate" pattern, and the `Cache::flexible` method provides an implementation of this pattern.
The flexible method accepts an array that specifies how long the cached value is considered "fresh" and when it becomes "stale". The first value in the array represents the number of seconds the cache is considered fresh, while the second value defines how long it can be served as stale data before recalculation is necessary.
If a request is made within the fresh period (before the first value), the cache is returned immediately without recalculation. If a request is made during the stale period (between the two values), the stale value is served to the user, and a [deferred function](https://laravel.com/docs/12.x/helpers#deferred-functions) is registered to refresh the cached value after the response is sent to the user. If a request is made after the second value, the cache is considered expired, and the value is recalculated immediately, which may result in a slower response for the user:
```
1$value = Cache::flexible('users', [5, 10], function () {2 return DB::table('users')->get();3});
```
#### [Retrieve and Delete](https://laravel.com/docs/12.x/cache#retrieve-delete)
If you need to retrieve an item from the cache and then delete the item, you may use the `pull` method. Like the `get` method, `null` will be returned if the item does not exist in the cache:
```
1$value = Cache::pull('key');23$value = Cache::pull('key', 'default');
```
### [Storing Items in the Cache](https://laravel.com/docs/12.x/cache#storing-items-in-the-cache)
You may use the `put` method on the `Cache` facade to store items in the cache:
```
1Cache::put('key', 'value', $seconds = 10);
```
If the storage time is not passed to the `put` method, the item will be stored indefinitely:
```
1Cache::put('key', 'value');
```
Instead of passing the number of seconds as an integer, you may also pass a `DateTime` instance representing the desired expiration time of the cached item:
```
1Cache::put('key', 'value', now()->plus(minutes: 10));
```
#### [Store if Not Present](https://laravel.com/docs/12.x/cache#store-if-not-present)
The `add` method will only add the item to the cache if it does not already exist in the cache store. The method will return `true` if the item is actually added to the cache. Otherwise, the method will return `false`. The `add` method is an atomic operation:
```
1Cache::add('key', 'value', $seconds);
```
#### [Storing Items Forever](https://laravel.com/docs/12.x/cache#storing-items-forever)
The `forever` method may be used to store an item in the cache permanently. Since these items will not expire, they must be manually removed from the cache using the `forget` method:
```
1Cache::forever('key', 'value');
```
If you are using the Memcached driver, items that are stored "forever" may be removed when the cache reaches its size limit.
### [Removing Items From the Cache](https://laravel.com/docs/12.x/cache#removing-items-from-the-cache)
You may remove items from the cache using the `forget` method:
```
1Cache::forget('key');
```
You may also remove items by providing a zero or negative number of expiration seconds:
```
1Cache::put('key', 'value', 0);23Cache::put('key', 'value', -5);
```
You may clear the entire cache using the `flush` method:
```
1Cache::flush();
```
Flushing the cache does not respect your configured cache "prefix" and will remove all entries from the cache. Consider this carefully when clearing a cache which is shared by other applications.
### [Cache Memoization](https://laravel.com/docs/12.x/cache#cache-memoization)
Laravel's `memo` cache driver allows you to temporarily store resolved cache values in memory during a single request or job execution. This prevents repeated cache hits within the same execution, significantly improving performance.
To use the memoized cache, invoke the `memo` method:
```
1use Illuminate\Support\Facades\Cache;23$value = Cache::memo()->get('key');
```
The `memo` method optionally accepts the name of a cache store, which specifies the underlying cache store the memoized driver will decorate:
```
1// Using the default cache store...2$value = Cache::memo()->get('key');34// Using the Redis cache store...5$value = Cache::memo('redis')->get('key');
```
The first `get` call for a given key retrieves the value from your cache store, but subsequent calls within the same request or job will retrieve the value from memory:
```
1// Hits the cache...2$value = Cache::memo()->get('key');34// Does not hit the cache, returns memoized value...5$value = Cache::memo()->get('key');
```
When calling methods that modify cache values (such as `put`, `increment`, `remember`, etc.), the memoized cache automatically forgets the memoized value and delegates the mutating method call to the underlying cache store:
```
1Cache::memo()->put('name', 'Taylor'); // Writes to underlying cache...2Cache::memo()->get('name'); // Hits underlying cache...3Cache::memo()->get('name'); // Memoized, does not hit cache...45Cache::memo()->put('name', 'Tim'); // Forgets memoized value, writes new value...6Cache::memo()->get('name'); // Hits underlying cache again...
```
### [The Cache Helper](https://laravel.com/docs/12.x/cache#the-cache-helper)
In addition to using the `Cache` facade, you may also use the global `cache` function to retrieve and store data via the cache. When the `cache` function is called with a single, string argument, it will return the value of the given key:
```
1$value = cache('key');
```
If you provide an array of key / value pairs and an expiration time to the function, it will store values in the cache for the specified duration:
```
1cache(['key' => 'value'], $seconds);23cache(['key' => 'value'], now()->plus(minutes: 10));
```
When the `cache` function is called without any arguments, it returns an instance of the `Illuminate\Contracts\Cache\Factory` implementation, allowing you to call other caching methods:
```
1cache()->remember('users', $seconds, function () {2 return DB::table('users')->get();3});
```
When testing calls to the global `cache` function, you may use the `Cache::shouldReceive` method just as if you were [testing the facade](https://laravel.com/docs/12.x/mocking#mocking-facades).
Cache tags are not supported when using the `file`, `dynamodb`, or `database` cache drivers.
### [Storing Tagged Cache Items](https://laravel.com/docs/12.x/cache#storing-tagged-cache-items)
Cache tags allow you to tag related items in the cache and then flush all cached values that have been assigned a given tag. You may access a tagged cache by passing in an ordered array of tag names. For example, let's access a tagged cache and `put` a value into the cache:
```
1use Illuminate\Support\Facades\Cache;23Cache::tags(['people', 'artists'])->put('John', $john, $seconds);4Cache::tags(['people', 'authors'])->put('Anne', $anne, $seconds);
```
### [Accessing Tagged Cache Items](https://laravel.com/docs/12.x/cache#accessing-tagged-cache-items)
Items stored via tags may not be accessed without also providing the tags that were used to store the value. To retrieve a tagged cache item, pass the same ordered list of tags to the `tags` method, then call the `get` method with the key you wish to retrieve:
```
1$john = Cache::tags(['people', 'artists'])->get('John');23$anne = Cache::tags(['people', 'authors'])->get('Anne');
```
### [Removing Tagged Cache Items](https://laravel.com/docs/12.x/cache#removing-tagged-cache-items)
You may flush all items that are assigned a tag or list of tags. For example, the following code would remove all caches tagged with either `people`, `authors`, or both. So, both `Anne` and `John` would be removed from the cache:
```
1Cache::tags(['people', 'authors'])->flush();
```
In contrast, the code below would remove only cached values tagged with `authors`, so `Anne` would be removed, but not `John`:
```
1Cache::tags('authors')->flush();
```
## [Atomic Locks](https://laravel.com/docs/12.x/cache#atomic-locks)
To utilize this feature, your application must be using the `memcached`, `redis`, `dynamodb`, `database`, `file`, or `array` cache driver as your application's default cache driver. In addition, all servers must be communicating with the same central cache server.
### [Managing Locks](https://laravel.com/docs/12.x/cache#managing-locks)
Atomic locks allow for the manipulation of distributed locks without worrying about race conditions. For example, [Laravel Cloud](https://cloud.laravel.com/) uses atomic locks to ensure that only one remote task is being executed on a server at a time. You may create and manage locks using the `Cache::lock` method:
```
1use Illuminate\Support\Facades\Cache;23$lock = Cache::lock('foo', 10);45if ($lock->get()) {6 // Lock acquired for 10 seconds...78 $lock->release();9}
```
The `get` method also accepts a closure. After the closure is executed, Laravel will automatically release the lock:
```
1Cache::lock('foo', 10)->get(function () {2 // Lock acquired for 10 seconds and automatically released...3});
```
If the lock is not available at the moment you request it, you may instruct Laravel to wait for a specified number of seconds. If the lock cannot be acquired within the specified time limit, an `Illuminate\Contracts\Cache\LockTimeoutException` will be thrown:
```
1use Illuminate\Contracts\Cache\LockTimeoutException;23$lock = Cache::lock('foo', 10);45try {6 $lock->block(5);78 // Lock acquired after waiting a maximum of 5 seconds...9} catch (LockTimeoutException $e) {10 // Unable to acquire lock...11} finally {12 $lock->release();13}
```
The example above may be simplified by passing a closure to the `block` method. When a closure is passed to this method, Laravel will attempt to acquire the lock for the specified number of seconds and will automatically release the lock once the closure has been executed:
```
1Cache::lock('foo', 10)->block(5, function () {2 // Lock acquired for 10 seconds after waiting a maximum of 5 seconds...3});
```
### [Managing Locks Across Processes](https://laravel.com/docs/12.x/cache#managing-locks-across-processes)
Sometimes, you may wish to acquire a lock in one process and release it in another process. For example, you may acquire a lock during a web request and wish to release the lock at the end of a queued job that is triggered by that request. In this scenario, you should pass the lock's scoped "owner token" to the queued job so that the job can re-instantiate the lock using the given token.
In the example below, we will dispatch a queued job if a lock is successfully acquired. In addition, we will pass the lock's owner token to the queued job via the lock's `owner` method:
```
1$podcast = Podcast::find($id);23$lock = Cache::lock('processing', 120);45if ($lock->get()) {6 ProcessPodcast::dispatch($podcast, $lock->owner());7}
```
Within our application's `ProcessPodcast` job, we can restore and release the lock using the owner token:
```
1Cache::restoreLock('processing', $this->owner)->release();
```
If you would like to release a lock without respecting its current owner, you may use the `forceRelease` method:
```
1Cache::lock('processing')->forceRelease();
```
### [Concurrency Limiting](https://laravel.com/docs/12.x/cache#concurrency-limiting)
Laravel's atomic lock functionality also provides a few ways to limit concurrent execution of closures. Use `withoutOverlapping` when you want to allow only one running instance across your infrastructure:
```
1Cache::withoutOverlapping('foo', function () {2 // Lock acquired after waiting a maximum of 10 seconds...3});
```
By default, the lock is held until the closure finishes executing, and the method waits up to 10 seconds to acquire the lock. You may customize these values using additional arguments:
```
1Cache::withoutOverlapping('foo', function () {2 // Lock acquired for 120 seconds after waiting a maximum of 5 seconds...3}, lockFor: 120, waitFor: 5);
```
If the lock cannot be acquired within the specified wait time, an `Illuminate\Contracts\Cache\LockTimeoutException` will be thrown.
If you want controlled parallelism, use the `funnel` method to set a maximum number of concurrent executions. The `funnel` method works with any cache driver that supports locks:
```
1Cache::funnel('foo')2 ->limit(3)3 ->releaseAfter(60)4 ->block(10)5 ->then(function () {6 // Concurrency lock acquired...7 }, function () {8 // Could not acquire concurrency lock...9 });
```
The `funnel` key identifies the resource being limited. The `limit` method defines the maximum concurrent executions. The `releaseAfter` method sets a safety timeout in seconds before an acquired slot is automatically released. The `block` method sets how many seconds to wait for an available slot.
If you prefer to handle the timeout via exceptions instead of providing a failure closure, you may omit the second closure. An `Illuminate\Cache\Limiters\LimiterTimeoutException` will be thrown if the lock cannot be acquired within the specified wait time:
```
1use Illuminate\Cache\Limiters\LimiterTimeoutException;23try {4 Cache::funnel('foo')5 ->limit(3)6 ->releaseAfter(60)7 ->block(10)8 ->then(function () {9 // Concurrency lock acquired...10 });11} catch (LimiterTimeoutException $e) {12 // Unable to acquire concurrency lock...13}
```
If you would like to use a specific cache store for the concurrency limiter, you may invoke the `funnel` method on the desired store:
```
1Cache::store('redis')->funnel('foo')2 ->limit(3)3 ->block(10)4 ->then(function () {5 // Concurrency lock acquired using the "redis" store...6 });
```
The `funnel` method requires the cache store to implement the `Illuminate\Contracts\Cache\LockProvider` interface. If you attempt to use `funnel` with a cache store that does not support locks, a `BadMethodCallException` will be thrown.
## [Cache Failover](https://laravel.com/docs/12.x/cache#cache-failover)
The `failover` cache driver provides automatic failover functionality when interacting with the cache. If the primary cache store of the `failover` store fails for any reason, Laravel will automatically attempt to use the next configured store in the list. This is particularly useful for ensuring high availability in production environments where cache reliability is critical.
To configure a failover cache store, specify the `failover` driver and provide an array of store names to attempt in order. By default, Laravel includes an example failover configuration in your application's `config/cache.php` configuration file:
```
1'failover' => [2 'driver' => 'failover',3 'stores' => [4 'database',5 'array',6 ],7],
```
Once you have configured a store that uses the `failover` driver, you will need to set the failover store as your default cache store in your application's `.env` file to make use of the failover functionality:
```
1CACHE_STORE=failover
```
When a cache store operation fails and failover is activated, Laravel will dispatch the `Illuminate\Cache\Events\CacheFailedOver` event, allowing you to report or log that a cache store has failed.
## [Adding Custom Cache Drivers](https://laravel.com/docs/12.x/cache#adding-custom-cache-drivers)
### [Writing the Driver](https://laravel.com/docs/12.x/cache#writing-the-driver)
To create our custom cache driver, we first need to implement the `Illuminate\Contracts\Cache\Store` [contract](https://laravel.com/docs/12.x/contracts). So, a MongoDB cache implementation might look something like this:
```
1<?php23namespace App\Extensions;45use Illuminate\Contracts\Cache\Store;67class MongoStore implements Store8{9 public function get($key) {}10 public function many(array $keys) {}11 public function put($key, $value, $seconds) {}12 public function putMany(array $values, $seconds) {}13 public function increment($key, $value = 1) {}14 public function decrement($key, $value = 1) {}15 public function forever($key, $value) {}16 public function forget($key) {}17 public function flush() {}18 public function getPrefix() {}19}
```
We just need to implement each of these methods using a MongoDB connection. For an example of how to implement each of these methods, take a look at the `Illuminate\Cache\MemcachedStore` in the [Laravel framework source code](https://github.com/laravel/framework). Once our implementation is complete, we can finish our custom driver registration by calling the `Cache` facade's `extend` method:
```
1Cache::extend('mongo', function (Application $app) {2 return Cache::repository(new MongoStore);3});
```
If you're wondering where to put your custom cache driver code, you could create an `Extensions` namespace within your `app` directory. However, keep in mind that Laravel does not have a rigid application structure and you are free to organize your application according to your preferences.
### [Registering the Driver](https://laravel.com/docs/12.x/cache#registering-the-driver)
To register the custom cache driver with Laravel, we will use the `extend` method on the `Cache` facade. Since other service providers may attempt to read cached values within their `boot` method, we will register our custom driver within a `booting` callback. By using the `booting` callback, we can ensure that the custom driver is registered just before the `boot` method is called on our application's service providers but after the `register` method is called on all of the service providers. We will register our `booting` callback within the `register` method of our application's `App\Providers\AppServiceProvider` class:
```
1<?php23namespace App\Providers;45use App\Extensions\MongoStore;6use Illuminate\Contracts\Foundation\Application;7use Illuminate\Support\Facades\Cache;8use Illuminate\Support\ServiceProvider;910class AppServiceProvider extends ServiceProvider11{12 /**13 * Register any application services.14 */15 public function register(): void16 {17 $this->app->booting(function () {18 Cache::extend('mongo', function (Application $app) {19 return Cache::repository(new MongoStore);20 });21 });22 }2324 /**25 * Bootstrap any application services.26 */27 public function boot(): void28 {29 // ...30 }31}
```
The first argument passed to the `extend` method is the name of the driver. This will correspond to your `driver` option in the `config/cache.php` configuration file. The second argument is a closure that should return an `Illuminate\Cache\Repository` instance. The closure will be passed an `$app` instance, which is an instance of the [service container](https://laravel.com/docs/12.x/container).
Once your extension is registered, update the `CACHE_STORE` environment variable or `default` option within your application's `config/cache.php` configuration file to the name of your extension.
## [Events](https://laravel.com/docs/12.x/cache#events)
To execute code on every cache operation, you may listen for various [events](https://laravel.com/docs/12.x/events) dispatched by the cache:
| Event Name |
|---|
| `Illuminate\Cache\Events\CacheFlushed` |
| `Illuminate\Cache\Events\CacheFlushing` |
| `Illuminate\Cache\Events\CacheHit` |
| `Illuminate\Cache\Events\CacheMissed` |
| `Illuminate\Cache\Events\ForgettingKey` |
| `Illuminate\Cache\Events\KeyForgetFailed` |
| `Illuminate\Cache\Events\KeyForgotten` |
| `Illuminate\Cache\Events\KeyWriteFailed` |
| `Illuminate\Cache\Events\KeyWritten` |
| `Illuminate\Cache\Events\RetrievingKey` |
| `Illuminate\Cache\Events\RetrievingManyKeys` |
| `Illuminate\Cache\Events\WritingKey` |
| `Illuminate\Cache\Events\WritingManyKeys` |
To increase performance, you may disable cache events by setting the `events` configuration option to `false` for a given cache store in your application's `config/cache.php` configuration file:
```
1'database' => [2 'driver' => 'database',3 // ...4 'events' => false,5],
``` |
| Shard | 63 (laksa) |
| Root Hash | 5292393658133462863 |
| Unparsed URL | com,laravel!/docs/12.x/cache s443 |