Laravel 7.x キャッシュ

設定Configuration

Laravelは読み書きしやすい、多くのキャッシュシステムに対する統一したAPIを提供します。キャッシュの設定は、config/cache.phpで指定します。アプリケーション全体のデフォルトとして使用するキャッシュドライバをこのファイルの中で指定します。MemcachedやRedisなど、人気のあるキャッシュシステムをLaravelは最初からサポートしています。Laravel provides an expressive, unified API for various caching backends. The cache configuration is located at config/cache.php. In this file you may specify which cache driver you would like to be used by default throughout your application. Laravel supports popular caching backends like Memcached[https://memcached.org] and Redis[https://redis.io] out of the box.

キャッシュ設定ファイルは、さまざまな他のオプションも含んでいます。コメントで説明してありますので、よく読んで確認してください。Laravelのデフォルトとして、fileキャッシュドライバが設定されています。ファイルシステムへオブジェクトをシリアライズして保存します。大きなアプリケーションではMemecachedやAPCのような、より堅牢なドライバを使うことを推奨します。複数のドライバを使用するキャッシュ設定も可能です。The cache configuration file also contains various other options, which are documented within the file, so make sure to read over these options. By default, Laravel is configured to use the file cache driver, which stores the serialized, cached objects in the filesystem. For larger applications, it is recommended that you use a more robust driver such as Memcached or Redis. You may even configure multiple cache configurations for the same driver.

ドライバ事前要件Driver Prerequisites

データベースDatabase

データベースをキャッシュドライバに使用する場合、キャッシュアイテムを構成するテーブルを用意する必要があります。このテーブルの「スキーマ」を定義するサンプルを見てください。When using the database cache driver, you will need to setup a table to contain the cache items. You'll find an example Schema declaration for the table below:

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

lightbulb">Tip!! 正確なスキーマのマイグレーションを生成するために、php artisan cache:table Artisanコマンドを使用することもできます。{tip} You may also use the php artisan cache:table Artisan command to generate a migration with the proper schema.

MemcachedMemcached

Memcachedキャッシュを使用する場合は、Memcached PECLパッケージをインストールする必要があります。全Memcachedサーバは、config/cache.php設定ファイルにリストしてください。Using the Memcached driver requires the Memcached PECL package[https://pecl.php.net/package/memcached] to be installed. You may list all of your Memcached servers in the config/cache.php configuration file:

'memcached' => [
    [
        'host' => '127.0.0.1',
        'port' => 11211,
        'weight' => 100
    ],
],

さらに、UNIXソケットパスへ、hostオプションを設定することもできます。これを行うにはportオプションに0を指定してください。You may also set the host option to a UNIX socket path. If you do this, the port option should be set to 0:

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

RedisRedis

LaravelでRedisを使う前にPECLでPhpRedis PHP拡張、もしくはComposerでpredis/predisパッケージ(~1.0）のどちらかをインストールしておく必要があります。Before using a Redis cache with Laravel, you will need to either install the PhpRedis PHP extension via PECL or install the predis/predis package (~1.0) via Composer.

Redisの設定についての詳細は、Laravelドキュメントページを読んでください。For more information on configuring Redis, consult its Laravel documentation page[/docs/{{version}}/redis#configuration].

キャッシュの使用法Cache Usage

キャッシュインスタンスの取得Obtaining A Cache Instance

Illuminate\Contracts\Cache\FactoryとIlluminate\Contracts\Cache\Repository契約は、Laravelのキャッシュサービスへのアクセスを提供します。Factory契約は、アプリケーションで定義している全キャッシュドライバへのアクセスを提供します。Repository契約は通常、cache設定ファイルで指定している、アプリケーションのデフォルトキャッシュドライバの実装です。The Illuminate\Contracts\Cache\Factory and Illuminate\Contracts\Cache\Repository contracts[/docs/{{version}}/contracts] provide access to Laravel's cache services. The Factory contract provides access to all cache drivers defined for your application. The Repository contract is typically an implementation of the default cache driver for your application as specified by your cache configuration file.

しかし、このドキュメント全体で使用している、Cacheファサードも利用できます。Cacheファサードは裏で動作している、Laravelキャッシュ契約の実装への便利で簡潔なアクセスを提供しています。However, you may also use the Cache facade, which is what we will use throughout this documentation. The Cache facade provides convenient, terse access to the underlying implementations of the Laravel cache contracts:

<?php

namespace App\Http\Controllers;

use Illuminate\Support\Facades\Cache;

class UserController extends Controller
{
    /**
     * アプリケーションの全ユーザーリストの表示
     *
     * @return Response
     */
    public function index()
    {
        $value = Cache::get('key');

        //
    }
}

複数のキャッシュ保存先へのアクセスAccessing Multiple Cache Stores

Cacheファサードのstoreメソッドを使い、さまざまなキャッシュ保存域へアクセスできます。storeメソッドに渡すキーは、cache設定ファイルのstores設定配列にリストしている保存域の一つです。Using the Cache facade, you may access various cache stores via the store method. The key passed to the store method should correspond to one of the stores listed in the stores configuration array in your cache configuration file:

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

Cache::store('redis')->put('bar', 'baz', 600); // １０分間

キャッシュからアイテム取得Retrieving Items From The Cache

Cacheファサードのgetメソッドは、キャッシュからアイテムを取得するために使用します。アイテムがキャッシュに存在していない場合は、nullが返されます。アイテムが存在していない時に返したい、カスタムデフォルト値をgetメソッドの第２引数として渡すこともできます。The get method on the Cache facade is used to retrieve items from the cache. If the item does not exist in the cache, null will be returned. If you wish, you may pass a second argument to the get method specifying the default value you wish to be returned if the item doesn't exist:

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

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

デフォルト値として「クロージャ」を渡すこともできます。キャッシュに指定したアイテムが存在していない場合、「クロージャ」の結果が返されます。クロージャを渡すことで、データベースや外部サービスからデフォルト値を取得するのを遅らせることができます。You may even pass a Closure as the default value. The result of the Closure will be returned if the specified item does not exist in the cache. Passing a Closure allows you to defer the retrieval of default values from a database or other external service:

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

アイテムの存在確認Checking For Item Existence

hasメソッドで、キャッシュにアイテムが存在しているかを調べることができます。このメソッドは、値がnullの場合、falseを返します。The has method may be used to determine if an item exists in the cache. This method will return false if the value is null:

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

値の増減Incrementing / Decrementing Values

incrementとdecrementメソッドはキャッシュの整数アイテムの値を調整するために使用します。両方のメソッドともそのアイテムの値をどのくらい増減させるかの増分をオプションの第２引数に指定できます。The increment and decrement methods may be used to adjust the value of integer items in the cache. Both of these methods accept an optional second argument indicating the amount by which to increment or decrement the item's value:

Cache::increment('key');
Cache::increment('key', $amount);
Cache::decrement('key');
Cache::decrement('key', $amount);

取得不可時更新Retrieve & Store

キャッシュからアイテムを取得しようとして、指定したアイテムが存在しない場合は、デフォルト値を保存したい場合もあるでしょう。たとえば、全ユーザーをキャッシュから取得しようとし、存在していない場合はデータベースから取得しキャッシュへ追加したい場合です。Cache::rememberメソッドを使用します。Sometimes you may wish to retrieve an item from the cache, but also store a default value if the requested item doesn't exist. For example, you may wish to retrieve all users from the cache or, if they don't exist, retrieve them from the database and add them to the cache. You may do this using the Cache::remember method:

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

キャッシュに存在しない場合、rememberメソッドに渡された「クロージャ」が実行され、結果がキャッシュに保存されます。If the item does not exist in the cache, the Closure passed to the remember method will be executed and its result will be placed in the cache.

rememberForeverメソッドでアイテムをキャッシュから取得するか、できない場合は永久に保存できます。You may use the rememberForever method to retrieve an item from the cache or store it forever:

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

取得後削除Retrieve & Delete

キャッシュからアイテムを取得した後に削除したい場合は、pullメソッドを使用します。getメソッドと同様にキャッシュにアイテムが存在していない場合は、nullが返ります。If you need to retrieve an item from the cache and then delete the item, you may use the pull method. Like the get method, null will be returned if the item does not exist in the cache:

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

キャッシュへアイテム保存Storing Items In The Cache

Cacheファサードのputメソッドにより、キャッシュにアイテムを保存できます。You may use the put method on the Cache facade to store items in the cache:

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

putメソッドに保存期間を渡さない場合、そのアイテムは無期限に保存されます。If the storage time is not passed to the put method, the item will be stored indefinitely:

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

どのくらいでアイテムが無効になるかを秒数で指定する代わりに、キャッシュされたアイテムの有効期限を示すDateTimeインスタンスを渡すこともできます。Instead of passing the number of seconds as an integer, you may also pass a DateTime instance representing the expiration time of the cached item:

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

非存在時保存Store If Not Present

addメソッドはキャッシュに保存されていない場合のみ、そのアイテムを保存します。キャッシュへ実際にアイテムが追加された場合はtrueが返ってきます。そうでなければfalseが返されます。The add method will only add the item to the cache if it does not already exist in the cache store. The method will return true if the item is actually added to the cache. Otherwise, the method will return false:

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

アイテムを永遠に保存Storing Items Forever

foreverメソッドはそのアイテムをキャッシュへ永遠に保存します。こうした値は有効期限が切れないため、forgetメソッドを使用し、削除する必要があります。The forever method may be used to store an item in the cache permanently. Since these items will not expire, they must be manually removed from the cache using the forget method:

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

lightbulb">Tip!! Memcachedドライバーを使用する場合、キャッシュが最大値に達すると、"forever"を指定したアイテムも削除されます。{tip} If you are using the Memcached driver, items that are stored "forever" may be removed when the cache reaches its size limit.

キャッシュからのアイテム削除Removing Items From The Cache

forgetメソッドでキャッシュからアイテムを削除します。You may remove items from the cache using the forget method:

Cache::forget('key');

０か負数を指定し、アイテムを削除することもできます。You may also remove items by providing a zero or negative TTL:

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

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

キャッシュ全体をクリアしたい場合はflushメソッドを使います。You may clear the entire cache using the flush method:

Cache::flush();

Note: note flushメソッドは、キャッシュのプレフィックスを考慮せずに、キャッシュから全アイテムを削除します。他のアプリケーションと共有するキャッシュを削除するときは、利用を熟考してください。{note} Flushing the cache does not respect the cache prefix and will remove all entries from the cache. Consider this carefully when clearing a cache which is shared by other applications.

CacheヘルパThe Cache Helper

Cacheファサードやキャッシュ契約の利用に加え、グローバルなcache関数を使用し、キャッシュ経由でデータを取得および保存することもできます。cache関数を文字列引数だけで呼び出すと、指定したキーの値を返します。In addition to using the Cache facade or cache contract[/docs/{{version}}/contracts], you may also use the global cache function to retrieve and store data via the cache. When the cache function is called with a single, string argument, it will return the value of the given key:

$value = cache('key');

関数へキー／値ペアの配列と有効時間を指定した場合は、指定した時間まで値をキャッシュへ保存します。If you provide an array of key / value pairs and an expiration time to the function, it will store values in the cache for the specified duration:

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

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

cache関数を引数無しで呼び出すと、Illuminate\Contracts\Cache\Factory`の実装インスタンスが返されます。これを使い他のキャッシュメソッドも呼び出せます。When the cache function is called without any arguments, it returns an instance of the Illuminate\Contracts\Cache\Factory implementation, allowing you to call other caching methods:

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

lightbulb">Tip!! テストでグローバルのcache関数の呼び出し時は、ファサードのテストと同様にCache::shouldReceiveメソッドを使用できます。{tip} When testing call to the global cache function, you may use the Cache::shouldReceive method just as if you were testing a facade[/docs/{{version}}/mocking#mocking-facades].

キャッシュタグCache Tags

Note: note キャッシュタグはfile、dynamodb、databaseキャッシュドライバ使用時は使用できません。また"forever"として保存しているキャッシュに複数のタグを使用する場合は、memcachedのような古いレコードを自動的にパージするドライバで良いパフォーマンスが出ます。{note} Cache tags are not supported when using the file, dynamodb, or database cache drivers. Furthermore, when using multiple tags with caches that are stored "forever", performance will be best with a driver such as memcached, which automatically purges stale records.

タグ付きキャッシュアイテムの保存Storing Tagged Cache Items

キャッシュタグにより関連するアイテムにタグを付け、そのタグを指定することで割り付けたキャッシュ値へ一度にアクセスできます。たとえば、タグ付けしたキャッシュにアクセスし、キャッシュへ値をputしてみましょう。Cache tags allow you to tag related items in the cache and then flush all cached values that have been assigned a given tag. You may access a tagged cache by passing in an ordered array of tag names. For example, let's access a tagged cache and put value in the cache:

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

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

タグ付けしたキャッシュアイテムへのアクセスAccessing Tagged Cache Items

タグ付けしたキャッシュアイテムを取得するには、tagsメソッドへ渡した同じ順番でタグのリストを渡します。それから、getメソッドを取得したいキーで呼び出します。To retrieve a tagged cache item, pass the same ordered list of tags to the tags method and then call the get method with the key you wish to retrieve:

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

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

タグ付けしたアイテムの削除Removing Tagged Cache Items

タグやタグのリストを割り付けたアイテムすべてを削除できます。たとえば次の文は、peopleか authors、もしくは両方のタグ付けしたキャッシュをすべて削除します。You may flush all items that are assigned a tag or list of tags. For example, this statement would remove all caches tagged with either people, authors, or both. So, both Anne and John would be removed from the cache:

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

制約により、この文はauthorsのタグづけしたキャッシュだけを削除するため、Anneは削除されますがJohnはされません。In contrast, this statement would remove only caches tagged with authors, so Anne would be removed, but not John:

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

アトミックロックAtomic Locks

Note: note この機能を利用するには、アプリケーションでmemcached、dynamodb、redis、database、arrayのどれかをデフォルトキャッシュドライバに使用する必用があります。更に、すべてのサーバから同じ中央キャッシュサーバへ通信できる必用もあります。{note} To utilize this feature, your application must be using the memcached, dynamodb, redis, database, or array cache driver as your application's default cache driver. In addition, all servers must be communicating with the same central cache server.

ドライバー要件Driver Prerequisites

データベースDatabase

databaseキャッシュドライバを使用する場合は、キャッシュロックを含むテーブルを準備する必用があります。以下にテーブルのSchema定義の例を紹介します。When using the database cache driver, you will need to setup a table to contain the cache locks. You'll find an example Schema declaration for the table below:

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

ロック管理Managing Locks

アトミックロックにより競合状態を心配することなく、分散型のロック操作を実現できます。たとえば、Laravel Forgeでは、一度に１つのリモートタスクを１つのサーバで実行するために、アトミックロックを使用しています。ロックを生成し、管理するにはCache::lockメソッドを使用します。Atomic locks allow for the manipulation of distributed locks without worrying about race conditions. For example, Laravel Forge[https://forge.laravel.com] uses atomic locks to ensure that only one remote task is being executed on a server at a time. You may create and manage locks using the Cache::lock method:

use Illuminate\Support\Facades\Cache;

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

if ($lock->get()) {
    // １０秒間ロックを獲得する

    $lock->release();
}

getメソッドは、クロージャも引数に取ります。クロージャ実行後、Laravelは自動的にロックを解除します。The get method also accepts a Closure. After the Closure is executed, Laravel will automatically release the lock:

Cache::lock('foo')->get(function () {
    // 無期限のロックを獲得し、自動的に開放する
});

リクエスト時にロックが獲得できないときに、指定秒数待機するようにLaravelに指示できます。指定制限時間内にロックが獲得できなかった場合は、Illuminate\Contracts\Cache\LockTimeoutExceptionが投げられます。If the lock is not available at the moment you request it, you may instruct Laravel to wait for a specified number of seconds. If the lock can not be acquired within the specified time limit, an Illuminate\Contracts\Cache\LockTimeoutException will be thrown:

use Illuminate\Contracts\Cache\LockTimeoutException;

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

try {
    $lock->block(5);

    // 最大５秒待機し、ロックを獲得
} catch (LockTimeoutException $e) {
    // ロックを獲得できなかった
} finally {
    optional($lock)->release();
}

Cache::lock('foo', 10)->block(5, function () {
    // 最大５秒待機し、ロックを獲得
});

プロセス間のロック管理Managing Locks Across Processes

あるプロセスでロックを獲得し、他のプロセスで開放したい場合もあります。たとえば、Webリクエストでロックを獲得し、そのリクエストから起動したキュー済みジョブの最後で、ロックを開放したい場合です。そのようなシナリオでは、ジョブで渡されたトークンを使い、ロックを再インスタンス化できるように、ロックを限定する「所有者(owner)のトークン」をキューするジョブへ渡す必要があります。Sometimes, you may wish to acquire a lock in one process and release it in another process. For example, you may acquire a lock during a web request and wish to release the lock at the end of a queued job that is triggered by that request. In this scenario, you should pass the lock's scoped "owner token" to the queued job so that the job can re-instantiate the lock using the given token:

// コントローラ側
$podcast = Podcast::find($id);

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

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

// ProcessPodcastジョブ側
Cache::restoreLock('foo', $this->owner)->release();

現在の所有者にかかわらず、ロックを開放したい場合は、forceReleaseメソッドを使用します。If you would like to release a lock without respecting its current owner, you may use the forceRelease method:

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

カスタムキャッシュドライバの追加Adding Custom Cache Drivers

ドライバープログラミングWriting The Driver

カスタムキャッシュドライバを作成するには、Illuminate\Contracts\Cache\Store契約を最初に実装する必要があります。そのため、MongoDBキャッシュドライバは、以下のような実装になるでしょう。To create our custom cache driver, we first need to implement the Illuminate\Contracts\Cache\Store contract[/docs/{{version}}/contracts]. So, a MongoDB cache implementation would look something like this:

<?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のソースコードを参照してください。実装を完了したら、ドライバを登録します。We just need to implement each of these methods using a MongoDB connection. For an example of how to implement each of these methods, take a look at the Illuminate\Cache\MemcachedStore in the framework source code. Once our implementation is complete, we can finish our custom driver registration.

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

lightbulb">Tip!! カスタムキャッシュドライバーをどこに設置するか迷っているなら、appディレクトリ下にExtensionsの名前空間で作成できます。しかし、Laravelはアプリケーション構造を強制していませんので、自分の好みに合わせてアプリケーションを自由に構築できることを忘れないでください。{tip} If you're wondering where to put your custom cache driver code, you could create an Extensions namespace within your app directory. However, keep in mind that Laravel does not have a rigid application structure and you are free to organize your application according to your preferences.

ドライバ登録Registering The Driver

Laravelにカスタムキャッシュドライバを登録するには、Cacheファサードのextendメソッドを使います。新しくインストールしたLaravelに含まれている、デフォルトのApp\Providers\AppServiceProviderのbootメソッドで、Cache::extendを呼び出せます。もしくは、拡張を設置するために自身のサービスプロバイダを作成することもできます。config/app.phpプロバイダ配列に、そのプロバイダを登録し忘れないようにしてください。To register the custom cache driver with Laravel, we will use the extend method on the Cache facade. The call to Cache::extend could be done in the boot method of the default App\Providers\AppServiceProvider that ships with fresh Laravel applications, or you may create your own service provider to house the extension - just don't forget to register the provider in the config/app.php provider array:

<?php

namespace App\Providers;

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

class CacheServiceProvider extends ServiceProvider
{
    /**
     * 全アプリケーションサービスの登録
     *
     * @return void
     */
    public function register()
    {
        //
    }

    /**
     * 全アプリケーションサービスの初期起動
     *
     * @return void
     */
    public function boot()
    {
        Cache::extend('mongo', function ($app) {
            return Cache::repository(new MongoStore);
        });
    }
}

extendメソッドの最初の引数はドライバ名です。これはconfig/cache.php設定ファイルの、driverオプションと対応します。第２引数は、Illuminate\Cache\Repositoryインスタンスを返すクロージャです。クロージャには、サービスコンテナインスタンスの$appインスタンスが渡されます。The first argument passed to the extend method is the name of the driver. This will correspond to your driver option in the config/cache.php configuration file. The second argument is a Closure that should return an Illuminate\Cache\Repository instance. The Closure will be passed an $app instance, which is an instance of the service container[/docs/{{version}}/container].

拡張を登録したら、config/cache.php設定ファイルのdriverオプションへ、拡張の名前を登録してください。Once your extension is registered, update your config/cache.php configuration file's driver option to the name of your extension.

イベントEvents

全キャッシュ操作に対してコードを実行するには、キャッシュが発行するイベントを購読する必要があります。通常、イベントリスナはEventServiceProviderの中へ設置します。To execute code on every cache operation, you may listen for the events[/docs/{{version}}/events] fired by the cache. Typically, you should place these event listeners within your EventServiceProvider:

/**
 * アプリケーションのイベントリスナ
 *
 * @var array
 */
protected $listen = [
    'Illuminate\Cache\Events\CacheHit' => [
        'App\Listeners\LogCacheHit',
    ],

    'Illuminate\Cache\Events\CacheMissed' => [
        'App\Listeners\LogCacheMissed',
    ],

    'Illuminate\Cache\Events\KeyForgotten' => [
        'App\Listeners\LogKeyForgotten',
    ],

    'Illuminate\Cache\Events\KeyWritten' => [
        'App\Listeners\LogKeyWritten',
    ],
];