Laravel 11.x Redis

イントロダクションIntroduction

Redisはオープンソースの高度なキー／値保存域です。キーには文字列、ハッシュ、リスト、セット、ソート済みセットを含むことができるため、データ構造サーバと呼ばれることが多いです。Redis[https://redis.io] is an open source, advanced key-value store. It is often referred to as a data structure server since keys can contain strings[https://redis.io/docs/data-types/strings/], hashes[https://redis.io/docs/data-types/hashes/], lists[https://redis.io/docs/data-types/lists/], sets[https://redis.io/docs/data-types/sets/], and sorted sets[https://redis.io/docs/data-types/sorted-sets/].

LaravelでRedisを使い始める前に、PECLによりPhpRedisPHP拡張機能をインストールして使用することを推奨します。この拡張機能は、「ユーザーフレンドリー」なPHPパッケージに比べてインストールは複雑ですが、Redisを多用するアプリケーションのパフォーマンスが向上する可能性があります。Laravel Sailを使用している場合、この拡張機能はアプリケーションのDockerコンテナにはじめからインストールしてあります。Before using Redis with Laravel, we encourage you to install and use the PhpRedis[https://github.com/phpredis/phpredis] PHP extension via PECL. The extension is more complex to install compared to "user-land" PHP packages but may yield better performance for applications that make heavy use of Redis. If you are using Laravel Sail[/docs/{{version}}/sail], this extension is already installed in your application's Docker container.

PhpRedis拡張機能をインストールできない場合は、Composerを介してpredis/predisパッケージをインストールしてください。PredisはすべてPHPで記述されたRedisクライアントであり、追加の拡張機能は必要ありません。If you are unable to install the PhpRedis extension, you may install the predis/predis package via Composer. Predis is a Redis client written entirely in PHP and does not require any additional extensions:

composer require predis/predis:^2.0

設定Configuration

config/database.php設定ファイルによりアプリケーションのRedis設定を設定します。このファイル内に、アプリケーションで使用するRedisサーバを含むredis配列があります。You may configure your application's Redis settings via the config/database.php configuration file. Within this file, you will see a redis array containing the Redis servers utilized by your application:

'redis' => [

    'client' => env('REDIS_CLIENT', 'phpredis'),

    'options' => [
        'cluster' => env('REDIS_CLUSTER', 'redis'),
        'prefix' => env('REDIS_PREFIX', Str::slug(env('APP_NAME', 'laravel'), '_').'_database_'),
    ],

    'default' => [
        'url' => env('REDIS_URL'),
        'host' => env('REDIS_HOST', '127.0.0.1'),
        'username' => env('REDIS_USERNAME'),
        'password' => env('REDIS_PASSWORD'),
        'port' => env('REDIS_PORT', '6379'),
        'database' => env('REDIS_DB', '0'),
    ],

    'cache' => [
        'url' => env('REDIS_URL'),
        'host' => env('REDIS_HOST', '127.0.0.1'),
        'username' => env('REDIS_USERNAME'),
        'password' => env('REDIS_PASSWORD'),
        'port' => env('REDIS_PORT', '6379'),
        'database' => env('REDIS_CACHE_DB', '1'),
    ],

],

設定ファイルで定義する各Redisサーバは、Redis接続を表す単一のURLを定義しない限り、名前、ホスト、およびポートを指定する必要があります。Each Redis server defined in your configuration file is required to have a name, host, and a port unless you define a single URL to represent the Redis connection:

'redis' => [

    'client' => env('REDIS_CLIENT', 'phpredis'),

    'options' => [
        'cluster' => env('REDIS_CLUSTER', 'redis'),
        'prefix' => env('REDIS_PREFIX', Str::slug(env('APP_NAME', 'laravel'), '_').'_database_'),
    ],

    'default' => [
        'url' => 'tcp://127.0.0.1:6379?database=0',
    ],

    'cache' => [
        'url' => 'tls://user:password@127.0.0.1:6380?database=1',
    ],

],

接続スキームの構成Configuring the Connection Scheme

RedisクライアントはRedisサーバへ接続するとき、デフォルトでtcpスキームを使用します。しかし、Redisサーバの設定配列でscheme設定オプションを指定すれば、TLS/SSL暗号化を使用できます。By default, Redis clients will use the tcp scheme when connecting to your Redis servers; however, you may use TLS / SSL encryption by specifying a scheme configuration option in your Redis server's configuration array:

'default' => [
    'scheme' => 'tls',
    'url' => env('REDIS_URL'),
    'host' => env('REDIS_HOST', '127.0.0.1'),
    'username' => env('REDIS_USERNAME'),
    'password' => env('REDIS_PASSWORD'),
    'port' => env('REDIS_PORT', '6379'),
    'database' => env('REDIS_DB', '0'),
],

クラスタClusters

アプリケーションがRedisサーバのクラスタを利用する場合は、Redis設定のclustersキー内で使用するクラスタを定義してください。この設定キーはデフォルトでは存在しないため、アプリケーションのconfig/database.php設定ファイル内で作成する必要があります。If your application is utilizing a cluster of Redis servers, you should define these clusters within a clusters key of your Redis configuration. This configuration key does not exist by default so you will need to create it within your application's config/database.php configuration file:

'redis' => [

    'client' => env('REDIS_CLIENT', 'phpredis'),

    'options' => [
        'cluster' => env('REDIS_CLUSTER', 'redis'),
        'prefix' => env('REDIS_PREFIX', Str::slug(env('APP_NAME', 'laravel'), '_').'_database_'),
    ],

    'clusters' => [
        'default' => [
            [
                'url' => env('REDIS_URL'),
                'host' => env('REDIS_HOST', '127.0.0.1'),
                'username' => env('REDIS_USERNAME'),
                'password' => env('REDIS_PASSWORD'),
                'port' => env('REDIS_PORT', '6379'),
                'database' => env('REDIS_DB', '0'),
            ],
        ],
    ],

    // ...
],

options.clusterの設定値がredisに設定されているため、Laravelはデフォルトで、ネイティブのRedisクラスタリングを使用します。Redisクラスタリングは丁寧にフェイルオーバーを処理するので、素晴らしいデフォルトオプションです。By default, Laravel will use native Redis clustering since the options.cluster configuration value is set to redis. Redis clustering is a great default option, as it gracefully handles failover.

Laravelはクライアントサイドシャーディングもサポートしています。しかし、クライアントサイドシャーディングはフェイルオーバーを処理しません。そのため、主に別のプライマリデータストアから利用可能な一時的なキャッシュデータに適しています。Laravel also supports client-side sharding. However, client-side sharding does not handle failover; therefore, it is primarily suited for transient cached data that is available from another primary data store.

ネイティブのRedisクラスタリングではなく、クライアントサイドのシャーディングを使用したい場合は、アプリケーションのconfig/database.php設定ファイル内のoptions.cluster設定値を削除してください。If you would like to use client-side sharding instead of native Redis clustering, you may remove the options.cluster configuration value within your application's config/database.php configuration file:

'redis' => [

    'client' => env('REDIS_CLIENT', 'phpredis'),

    'clusters' => [
        // ...
    ],

    // ...
],

PredisPredis

アプリケーションがPredisパッケージを介してRedisを操作するようにする場合は、REDIS_CLIENT環境変数の値を確実にpredisへ設定してください。If you would like your application to interact with Redis via the Predis package, you should ensure the REDIS_CLIENT environment variable's value is predis:

'redis' => [

    'client' => env('REDIS_CLIENT', 'predis'),

    // ...
],

デフォルトの設定オプションに加え、Predisは追加の接続パラメータをサポートしており、Redisサーバごとに定義できます。これらの追加設定オプションを使用するには、アプリケーションのconfig/database.php設定ファイルで、Redisサーバの設定に追加します。In addition to the default configuration options, Predis supports additional connection parameters[https://github.com/nrk/predis/wiki/Connection-Parameters] that may be defined for each of your Redis servers. To utilize these additional configuration options, add them to your Redis server configuration in your application's config/database.php configuration file:

'default' => [
    'url' => env('REDIS_URL'),
    'host' => env('REDIS_HOST', '127.0.0.1'),
    'username' => env('REDIS_USERNAME'),
    'password' => env('REDIS_PASSWORD'),
    'port' => env('REDIS_PORT', '6379'),
    'database' => env('REDIS_DB', '0'),
    'read_write_timeout' => 60,
],

PhpRedisPhpRedis

デフォルトでは、LaravelはPhpRedis拡張機能を使用してRedisと通信します。LaravelがRedisとの通信に使用するクライアントは、redis.client設定オプションの値で決まります。これは通常、REDIS_CLIENT環境変数の値を反映します。By default, Laravel will use the PhpRedis extension to communicate with Redis. The client that Laravel will use to communicate with Redis is dictated by the value of the redis.client configuration option, which typically reflects the value of the REDIS_CLIENT environment variable:

'redis' => [

    'client' => env('REDIS_CLIENT', 'phpredis'),

    // ...
],

デフォルトの設定オプションに加えて、PhpRedisはname、persistent、persistent_id、prefix、read_timeout、retry_interval、timeout、contextの追加接続パラメータをサポートしています。これらのオプションは、config/database.php設定ファイルのRedisサーバ設定へ追加してください。In addition to the default configuration options, PhpRedis supports the following additional connection parameters: name, persistent, persistent_id, prefix, read_timeout, retry_interval, timeout, and context. You may add any of these options to your Redis server configuration in the config/database.php configuration file:

'default' => [
    'url' => env('REDIS_URL'),
    'host' => env('REDIS_HOST', '127.0.0.1'),
    'username' => env('REDIS_USERNAME'),
    'password' => env('REDIS_PASSWORD'),
    'port' => env('REDIS_PORT', '6379'),
    'database' => env('REDIS_DB', '0'),
    'read_timeout' => 60,
    'context' => [
        // 'auth' => ['username', 'secret'],
        // 'stream' => ['verify_peer' => false],
    ],
],

PhpRedisのシリアライズと圧縮PhpRedis Serialization and Compression

PhpRedis拡張モジュールは、様々なシリアライズや圧縮アルゴリズムも設定できます。これらのアルゴリズムは、Redis設定のoptions配列で指定します。The PhpRedis extension may also be configured to use a variety of serializers and compression algorithms. These algorithms can be configured via the options array of your Redis configuration:

'redis' => [

    'client' => env('REDIS_CLIENT', 'phpredis'),

    'options' => [
        'cluster' => env('REDIS_CLUSTER', 'redis'),
        'prefix' => env('REDIS_PREFIX', Str::slug(env('APP_NAME', 'laravel'), '_').'_database_'),
        'serializer' => Redis::SERIALIZER_MSGPACK,
        'compression' => Redis::COMPRESSION_LZ4,
    ],

    // ...
],

現在サポートしているシリアライザは、Redis::SERIALIZER_NONE（デフォルト）、Redis::SERIALIZER_PHP、Redis::SERIALIZER_JSON、Redis::SERIALIZER_IGBINARY、Redis::SERIALIZER_MSGPACKです。Currently supported serializers include: Redis::SERIALIZER_NONE (default), Redis::SERIALIZER_PHP, Redis::SERIALIZER_JSON, Redis::SERIALIZER_IGBINARY, and Redis::SERIALIZER_MSGPACK.

サポートする圧縮アルゴリズムは、Redis::COMPRESSION_NONE（デフォルト）、Redis::COMPRESSION_LZF、Redis::COMPRESSION_ZSTD、Redis::COMPRESSION_LZ4です。Supported compression algorithms include: Redis::COMPRESSION_NONE (default), Redis::COMPRESSION_LZF, Redis::COMPRESSION_ZSTD, and Redis::COMPRESSION_LZ4.

Redisの操作Interacting With Redis

Redisファサードでさまざまなメソッドを呼び出すことで、Redisを操作できます。Redisファサードは動的メソッドをサポートしています。つまり、ファサードでRedisコマンドを呼び出すと、コマンドが直接Redisに渡されます。この例では、Redisファサードでgetメソッドを呼び出すことにより、RedisのGETコマンドを呼び出しています。You may interact with Redis by calling various methods on the Redis facade[/docs/{{version}}/facades]. The Redis facade supports dynamic methods, meaning you may call any Redis command[https://redis.io/commands] on the facade and the command will be passed directly to Redis. In this example, we will call the Redis GET command by calling the get method on the Redis facade:

<?php

namespace App\Http\Controllers;

use App\Http\Controllers\Controller;
use Illuminate\Support\Facades\Redis;
use Illuminate\View\View;

class UserController extends Controller
{
    /**
     * 指定ユーザーのプロファイル表示
     */
    public function show(string $id): View
    {
        return view('user.profile', [
            'user' => Redis::get('user:profile:'.$id)
        ]);
    }
}

上記のように、Redisファサードで任意のRedisコマンドを呼び出すことができます。Laravelはマジックメソッドを使用してコマンドをRedisサーバへ渡します。Redisコマンドが引数を必要とする場合は、それらをファサードの対応するメソッドへ渡す必要があります。As mentioned above, you may call any of Redis' commands on the Redis facade. Laravel uses magic methods to pass the commands to the Redis server. If a Redis command expects arguments, you should pass those to the facade's corresponding method:

use Illuminate\Support\Facades\Redis;

Redis::set('name', 'Taylor');

$values = Redis::lrange('names', 5, 10);

または、Redisファサードのcommandメソッドを使用してサーバにコマンドを渡すこともできます。このメソッドは、コマンドの名前を最初の引数、値の配列を２番目の引数に取ります。Alternatively, you may pass commands to the server using the Redis facade's command method, which accepts the name of the command as its first argument and an array of values as its second argument:

$values = Redis::command('lrange', ['name', 5, 10]);

複数のRedis接続の使用Using Multiple Redis Connections

アプリケーションのconfig/database.php設定ファイルでは、複数のRedis接続／サーバが定義できます。Redisファサードのconnectionメソッドを使用して、特定のRedis接続への接続を取得できます。Your application's config/database.php configuration file allows you to define multiple Redis connections / servers. You may obtain a connection to a specific Redis connection using the Redis facade's connection method:

$redis = Redis::connection('connection-name');

デフォルトのRedis接続のインスタンスを取得するには、引数なしでconnectionメソッドを呼び出してください。To obtain an instance of the default Redis connection, you may call the connection method without any additional arguments:

$redis = Redis::connection();

トランザクションTransactions

Redisファサードのtransactionメソッドは、RedisのネイティブMULTIおよびEXECコマンドの便利なラッパーを提供します。transactionメソッドは、唯一の引数にクロージャを取ります。このクロージャはRedis接続インスタンスを受け取り、このインスタンスで必要なコマンドを発行できます。クロージャ内で発行したすべてのRedisコマンドは、単一のアトミックトランザクションとして実行します。The Redis facade's transaction method provides a convenient wrapper around Redis' native MULTI and EXEC commands. The transaction method accepts a closure as its only argument. This closure will receive a Redis connection instance and may issue any commands it would like to this instance. All of the Redis commands issued within the closure will be executed in a single, atomic transaction:

use Redis;
use Illuminate\Support\Facades;

Facades\Redis::transaction(function (Redis $redis) {
    $redis->incr('user_visits', 1);
    $redis->incr('total_visits', 1);
});

warning Warning! Redisトランザクションを定義する場合、Redis接続から値を取得できません。トランザクションは単一のアトミック操作として実行し、クロージャ全体がコマンドの実行を完了するまで、操作は実行されないことに注意してください。[!WARNING]
When defining a Redis transaction, you may not retrieve any values from the Redis connection. Remember, your transaction is executed as a single, atomic operation and that operation is not executed until your entire closure has finished executing its commands.

LuaスクリプトLua Scripts

evalメソッドは、単一のアトミック操作で複数のRedisコマンドを実行する別のメソッドです。ただし、evalメソッドには、その操作中にRedisキー／値を対話し調べられる利点があります。Redisスクリプトは、Luaプログラミング言語で記述します。The eval method provides another method of executing multiple Redis commands in a single, atomic operation. However, the eval method has the benefit of being able to interact with and inspect Redis key values during that operation. Redis scripts are written in the Lua programming language[https://www.lua.org].

evalメソッドは最初は少し怖いかもしれませんが、壁を超えるために基本的な例を見てみましょう。evalメソッドは引数をいくつか取ります。まず、Luaスクリプトを(文字列として)メソッドへ渡す必要があります。次に、スクリプトが操作するキーの数を(整数として)渡す必要があります。第三に、それらのキーの名前を渡す必要があります。最後に、スクリプト内でアクセスする必要があるその他の追加の引数を渡します。The eval method can be a bit scary at first, but we'll explore a basic example to break the ice. The eval method expects several arguments. First, you should pass the Lua script (as a string) to the method. Secondly, you should pass the number of keys (as an integer) that the script interacts with. Thirdly, you should pass the names of those keys. Finally, you may pass any other additional arguments that you need to access within your script.

この例では、カウンターを増分し、その新しい値を検査し、最初のカウンターの値が５より大きい場合は、２番目のカウンターを増分します。最後に、最初のカウンターの値を返します。In this example, we will increment a counter, inspect its new value, and increment a second counter if the first counter's value is greater than five. Finally, we will return the value of the first counter:

$value = Redis::eval(<<<'LUA'
    local counter = redis.call("incr", KEYS[1])

    if counter > 5 then
        redis.call("incr", KEYS[2])
    end

    return counter
LUA, 2, 'first-counter', 'second-counter');

warning Warning! Redisスクリプトの詳細には、Redisドキュメントを参照してください。[!WARNING]
Please consult the Redis documentation[https://redis.io/commands/eval] for more information on Redis scripting.

パイプラインコマンドPipelining Commands

数十のRedisコマンドを実行する必要が起きることもあるでしょう。毎コマンドごとにRedisサーバへネットワークトリップする代わりに、pipelineメソッドを使用できます。pipelineメソッドは、Redisインスタンスを受け取るクロージャを１つ引数に取ります。このRedisインスタンスですべてのコマンドを発行すると、サーバへのネットワークトリップを減らすため、すべてのコマンドを一度にRedisサーバへ送信します。コマンドは、発行した順序で実行されます。Sometimes you may need to execute dozens of Redis commands. Instead of making a network trip to your Redis server for each command, you may use the pipeline method. The pipeline method accepts one argument: a closure that receives a Redis instance. You may issue all of your commands to this Redis instance and they will all be sent to the Redis server at the same time to reduce network trips to the server. The commands will still be executed in the order they were issued:

use Redis;
use Illuminate\Support\Facades;

Facades\Redis::pipeline(function (Redis $pipe) {
    for ($i = 0; $i < 1000; $i++) {
        $pipe->set("key:$i", $i);
    }
});

Pub／SubPub / Sub

Laravelは、Redisのpublishおよびsubscribeコマンドへの便利なインターフェイスを提供しています。これらのRedisコマンドを使用すると、特定の「チャンネル」でメッセージをリッスンできます。別のアプリケーションから、または別のプログラミング言語を使用してメッセージをチャンネルに公開し、アプリケーションとプロセス間の簡単な通信を可能にすることができます。Laravel provides a convenient interface to the Redis publish and subscribe commands. These Redis commands allow you to listen for messages on a given "channel". You may publish messages to the channel from another application, or even using another programming language, allowing easy communication between applications and processes.

まず、subscribeメソッドを使用してチャンネルリスナを設定しましょう。subscribeメソッドを呼び出すとプロセスは長時間実行され続けるため、このメソッド呼び出しはArtisanコマンド内に配置します。First, let's setup a channel listener using the subscribe method. We'll place this method call within an Artisan command[/docs/{{version}}/artisan] since calling the subscribe method begins a long-running process:

<?php

namespace App\Console\Commands;

use Illuminate\Console\Command;
use Illuminate\Support\Facades\Redis;

class RedisSubscribe extends Command
{
    /**
     * consoleコマンドの名前と使用方法
     *
     * @var string
     */
    protected $signature = 'redis:subscribe';

    /**
     * コンソールコマンドの説明
     *
     * @var string
     */
    protected $description = 'Subscribe to a Redis channel';

    /**
     * consoleコマンドの実行
     */
    public function handle(): void
    {
        Redis::subscribe(['test-channel'], function (string $message) {
            echo $message;
        });
    }
}

これで、publishメソッドを使用してチャンネルへメッセージを発行できます。Now we may publish messages to the channel using the publish method:

use Illuminate\Support\Facades\Redis;

Route::get('/publish', function () {
    // ...

    Redis::publish('test-channel', json_encode([
        'name' => 'Adam Wathan'
    ]));
});

ワイルドカードサブスクリプションWildcard Subscriptions

psubscribeメソッドを使用すると、ワイルドカードチャンネルをサブスクライブできます。これは、すべてのチャンネルのすべてのメッセージをキャッチするのに役立ちます。チャンネル名は、引数に渡たすクロージャの２番目の引数へ渡されます。Using the psubscribe method, you may subscribe to a wildcard channel, which may be useful for catching all messages on all channels. The channel name will be passed as the second argument to the provided closure:

Redis::psubscribe(['*'], function (string $message, string $channel) {
    echo $message;
});

Redis::psubscribe(['users.*'], function (string $message, string $channel) {
    echo $message;
});