Laravel 13.x 中文文档

主题

缓存 ​

简介 ​

你的应用程序执行的某些数据检索或处理任务可能是 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 命令创建它：

shell
php artisan make:cache-table

php artisan migrate

Memcached ​

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

php
'memcached' => [
    // ...

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

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

php
'memcached' => [
    // ...

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

Redis ​

在 Laravel 中使用 Redis 缓存之前，你需要通过 PECL 安装 PhpRedis PHP 扩展或通过 Composer 安装 predis/predis 包（~2.0）。Laravel Sail 已包含此扩展。此外，官方 Laravel 应用程序平台如 Laravel Cloud 和 Laravel Forge 默认安装了 PhpRedis 扩展。

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

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 通信：

shell
composer require aws/aws-sdk-php

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

php
'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 门面，这是我们在整个文档中使用的方式。Cache 门面为 Laravel 缓存约定的底层实现提供了方便、简洁的访问：

php
<?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 配置数组中列出的存储之一：

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

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

从缓存中检索项目 ​

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

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

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

你甚至可以传递闭包作为默认值。如果指定项目中不存在于缓存中，闭包的结果将被返回。传递闭包允许你延迟从数据库或其他外部服务检索默认值：

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

确定项目是否存在 ​

has 方法可用于确定项目中是否存在于缓存中。如果项目存在但其值为 null，此方法也将返回 false：

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

递增 / 递减值 ​

increment 和 decrement 方法可用于调整缓存中整数项目的值。这两个方法都接受一个可选的第二个参数，指示项目值递增或递减的数量：

php
// 如果值不存在，则初始化...
Cache::add('key', 0, now()->plus(hours: 4));

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

检索并存储 ​

有时你可能希望从缓存中检索项目，但如果请求的项目不存在，也存储一个默认值。例如，你可能希望从缓存中检索所有用户，或者如果他们不存在，从数据库中检索他们并将他们添加到缓存中。你可以使用 Cache::remember 方法完成此操作：

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

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

你可以使用 rememberForever 方法从缓存中检索项目，或者如果它不存在，则永久存储它：

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

过期时重新验证 ​

使用 Cache::remember 方法时，如果缓存值已过期，某些用户可能会遇到响应时间慢的问题。对于某些类型的数据，在后台重新计算缓存值时允许提供部分过期数据可能很有用，防止某些用户在计算缓存值时遇到响应时间慢的问题。这通常被称为「过期时重新验证」模式，Cache::flexible 方法提供了此模式的实现。

flexible 方法接受一个数组，指定缓存值被视为「新鲜」的时间以及何时变为「过期」。数组中的第一个值表示缓存被视为新鲜的秒数，而第二个值定义在需要重新计算之前可以将其作为过期数据提供的时长。

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

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

检索并删除 ​

如果你需要从缓存中检索项目然后删除该项目，可以使用 pull 方法。与 get 方法一样，如果项目中不存在于缓存中，将返回 null：

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

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

在缓存中存储项目 ​

你可以使用 Cache 门面上的 put 方法在缓存中存储项目：

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

如果未将存储时间传递给 put 方法，项目将被无限期存储：

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

除了传递整数秒数外，你还可以传递表示缓存项目所需过期时间的 DateTime 实例：

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

不存在时存储 ​

add 方法仅在项目尚未存在于缓存存储中时将其添加到缓存中。如果项目实际添加到缓存中，该方法将返回 true。否则，该方法将返回 false。add 方法是一个原子操作：

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

延长项目生命周期 ​

touch 方法允许你延长现有缓存项目的生命周期 (TTL)。如果缓存项目存在且其过期时间成功延长，touch 方法将返回 true。如果项目中不存在于缓存中，该方法将返回 false：

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

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

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

永久存储项目 ​

forever 方法可用于将项目永久存储在缓存中。由于这些项目不会过期，必须使用 forget 方法手动从缓存中删除它们：

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

NOTE

如果你使用 Memcached 驱动程序，当缓存达到其大小限制时，「永久」存储的项目可能会被删除。

从缓存中删除项目 ​

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

php
Cache::forget('key');

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

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

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

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

php
Cache::flush();

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

php
Cache::flushLocks();

WARNING

清除缓存不会遵守你配置的缓存「前缀」，并将从缓存中删除所有条目。在清除由其他应用程序共享的缓存时，请仔细考虑这一点。

缓存记忆化 ​

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

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

php
use Illuminate\Support\Facades\Cache;

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

memo 方法可选地接受缓存存储的名称，指定记忆化驱动程序将装饰的底层缓存存储：

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

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

给定键的第一次 get 调用从缓存存储中检索值，但在同一请求或任务中的后续调用将从内存中检索值：

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

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

当调用修改缓存值的方法（如 put、increment、remember 等）时，记忆化缓存会自动忘记记忆化值并将修改方法调用委托给底层缓存存储：

php
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 函数时，它将返回给定键的值：

php
$value = cache('key');

如果你向函数提供键/值对数组和过期时间，它将在指定持续时间内将值存储在缓存中：

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

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

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

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

NOTE

测试全局 cache 函数的调用时，可以使用 Cache::shouldReceive 方法，就像测试门面一样。

缓存标签 ​

WARNING

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

存储带标签的缓存项目 ​

缓存标签允许你在缓存中标记相关项目，然后刷新所有已分配给定标签的缓存值。你可以通过传入有序的标签名称数组来访问带标签的缓存。例如，让我们访问一个带标签的缓存并将值 put 到缓存中：

php
use Illuminate\Support\Facades\Cache;

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

访问带标签的缓存项目 ​

通过标签存储的项目如果不提供用于存储值的标签，则无法访问。要检索带标签的缓存项目，请将相同的有序标签列表传递给 tags 方法，然后使用你希望检索的键调用 get 方法：

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

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

删除带标签的缓存项目 ​

你可以刷新分配给一个标签或标签列表的所有项目。例如，以下代码将删除所有标记为 people、authors 或两者的缓存。因此，Anne 和 John 都将从缓存中删除：

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

相反，以下代码将仅删除标记为 authors 的缓存值，因此 Anne 将被删除，但 John 不会：

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

原子锁 ​

WARNING

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

管理锁 ​

原子锁允许操作分布式锁而无需担心竞争条件。例如，Laravel Cloud 使用原子锁确保一次只有一个远程任务在服务器上执行。你可以使用 Cache::lock 方法创建和管理锁：

php
use Illuminate\Support\Facades\Cache;

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

if ($lock->get()) {
    // 锁定获取 10 秒...

    $lock->release();
}

get 方法也接受闭包。闭包执行后，Laravel 将自动释放锁：

php
Cache::lock('foo', 10)->get(function () {
    // 锁定获取 10 秒并自动释放...
});

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

php
use Illuminate\Contracts\Cache\LockTimeoutException;

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

try {
    $lock->block(5);

    // 等待最多 5 秒后获取锁...
} catch (LockTimeoutException $e) {
    // 无法获取锁...
} finally {
    $lock->release();
}

你可以通过将闭包传递给 block 方法来简化此示例。当闭包传递给此方法时，Laravel 将在指定秒数内尝试获取锁，并在闭包执行后自动释放锁：

php
Cache::lock('foo', 10)->block(5, function () {
    // 等待最多 5 秒后获取锁...
});

如果锁不存在，restore 方法可用于重新创建锁：

php
$lock = Cache::restoreLock('foo', $lock->owner());

if ($lock->get()) {
    // 锁定获取...
}

跨进程管理锁 ​

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

php
// 控制器中...
$podcast = Podcast::find($id);

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

if ($result = $lock->get()) {
    // 锁定获取...

    // 将所有者令牌传递给队列任务...
    ProcessPodcast::dispatch($podcast, $lock->owner());
}

// 队列任务中...
Cache::restoreLock('foo', $this->owner)->release();

如果你想在不尊重当前所有者的情况下释放锁，可以使用 forceRelease 方法：

php
Cache::lock('foo')->forceRelease();

并发限制 ​

Laravel 的原子锁功能可用于限制并发任务的执行。例如，假设你的应用程序正在与第三方 API 交互，该 API 每分钟只允许 100 个请求。你可以使用原子锁限制此速率。

在尝试执行任务之前，你应该尝试获取与 API 限制对应的锁。例如，如果你每分钟只允许 100 个请求，则锁的 TTL 应为 60 秒：

php
use Illuminate\Support\Facades\Cache;

$lock = Cache::lock('api-limit', 60);

if ($lock->get()) {
    // 锁定获取，可以执行任务...
} else {
    // 无法获取锁，必须等待...
}

或者，你可以使用 block 方法等待锁变得可用：

php
use Illuminate\Support\Facades\Cache;

$lock = Cache::lock('api-limit', 60);

try {
    $lock->block(5);

    // 锁定获取，可以执行任务...
} catch (\Illuminate\Contracts\Cache\LockTimeoutException $e) {
    // 无法在 5 秒内获取锁...
} finally {
    $lock->release();
}

缓存故障转移 ​

如果你的应用程序配置了多个缓存存储，你可以利用 Laravel 的缓存故障转移功能。当配置的缓存存储不可用时，Laravel 将自动尝试使用下一个可用的存储。

要配置缓存故障转移，你应该在应用程序的 config/cache.php 配置文件中定义一个使用 failover 驱动程序的新存储。failover 存储的 stores 配置选项应包含在主存储不可用时应使用的存储名称数组：

php
'stores' => [
    // ...

    'failover' => [
        'driver' => 'failover',
        'stores' => ['redis', 'database', 'file'],
    ],
],

配置故障转移存储后，你可以将 CACHE_STORE 环境变量或 config/cache.php 配置文件中的 default 选项设置为故障转移存储的名称：

env
CACHE_STORE=failover

添加自定义缓存驱动程序 ​

编写驱动程序 ​

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

php
<?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() {}
}

我们只需要使用 MongoDB 连接实现这些方法。有关如何实现这些方法的示例，请查看 Laravel 框架源代码中的 Illuminate\Cache\MemcachedStore。

一旦契约实现完成，我们就可以完成自定义驱动程序注册：

php
use App\Extensions\MongoStore;
use Illuminate\Support\Facades\Cache;

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

NOTE

如果你不确定将自定义缓存驱动程序代码放在哪里，可以在 app/Extensions 目录中创建一个 Extensions 命名空间。但是，Laravel 没有严格的目录结构，你可以根据应用程序需要组织代码。

注册驱动程序 ​

要向 Laravel 注册自定义缓存驱动程序，我们将使用 Cache 门面上的 extend 方法。由于其他服务提供者可能会在其 boot 方法中读取缓存值，我们将在 booting 回调中注册扩展。这确保在应用程序的服务提供者调用 boot 方法之前，自定义缓存驱动程序已注册。我们将在应用程序的 App\Providers\AppServiceProvider 类中注册扩展：

php
<?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
{
    /**
     * 注册任何应用程序服务。
     */
    public function register(): void
    {
        $this->app->booting(function () {
             Cache::extend('mongo', function (Application $app) {
                 return Cache::repository(new MongoStore);
             });
         });
    }

    /**
     * 引导任何应用程序服务。
     */
    public function boot(): void
    {
        // ...
    }
}

传递给 extend 方法的第一个参数是驱动程序的名称。这将对应于 config/cache.php 配置文件中的 driver 选项。第二个参数是应返回 Illuminate\Cache\Repository 实例的闭包。闭包将传递一个 $app 实例，它是服务容器的实例。

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

事件 ​

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

事件名称
Illuminate\Cache\Events\CacheFlushed
Illuminate\Cache\Events\CacheFlushing
Illuminate\Cache\Events\CacheFlushFailed
Illuminate\Cache\Events\CacheLocksFlushed
Illuminate\Cache\Events\CacheLocksFlushing
Illuminate\Cache\Events\CacheLocksFlushFailed
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

为了提高性能，你可以在应用程序的 config/cache.php 配置文件中将给定缓存存储的 events 配置选项设置为 false 来禁用缓存事件：

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