缓存

简介

应用程序执行的一些数据检索或处理任务可能占用大量 CPU 资源，或者需要数秒才能完成。当出现这种情况时，通常会临时缓存检索到的数据，以便在后续请求相同数据时能够快速获取。缓存的数据通常存储在非常快速的数据存储中，例如Memcached或Redis。

幸运的是，Laravel 为各种缓存后端提供了富有表现力的统一 API，让你能够利用它们极快的数据检索速度，从而提升 Web 应用程序的性能。

配置

应用程序的缓存配置文件位于config/cache.php。在该文件中，你可以指定整个应用程序默认使用的缓存存储方式。Laravel 开箱即用，支持流行的缓存后端，如Memcached、Redis、DynamoDB、关系型数据库以及文件系统磁盘。此外，还提供了基于文件的缓存驱动，而array和null缓存驱动则为自动化测试提供了便捷的缓存后端。

缓存配置文件还包含许多其他选项，你可以逐一查看。默认情况下，Laravel 配置使用database缓存驱动，它会将序列化后的缓存对象存储在应用程序的数据库中。

驱动前提条件

数据库

当使用database缓存驱动时，你需要一个数据库表来存储缓存数据。通常，该表包含在 Laravel 默认的0001_01_01_000001_create_cache_table.php 数据库迁移文件中；不过，如果你的应用程序不包含此迁移文件，可以使用make:cache-table Artisan 命令来创建：

php artisan make:cache-table

php artisan migrate

Memcached

使用 Memcached 驱动需要安装Memcached PECL 包。你可以在config/cache.php配置文件中列出所有 Memcached 服务器。该文件已包含一个memcached.servers条目，可供你参考使用：

'memcached' => [
    // ...

    'servers' => [
        [
            'host' => env('MEMCACHED_HOST', '127.0.0.1'),
            'port' => env('MEMCACHED_PORT', 11211),
            'weight' => 100,
        ],
    ],
],

如有需要，你可以将host选项设置为 UNIX 套接字路径。如果这样做，port选项应设置为0：

'memcached' => [
    // ...

    'servers' => [
        [
            'host' => '/var/run/memcached/memcached.sock',
            'port' => 0,
            'weight' => 100
        ],
    ],
],

Redis

在 Laravel 中使用 Redis 缓存之前，你需要通过 PECL 安装 PhpRedis PHP 扩展，或者通过 Composer 安装predis/predis包。Laravel Sail已内置此扩展。此外，像Laravel Cloud和Laravel Forge这类官方 Laravel 应用平台，默认也已安装 PhpRedis 扩展。

有关 Redis 配置的更多信息，请查阅其Laravel 文档页面。

存储

storage缓存驱动允许你将缓存值存储到应用程序配置的任何文件系统磁盘中。当你想将现有的磁盘（如 S3 磁盘）用作键/值缓存存储时，这非常有用：

'storage' => [
    'driver' => 'storage',
    'disk' => env('CACHE_STORAGE_DISK'),
    'path' => env('CACHE_STORAGE_PATH', 'framework/cache/data'),
],

DynamoDB

在使用DynamoDB缓存驱动之前，你必须创建一个 DynamoDB 表来存储所有缓存数据。通常，该表应命名为cache。不过，你应该根据cache配置文件中stores.dynamodb.table配置项的值来命名该表。表名也可以通过DYNAMODB_CACHE_TABLE环境变量进行设置。

该表还应包含一个字符串类型的分区键，其名称需与应用程序cache配置文件中stores.dynamodb.attributes.key配置项的值相对应。默认情况下，分区键应命名为key。

通常，DynamoDB 不会主动从表中移除过期项。因此，你应该在表上启用生存时间（TTL）功能。配置表的 TTL 设置时，应将 TTL 属性名称设置为expires_at。

接下来，安装 AWS SDK，以便你的 Laravel 应用程序能够与 DynamoDB 进行通信：

composer require aws/aws-sdk-php

此外，你应确保为 DynamoDB 缓存存储配置项提供了相应的值。通常，像AWS_ACCESS_KEY_ID和AWS_SECRET_ACCESS_KEY这类选项，应在应用程序的.env配置文件中定义：

'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

如果你使用 MongoDB，官方的mongodb/laravel-mongodb包提供了一个mongodb缓存驱动，可通过mongodb数据库连接进行配置。MongoDB 支持 TTL 索引，可用于自动清除过期的缓存项。

有关 MongoDB 配置的更多信息，请参阅 MongoDB 缓存与锁文档。

缓存使用

获取缓存实例

要获取缓存存储实例，可以使用Cache门面（Facade），这也是本文档全程采用的方式。Cache门面为 Laravel 缓存契约的底层实现提供了便捷且简洁的访问方式：

<?php

namespace App\Http\Controllers;

use Illuminate\Support\Facades\Cache;

class UserController extends Controller
{
    /**
     * 显示应用程序的所有用户列表。
     */
    public function index(): array
    {
        $value = Cache::get('key');

        return [
            // ...
        ];
    }
}

访问多个缓存存储

通过Cache门面，你可以使用store方法访问不同的缓存存储。传递给store方法的键应与cache配置文件中stores配置数组所列出的存储之一相对应：

$value = Cache::store('file')->get('foo');

Cache::store('redis')->put('bar', 'baz', 600); // 10 分钟

从缓存中检索项

Cache门面的get方法用于从缓存中检索项。如果该项在缓存中不存在，则返回null。如果需要，你可以向get方法传入第二个参数，指定当项不存在时希望返回的默认值：

$value = Cache::get('key');

$value = Cache::get('key', 'default');

你甚至可以传入一个闭包作为默认值。如果指定的项在缓存中不存在，将返回该闭包的执行结果。传入闭包可以延迟从数据库或其他外部服务检索默认值的操作：

$value = Cache::get('key', function () {
    return DB::table(/* ... */)->get();
});

判断项是否存在

可以使用has方法判断某项是否存在于缓存中。如果该项存在但值为null，该方法也会返回false：

if (Cache::has('key')) {
    // ...
}

递增 / 递减值

可以使用increment和decrement方法调整缓存中整型项的值。这两个方法都接受一个可选的第二个参数，用于指定对该值进行递增或递减的幅度：

// 若值不存在则进行初始化……
Cache::add('key', 0, now()->plus(hours: 4));

// 递增或递减值……
Cache::increment('key');
Cache::increment('key', $amount);
Cache::decrement('key');
Cache::decrement('key', $amount);

检索与存储

有时你可能需要从缓存中获取某个项，但若请求的项不存在时，还想同时存储一个默认值。例如，你可能想从缓存中获取所有用户，若不存在则从数据库中获取并添加到缓存中。你可以使用 Cache::remember 方法来实现这一点：

$value = Cache::remember('users', $seconds, function () {
    return DB::table('users')->get();
});

如果缓存中不存在该项，传递给 remember 方法的闭包将被执行，其结果将存入缓存。

若需要判断某个项是从缓存中获取的，而非通过执行给定闭包得到的，可以使用 rememberWithWarmth 方法。该方法返回一个数组，其中包含缓存的值以及一个布尔值，用于表示该项是否“热”，即它是否从缓存中获取，而非通过闭包解析得到：

[$value, $warm] = Cache::rememberWithWarmth('users', $seconds, function () {
    return DB::table('users')->get();
});

你可以使用 rememberForever 方法从缓存中获取某个项，若不存在则将其永久存储：

$value = Cache::rememberForever('users', function () {
    return DB::table('users')->get();
});

先返回旧值再更新（Stale While Revalidate）

使用 Cache::remember 方法时，若缓存值已过期，部分用户可能会遇到响应缓慢的情况。对于某些类型的数据，允许在后台重新计算缓存值的同时，提供部分过期的数据是很有用的，这样可避免部分用户在缓存值计算期间遇到缓慢的响应。这通常被称为“先返回旧值再更新”模式，而 Cache::flexible 方法提供了该模式的实现。

flexible 方法接收一个数组，用于指定缓存值被视为“新鲜”的时长以及何时变为“过期”。数组中的第一个值表示缓存被视为新鲜的秒数，第二个值则定义在需要重新计算之前，该数据可作为过期数据提供的时间。

如果在新鲜期内（第一个值之前）发起请求，会立即返回缓存，无需重新计算。如果在过期期内（两个值之间）发起请求，会向用户返回过期值，并注册一个延迟函数，在响应发送给用户后刷新缓存值。如果在第二个值之后发起请求，缓存被视为已过期，会立即重新计算该值，这可能会导致用户响应变慢：

$value = Cache::flexible('users', [5, 10], function () {
    return DB::table('users')->get();
});

获取并删除

如果你需要从缓存中获取某个项，之后再将其删除，可以使用 pull 方法。与 get 方法类似，若缓存中不存在该项，将返回 null：

$value = Cache::pull('key');

$value = Cache::pull('key', 'default');

向缓存中存储项

你可以使用 Cache 外观（Facade）的 put 方法向缓存中存储项：

Cache::put('key', 'value', $seconds = 10);

如果未将存储时长传递给 put 方法，该缓存项将被永久存储：

Cache::put('key', 'value');

除了以整数形式传递秒数外，你还可以传递一个代表缓存项预期过期时间的 DateTime 实例：

Cache::put('key', 'value', now()->plus(minutes: 10));

仅在不存在时存储

add 方法仅会在缓存中不存在该缓存项时，才将其添加到缓存中。若该缓存项确实被添加到缓存中，该方法会返回 true，否则返回 false。add 方法是原子操作：

Cache::add('key', 'value', $seconds);

延长项的有效期

touch 方法允许你延长已有缓存项的生命周期（TTL）。若缓存项存在且成功延长了过期时间，touch 方法会返回 true。若缓存中不存在该缓存项，该方法会返回 false：

Cache::touch('key', 3600);

你可以提供一个 DateTimeInterface、DateInterval 或 Carbon 实例，来指定确切的过期时间：

Cache::touch('key', now()->addHours(2));

永久存储项

forever 方法可用于将某个缓存项永久存储到缓存中。由于这些项不会过期，因此必须使用 forget 方法手动将其从缓存中移除：

Cache::forever('key', 'value');

如果你使用的是 Memcached 驱动，当缓存达到大小限制时，“永久”存储的项可能会被移除。

从缓存中移除项

你可以使用 forget 方法从缓存中移除项：

Cache::forget('key');

你也可以通过提供零或负数的过期秒数来移除项：

Cache::put('key', 'value', 0);

Cache::put('key', 'value', -5);

你可以使用 flush 方法清空整个缓存：

Cache::flush();

你可以使用 flushLocks 方法清除缓存中的所有原子锁：

Cache::flushLocks();

清空缓存时不会考虑你配置的缓存“前缀”，会删除缓存中的所有条目。在清空与其他应用程序共享的缓存时，请谨慎操作。

缓存记忆化

Laravel 的 memo 缓存驱动允许你在单个请求或任务执行期间，将解析后的缓存值临时存储在内存中。这可以避免在同一次执行中重复命中缓存，从而显著提升性能。

若要使用记忆化缓存，请调用 memo 方法：

use Illuminate\Support\Facades\Cache;

$value = Cache::memo()->get('key');

memo 方法可选择接收一个缓存存储的名称，用于指定记忆化驱动将装饰的基础缓存存储：

// 使用默认缓存存储……
$value = Cache::memo()->get('key');

// 使用 Redis 缓存存储……
$value = Cache::memo('redis')->get('key');

对于给定的键，首次调用 get 会从缓存存储中获取值，而在相同请求或任务内的后续调用则会从内存中获取值：

// 命中缓存……
$value = Cache::memo()->get('key');

// 不再命中缓存，返回记忆化的值……
$value = Cache::memo()->get('key');

当调用修改缓存值的方法（如 put、increment、remember 等）时，记忆化缓存会自动清除记忆化的值，并将变更方法调用委托给基础缓存存储：

Cache::memo()->put('name', 'Taylor'); // 写入基础缓存……
Cache::memo()->get('name');           // 命中基础缓存……
Cache::memo()->get('name');           // 已记忆化，不命中缓存……

Cache::memo()->put('name', 'Tim');    // 清除记忆化值，写入新值……
Cache::memo()->get('name');           // 再次命中基础缓存……

缓存助手

除了使用 Cache 外观，你还可以使用全局 cache 函数通过缓存获取和存储数据。当 cache 函数仅传入一个字符串参数时，会返回给定键对应的值：

$value = cache('key');

如果你向该函数传入键/值对数组和过期时间，它会在指定时长内将值存储到缓存中：

cache(['key' => 'value'], $seconds);

cache(['key' => 'value'], now()->plus(minutes: 10));

当不传入任何参数调用 cache 函数时，它会返回 Illuminate\Contracts\Cache\Factory 的实现实例，从而允许你调用其他缓存方法：

cache()->remember('users', $seconds, function () {
    return DB::table('users')->get();
});

在测试对全局 cache 函数的调用时，你可以像测试外观（Facade）那样，使用 Cache::shouldReceive 方法。

缓存标签

使用 file、dynamodb、database 或 storage 缓存驱动时，不支持缓存标签。

存储带标签的缓存项

缓存标签允许你为缓存中的相关项添加标签，随后可清除所有被赋予了指定标签的缓存值。你可以传入一组有序的标签名来访问带标签的缓存。例如，下面将访问带标签的缓存并使用 put 向缓存中写入一个值：

use Illuminate\Support\Facades\Cache;

Cache::tags(['people', 'artists'])->put('John', $john, $seconds);
Cache::tags(['people', 'authors'])->put('Anne', $anne, $seconds);

访问带标签的缓存项

通过标签存储的项，在访问时必须同时提供用于存储该值的标签，否则无法访问。要检索带标签的缓存项，需向 tags 方法传入相同的有序标签列表，然后调用 get 方法并传入你想要检索的键：

$john = Cache::tags(['people', 'artists'])->get('John');

$anne = Cache::tags(['people', 'authors'])->get('Anne');

移除带标签的缓存项

你可以清除所有被赋予某个标签或一组标签的项。例如，下面的代码会移除所有带有 people、authors 或两者兼具的缓存，因此 Anne 和 John 都会从缓存中被移除：

Cache::tags(['people', 'authors'])->flush();

与此相反，下面的代码只会移除带有 authors 标签的缓存值，因此会移除 Anne，但不会移除 John：

Cache::tags('authors')->flush();

原子锁

要使用此功能，你的应用必须将 memcached、redis、dynamodb、database、file 或 array 缓存驱动作为应用的默认缓存驱动。此外，所有服务器都必须与同一台中央缓存服务器进行通信。

管理锁

原子锁可在无需担心竞态条件的情况下对分布式锁进行操作。例如，Laravel Cloud 使用原子锁来确保服务器上每次只执行一个远程任务。你可以使用 Cache::lock 方法来创建和管理锁：

use Illuminate\Support\Facades\Cache;

$lock = Cache::lock('foo', 10);

if ($lock->get()) {
    // Lock acquired for 10 seconds...

    $lock->release();
}

get 方法也支持传入闭包。闭包执行完毕后，Laravel 会自动释放锁：

Cache::lock('foo', 10)->get(function () {
    // Lock acquired for 10 seconds and automatically released...
});

如果在请求锁时锁不可用，你可以让 Laravel 等待指定的秒数。如果在指定时间范围内无法获取锁，则会抛出 Illuminate\Contracts\Cache\LockTimeoutException：

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();
}

上面的例子可以通过向 block 方法传入闭包来简化。当向该方法传入闭包时，Laravel 会尝试在指定的秒数内获取锁，并在闭包执行完成后自动释放锁：

Cache::lock('foo', 10)->block(5, function () {
    // Lock acquired for 10 seconds after waiting a maximum of 5 seconds...
});

跨进程管理锁

有时你可能希望在一个进程中获取锁，在另一个进程中释放它。例如，你可能在一次 Web 请求期间获取锁，并希望在该请求触发的队列任务结束时释放锁。在这种情况下，你应该将锁的作用域“owner token（所有者令牌）”传递给队列任务，以便该任务可以使用给定的令牌重新实例化锁。

在下面的例子中，如果成功获取锁，我们将派发一个队列任务。同时，我们会通过锁的 owner 方法将锁的所有者令牌传递给队列任务：

$podcast = Podcast::find($id);

$lock = Cache::lock('processing', 120);

if ($lock->get()) {
    ProcessPodcast::dispatch($podcast, $lock->owner());
}

在应用的 ProcessPodcast 任务中，我们可以使用所有者令牌恢复并释放锁：

Cache::restoreLock('processing', $this->owner)->release();

如果你希望在不考虑当前所有者的情况下释放锁，可以使用 forceRelease 方法：

Cache::lock('processing')->forceRelease();

刷新锁

如果你需要延长当前持有锁的过期时间，可以使用 refresh 方法。如果不提供秒数，则会使用锁的原始时长。这对于长时间运行的操作非常有用，此时你更倾向于获取一个较短的锁并周期性地延长它，而不是获取一个过期时间非常长的锁：

$lock = Cache::lock('generate-reports', 60);

if ($lock->get()) {
    foreach ($reports as $report) {
        $report->generate();

        // Extend the lock for another 60 seconds...
        $lock->refresh();
    }

    $lock->release();
}

并发限制

Laravel 的原子锁功能还提供了几种限制闭包并发执行的方式。当你希望在整个基础架构中只允许一个正在运行的实例时，请使用 withoutOverlapping：

Cache::withoutOverlapping('foo', function () {
    // Lock acquired after waiting a maximum of 10 seconds...
});

默认情况下，锁会一直持有直到闭包执行完成，该方法最多等待 10 秒来获取锁。你可以使用额外的参数来自定义这些值：

Cache::withoutOverlapping('foo', function () {
    // Lock acquired for 120 seconds after waiting a maximum of 5 seconds...
}, lockFor: 120, waitFor: 5);

如果在指定的等待时间内无法获取锁，则会抛出 Illuminate\Contracts\Cache\LockTimeoutException。

如果你想要可控的并行度，可使用 funnel 方法设置并发执行的最大数量。funnel 方法适用于任何支持锁的缓存驱动：

Cache::funnel('foo')
    ->limit(3)
    ->releaseAfter(60)
    ->block(10)
    ->then(function () {
        // Concurrency lock acquired...
    }, function () {
        // Could not acquire concurrency lock...
    });

funnel 键用于标识受限制的资源。limit 方法用于定义最大并发执行数量。releaseAfter 方法用于设置一个以秒为单位的安全超时时间，在获取到的槽位被自动释放之前生效。block 方法用于设置等待可用槽位的秒数。

如果你更倾向于通过异常来处理超时，而不是提供失败闭包，可以省略第二个闭包。如果在指定的等待时间内无法获取锁，则会抛出 Illuminate\Cache\Limiters\LimiterTimeoutException：

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

如果你想为并发限制器使用特定的缓存存储，可以在所需的存储上调用 funnel 方法：

Cache::store('redis')->funnel('foo')
    ->limit(3)
    ->block(10)
    ->then(function () {
        // Concurrency lock acquired using the "redis" store...
    });

funnel 方法要求缓存存储实现 Illuminate\Contracts\Cache\LockProvider 接口。如果你尝试对不支持锁的缓存存储使用 funnel，则会抛出 BadMethodCallException。

缓存故障转移

failover 缓存驱动在与缓存交互时提供自动故障转移功能。如果 failover 存储的主缓存存储因任何原因发生故障，Laravel 会自动尝试使用列表中的下一个已配置存储。这对于在缓存可靠性至关重要的生产环境中确保高可用性特别有用。

要配置故障转移缓存存储，请指定 failover 驱动，并提供一个按顺序尝试的存储名称数组。默认情况下，Laravel 会在应用的 config/cache.php 配置文件中包含一个示例故障转移配置：

'failover' => [
    'driver' => 'failover',
    'stores' => [
        'database',
        'array',
    ],
],

一旦配置了使用 failover 驱动的缓存存储，你就需要在你的应用程序 .env 文件中将故障转移存储设置为默认缓存存储，以使用故障转移功能：

CACHE_STORE=failover

当缓存存储操作失败并激活故障转移时，Laravel 会触发 Illuminate\Cache\Events\CacheFailedOver 事件，让你能够报告或记录缓存存储已发生故障。

添加自定义缓存驱动

编写驱动

要创建自定义缓存驱动，我们首先需要实现 Illuminate\Contracts\Cache\Store 契约。因此，MongoDB 缓存的实现可能如下所示：

<?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 touch($key, $seconds) {}
    public function forget($key) {}
    public function flush() {}
    public function getPrefix() {}
}

我们只需使用 MongoDB 连接实现这些方法即可。关于如何实现这些方法的示例，可参考 Laravel 框架源码中的 Illuminate\Cache\MemcachedStore。完成实现后，可通过调用 Cache 外观的 extend 方法完成自定义驱动的注册：

Cache::extend('mongo', function (Application $app) {
    return Cache::repository(new MongoStore);
});

如果你不确定自定义缓存驱动代码应放在何处，可以在 app 目录中创建 Extensions 命名空间。不过，请记住，Laravel 并没有严格的应用结构，你可以根据自身偏好自由组织应用结构。

注册驱动

要在 Laravel 中注册自定义缓存驱动，我们将使用 Cache 外观的 extend 方法。由于其他服务提供者可能会在其 boot 方法中尝试读取缓存值，我们将在 booting 回调中注册自定义驱动。通过使用 booting 回调，可以确保自定义驱动在所有服务提供者的 register 方法执行后、应用服务提供者的 boot 方法执行前完成注册。我们将在应用的 App\Providers\AppServiceProvider 类的 register 方法中注册此 booting 回调：

<?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
    {
        // ...
    }
}

传递给 extend 方法的第一个参数是驱动名称，该名称需与 config/cache.php 配置文件中的 driver 选项相对应。第二个参数是一个闭包，该闭包应返回一个 Illuminate\Cache\Repository 实例。闭包会接收一个 $app 实例，该实例是 服务容器的实例。

扩展注册完成后，将应用程序 config/cache.php 配置文件中的 CACHE_STORE 环境变量或 default 选项更新为扩展的名称。

事件

若要在每次缓存操作时执行代码，你可以监听缓存触发的各类 事件：

若要提升性能，可在应用程序 config/cache.php 配置文件中，为指定缓存存储将 events 配置选项设为 false，从而禁用缓存事件：

'database' => [
    'driver' => 'database',
    // ...
    'events' => false,
],