缓存

• 介绍
• 配置
  • 驱动程序先决条件
• 缓存使用
  • 获取缓存实例
  • 从缓存中检索项目
  • 在缓存中存储项目
  • 从缓存中移除项目
  • 缓存记忆化
  • 缓存助手
• 缓存标签
• 原子锁
  • 管理锁
  • 管理跨进程的锁
• 缓存故障转移
• 添加自定义缓存驱动
  • 编写驱动程序
  • 注册驱动程序
• 事件

引言

您的应用程序执行的某些数据检索或处理任务可能占用大量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 软件包 (~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 通信:

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 缓存驱动由官方的 mongodb/laravel-mongodb 包提供， 并且可以使用一个 mongodb 数据库连接进行配置。 MongoDB 支持 TTL 索引， 可用于自动清除过期缓存项。

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

缓存使用

获取缓存实例

要获取缓存存储实例，你可以使用 Cache 门面，这也是我们在整个文档中将使用的。Cache 门面提供了方便、简洁的访问方式，用于访问 Laravel 缓存契约的底层实现：

<?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 门面，你可以通过 store 方法访问各种缓存存储。传递给 store 方法的键应与 stores 配置数组中列出的存储之一对应，位于你的 cache 配置文件中：

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

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

从缓存中获取项

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 方法可用于调整缓存中整数项的值。这两个方法都接受一个可选的第二个参数，用于指示递增或递减该项值的数量：

// Initialize the value if it does not exist...
Cache::add('key', 0, now()->addHours(4));

// Increment or decrement the value...
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 方法的闭包将被执行，其结果将被放入缓存。

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

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

陈旧时重新验证

当使用 Cache::remember 方法时，如果缓存值已过期，一些用户可能会遇到响应时间慢的情况。对于某些类型的数据，允许在后台重新计算缓存值的同时提供部分过期数据会很有用，这可以防止一些用户在缓存值计算期间遇到响应时间慢的情况。这通常被称为“stale-while-revalidate”模式，而 Cache::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 门面上的 put 方法来将数据项存储到缓存中：

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

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

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

除了传递秒数作为整数外，您还可以传递一个 DateTime 实例，表示缓存项的预期过期时间:

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

若不存在则存储

该add方法只会将该项添加到缓存中，如果它在缓存存储中尚不存在。该方法将返回true，如果该项确实已添加到缓存中。否则，该方法将返回false。该add方法是一个原子操作：

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

永久存储项目

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

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

[!注意]
如果您正在使用 Memcached 驱动程序，当缓存达到其大小限制时，“永久”存储的条目可能会被移除。

从缓存中移除项目

您可以使用 forget 方法从缓存中移除项目:

Cache::forget('key');

您还可以通过提供零或负数的过期秒数来移除项目：

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

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

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

Cache::flush();

[!WARNING]
清除缓存不遵循您配置的缓存“前缀”，并将从缓存中移除所有条目。当清除与其他应用程序共享的缓存时，请务必仔细考虑。

缓存记忆化

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

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

use Illuminate\Support\Facades\Cache;

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

memo 方法可选接受一个缓存存储的名称，它指定了备忘录化驱动将装饰的底层缓存存储：

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

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

第一次 get 调用对于给定的键会从您的缓存存储中获取值，但同一请求或作业中的后续调用将从内存中获取值：

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

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

当调用修改缓存值的方法时 (例如 put、increment、remember 等)，备忘录化缓存会自动忘记已备忘录化的值，并将修改方法调用委托给底层的缓存存储：

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 facade 外，你还可以使用全局 cache 函数来通过缓存检索和存储数据。当 cache 函数带有一个单个字符串参数被调用时，它将返回给定键的值：

$value = cache('key');

如果您向该函数提供一个键/值对数组和一个过期时间，它会将值在缓存中存储指定的持续时间：

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

cache(['key' => 'value'], now()->addMinutes(10));

当 cache 函数在不带任何参数的情况下被调用时,它会返回一个 Illuminate\Contracts\Cache\Factory 实现的实例,允许你调用其他缓存方法:

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

[!NOTE]
在测试对全局 cache 函数的调用时，你可以使用 Cache::shouldReceive 方法，就像 测试门面 一样。

缓存标签

[!WARNING]
缓存标签在使用 file、dynamodb 或 database 缓存驱动程序时不受支持。

存储标记的缓存项

缓存标签允许您在缓存中标记相关项，然后清除所有已分配给定标签的缓存值。您可以通过传入标签名称的有序数组来访问带标签的缓存。例如，让我们访问一个带标签的缓存并 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();

原子锁

[!WARNING]
要使用此功能，您的应用程序必须使用 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...
});

管理跨进程锁

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

在下面的例子中，如果成功获取到锁，我们将分派一个排队作业。此外，我们将通过锁的 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();

缓存故障转移

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

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

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

一旦你配置了一个使用 failover 驱动的存储，你可能需要将 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 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);
});

[!NOTE]
如果您想知道自定义缓存驱动代码应该放在哪里，您可以在 app 目录下创建一个 Extensions 命名空间。但是，请记住 Laravel 没有严格的应用程序结构，您可以根据自己的偏好自由组织应用程序。

注册驱动程序

为了在 Laravel 中注册自定义缓存驱动，我们将使用 Cache 门面上的 extend 方法。由于其他服务提供者可能会在其 boot 方法中尝试读取缓存值，我们将在 booting 回调中注册我们的自定义驱动。通过使用 booting 回调，我们可以确保自定义驱动在我们的应用程序服务提供者上的 boot 方法被调用之前注册，但在所有服务提供者上的 register 方法被调用之后注册。我们将在应用程序的 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,
],