Cache

• Introduction
• Configuration
  • 驱动程序先决条件
• 缓存使用
  • 获取缓存实例
  • 从缓存中检索项目
  • 在缓存中存储项目
  • 从缓存中删除项目
  • 缓存助手
• 缓存标签
  • 存储标记的缓存项
  • 访问标记的缓存项
  • 删除标记的缓存项
  • 修剪陈旧的缓存标签
• 原子锁
  • 驱动程序先决条件
  • 管理锁
  • 跨进程管理锁
• 添加自定义缓存驱动程序
  • 编写驱动程序
  • 注册驱动程序
• Events

#Introduction

您的应用程序执行的某些数据检索或处理任务可能会占用 CPU 资源或需要几秒钟才能完成。在这种情况下，通常会将检索到的数据缓存一段时间，以便在后续请求相同数据时可以快速检索到。缓存数据通常存储在非常快速的数据存储中，例如Memcached 或者Redis.

值得庆幸的是，Laravel 为各种缓存后端提供了一个富有表现力的统一 API，让您可以利用它们超快的数据检索速度并加速您的 Web 应用程序。

#Configuration

您的应用程序的缓存配置文件位于config/cache.php.在此文件中，您可以指定您希望在整个应用程序中默认使用的缓存驱动程序。 Laravel 支持流行的缓存后端，例如Memcached,Redis,DynamoDB和开箱即用的关系数据库。此外，还提供基于文件的缓存驱动程序，而array 和“空”缓存驱动程序为您的自动化测试提供方便的缓存后端。

缓存配置文件还包含文件中记录的各种其他选项，因此请务必阅读这些选项。默认情况下，Laravel 配置为使用file 缓存驱动程序，它将序列化的缓存对象存储在服务器的文件系统中。对于较大的应用程序，建议您使用更强大的驱动程序，例如 Memcached 或 Redis。您甚至可以为同一个驱动程序配置多个缓存配置。

#驱动程序先决条件

Database

当使用database 缓存驱动程序，您将需要设置一个表来包含缓存项。你会找到一个例子Schema 下表声明：

Schema::create('cache', function (Blueprint $table) {
    $table->string('key')->unique();
    $table->text('value');
    $table->integer('expiration');
});

Note
您也可以使用php artisan cache:table 用于生成具有适当架构的迁移的 Artisan 命令。

Memcached

使用 Memcached 驱动程序需要内存缓存 PECL 包 待安装。您可以在config/cache.php 配置文件。该文件已经包含一个memcached.servers 入门指南：

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

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

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

Redis

在 Laravel 使用 Redis 缓存之前，您需要通过 PECL 安装 PhpRedis PHP 扩展或安装predis/predis 通过 Composer 打包 (~1.0)。Laravel 风帆 已经包含此扩展。此外，官方的 Laravel 部署平台如Laravel 锻造 和Laravel 蒸气 默认安装 PhpRedis 扩展。

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

DynamoDB

在使用之前DynamoDB 缓存驱动程序，您必须创建一个 DynamoDB 表来存储所有缓存数据。通常，该表应命名为cache.但是，您应该根据stores.dynamodb.table 应用程序中的配置值cache 配置文件。

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

#缓存使用

#获取缓存实例

要获取缓存存储实例，您可以使用Cache facade，这是我们将在整个文档中使用的内容。这Cachefacade 提供了对 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 facade，你可以通过访问各种缓存存储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 方法可用于确定某个项目是否存在于缓存中。这个方法也会返回false 如果该项目存在但其值为null:

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

递增/递减值

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

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

检索和删除

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

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

#在缓存中存储项目

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

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');

Note
如果您使用的是 Memcached 驱动程序，则当缓存达到其大小限制时，“永久”存储的项目可能会被删除。

#从缓存中删除项目

您可以使用forget 方法：

Cache::forget('key');

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

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

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

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

Cache::flush();

Warning
刷新缓存不尊重您配置的缓存“前缀”，并将从缓存中删除所有条目。清除由其他应用程序共享的缓存时，请仔细考虑这一点。

#缓存助手

除了使用Cache 门面，你也可以使用全局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 缓存驱动程序。此外，当使用带有“永久”存储的缓存的多个标签时，性能最好的驱动程序如下memcached，它会自动清除过时的记录。

#存储标记的缓存项

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

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 仅当使用 Redis 作为应用程序的缓存驱动程序时才需要修剪陈旧的缓存标签。

为了在使用 Redis 缓存驱动程序时正确修剪陈旧的缓存标签条目，Laravel 的cache:prune-stale-tags 工匠命令应该是scheduled 在你的应用程序中App\Console\Kernel 班级：

$schedule->command('cache:prune-stale-tags')->hourly();

#原子锁

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

#驱动程序先决条件

Database

当使用database 缓存驱动程序，您将需要设置一个表来包含应用程序的缓存锁。你会找到一个例子Schema 下表声明：

Schema::create('cache_locks', function (Blueprint $table) {
    $table->string('key')->primary();
    $table->string('owner');
    $table->integer('expiration');
});

#管理锁

原子锁允许操作分布式锁而不用担心竞争条件。例如，Laravel 锻造 使用原子锁来确保一次只有一个远程任务在服务器上执行。您可以使用创建和管理锁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 after waiting a maximum of 5 seconds...
});

#跨进程管理锁

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

在下面的示例中，如果成功获取锁，我们将调度一个排队的作业。此外，我们将通过锁的所有者令牌将锁的所有者令牌传递给排队的作业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();

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

#编写驱动程序

要创建我们的自定义缓存驱动程序，我们首先需要实现Illuminate\Contracts\Cache\Store contract.因此，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 连接来实现这些方法中的每一个。有关如何实现这些方法的示例，请查看Illuminate\Cache\MemcachedStore在里面Laravel 框架源代码.实施完成后，我们可以通过调用Cache 门面的extend 方法：

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

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

#注册驱动程序

要使用 Laravel 注册自定义缓存驱动程序，我们将使用extend 上的方法Cache 正面。由于其他服务提供商可能会尝试读取其内部的缓存值boot 方法，我们将在一个booting 打回来。通过使用booting 回调，我们可以确保自定义驱动程序在boot 方法在我们的应用程序的服务提供者上被调用，但是在register 方法在所有服务提供者上被调用。我们将注册我们的booting 内的回调register 我们应用程序的方法App\Providers\AppServiceProvider 班级：

<?php

namespace App\Providers;

use App\Extensions\MongoStore;
use Illuminate\Contracts\Foundation\Application;
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\ServiceProvider;

class CacheServiceProvider 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 method 是驱动程序的名称。这将对应你的driver 中的选项config/cache.php 配置文件。第二个参数是一个闭包，它应该返回一个Illuminate\Cache\Repository 实例。关闭将通过$app 实例，这是一个实例服务容器.

一旦你的扩展被注册，更新你的config/cache.php 配置文件的driver 扩展名称的选项。

#Events

要在每个缓存操作上执行代码，您可以监听events 由缓存触发。通常，您应该将这些事件侦听器放在应用程序的App\Providers\EventServiceProvider 班级：

use App\Listeners\LogCacheHit;
use App\Listeners\LogCacheMissed;
use App\Listeners\LogKeyForgotten;
use App\Listeners\LogKeyWritten;
use Illuminate\Cache\Events\CacheHit;
use Illuminate\Cache\Events\CacheMissed;
use Illuminate\Cache\Events\KeyForgotten;
use Illuminate\Cache\Events\KeyWritten;

/**
 * The event listener mappings for the application.
 *
 * @var array
 */
protected $listen = [
    CacheHit::class => [
        LogCacheHit::class,
    ],

    CacheMissed::class => [
        LogCacheMissed::class,
    ],

    KeyForgotten::class => [
        LogKeyForgotten::class,
    ],

    KeyWritten::class => [
        LogKeyWritten::class,
    ],
];