Laravel 中文文档

主题

全部文档

缓存 ​

简介 ​

应用执行的某些数据检索或处理任务可能非常消耗 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 socket 路径。若这样做，应将 port 选项设为 0：

php
'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 ​

storage 缓存驱动允许你将缓存值存储在应用已配置的任意文件系统磁盘上。当你希望将现有磁盘（例如 S3 磁盘）用作键 / 值缓存存储时，这会很有用：

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

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 and Locks 文档。

缓存用法 ​

获取缓存实例 ​

要获取缓存存储实例，可使用 Cache facade，本文将通篇使用它。Cache facade 提供了对 Laravel 缓存契约底层实现的便捷、简洁访问：

php
<?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 [
            // ...
        ];
    }
}

访问多个缓存存储 ​

使用 Cache facade，可通过 store 方法访问各种缓存存储。传给 store 方法的键应对应 cache 配置文件中 stores 配置数组里列出的某个存储：

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

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

从缓存检索条目 ​

Cache facade 的 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
// 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);

检索并存储 ​

有时你希望从缓存检索条目，但在请求的条目不存在时也存储一个默认值。例如，你可能希望从缓存检索所有用户，若不存在则从数据库检索并将它们加入缓存。可使用 Cache::remember 方法做到这一点：

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

若条目不存在于缓存中，将执行传给 remember 方法的闭包，并将其结果放入缓存。

若需要知道条目是从缓存检索的，还是通过执行给定闭包得到的，可使用 rememberWithWarmth 方法。该方法返回一个数组，包含缓存值以及一个布尔值，指示条目是否「热」（即从缓存检索，而非从闭包解析）：

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

可使用 rememberForever 方法从缓存检索条目，若不存在则永久存储：

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

过期后继续提供（Stale While Revalidate） ​

使用 Cache::remember 方法时，若缓存值已过期，部分用户可能会经历较慢的响应时间。对于某些类型的数据，允许在后台重新计算缓存值的同时继续提供部分过期数据会很有用，从而避免部分用户在计算缓存值时经历慢响应。这通常称为「stale-while-revalidate」模式，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 facade 上使用 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');

INFO

若使用 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
// Using the default cache store...
$value = Cache::memo()->get('key');

// Using the Redis cache store...
$value = Cache::memo('redis')->get('key');

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

php
// Hits the cache...
$value = Cache::memo()->get('key');

// Does not hit the cache, returns memoized value...
$value = Cache::memo()->get('key');

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

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

Cache 辅助函数 ​

除了使用 Cache facade，也可使用全局 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();
});

INFO

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

缓存标签 ​

WARNING

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

存储带标签的缓存条目 ​

缓存标签允许你为缓存中的相关条目打标签，然后刷新所有已分配给定标签的缓存值。可通过传入有序的标签名数组来访问带标签的缓存。例如，我们来访问一个被标记为 people 或 authors 的带标签缓存，并将缓存值存入：

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()) {
    // Lock acquired for 10 seconds...

    $lock->release();
}

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

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

若请求锁时锁尚不可用，可指示 Laravel 等待指定秒数。若在指定时限内无法获取锁，将抛出 Illuminate\Contracts\Cache\LockTimeoutException：

php
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 会尝试在指定秒数内获取锁，并在闭包执行完毕后自动释放锁：

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

跨进程管理锁 ​

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

在下例中，若成功获取锁，我们将派发一个队列任务。此外，我们将通过锁的 owner 方法将锁的所有者令牌传给队列任务：

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

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

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

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

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

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

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

刷新锁 ​

若需要延长当前拥有的锁的过期时间，可使用 refresh 方法。若未提供秒数，将使用锁的原始时长。这在长时间运行的进程中很有用，可防止锁在工作完成前过期：

php
$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：

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

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

php
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 方法可与任何支持锁的缓存驱动一起使用：

php
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：

php
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 方法：

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

INFO

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

缓存故障转移 ​

failover 缓存驱动在与缓存交互时提供自动故障转移功能。若 failover 存储的主缓存存储因任何原因失败，Laravel 将自动尝试配置的下一个缓存存储。

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

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

配置好使用 failover 驱动的存储后，需要在应用的 .env 文件中将故障转移存储设为默认缓存存储，以使用故障转移功能：

ini
CACHE_STORE=failover

当缓存存储操作失败并激活故障转移时，Laravel 会派发 Illuminate\Cache\Events\CacheFailedOver 事件，允许你报告或记录某个缓存存储已失败。

添加自定义缓存驱动 ​

编写驱动 ​

要创建自定义缓存驱动，首先需要实现 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。实现完成后，可通过调用 Cache facade 的 extend 方法注册自定义驱动：

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

INFO

若你想知道将自定义缓存驱动代码放在何处，可在 app 目录中创建 Extensions 命名空间。不过请记住，Laravel 没有严格的应用结构，你可按自己的喜好组织应用。

注册驱动 ​

要向 Laravel 注册自定义缓存驱动，我们将使用 Cache facade 上的 extend 方法。由于其他服务提供者可能尝试在其 boot 方法中读取缓存值，我们将在 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
{
    /**
     * 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\Contracts\Cache\Repository 实现的闭包。闭包会传入 $app 实例以及该驱动的配置数组：

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

事件 ​

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

Event Name
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,
],