メインコンテンツへスキップ

Documentation Index

Fetch the complete documentation index at: https://kawax.biz/llms.txt

Use this file to discover all available pages before exploring further.

Redis はインメモリのキー・バリューストアで、Laravel の多くの機能のバックエンドとして使われます。 設定から操作・Pub/Sub まで、Laravel での Redis の使い方を解説します。

キャッシュ

Redis をキャッシュドライバとして使う

キュー

Redis をキュードライバとして使う

ブロードキャスト

Pub/Sub でリアルタイム通信

​
Redis とは

Redis はオープンソースの高速なキー・バリューストアです。 文字列・ハッシュ・リスト・セット・ソート済みセットなど多様なデータ構造をサポートし、データ構造サーバーとも呼ばれます。 Laravel では以下の用途で Redis が使われます。

​
クライアントの選択

Laravel は PhpRedis（PHP 拡張）と Predis（PHP パッケージ）の 2 つのクライアントをサポートしています。
項目PhpRedisPredis
実装C 言語による PHP 拡張純粋な PHP パッケージ
インストールPECL 拡張が必要composer require で完結
パフォーマンス高速PhpRedis より若干低速
Laravel Sailデフォルトで導入済み別途インストールが必要
推奨環境本番環境開発環境・インストールが難しい環境
Laravel 13 ではデフォルトクライアントが PhpRedis です。本番環境では PhpRedis の使用を推奨します。 Laravel Sail を使っている場合は PhpRedis がすでにインストールされています。

​
設定

​
config/database.php

Redis の設定は config/database.php の redis 配列で管理します。 
'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'),
    ],

],

​
環境変数

.env で接続先を設定します。 
REDIS_CLIENT=phpredis
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=null
REDIS_DB=0
REDIS_CACHE_DB=1
URL 形式での指定も可能です。 
'default' => [
    'url' => 'tcp://127.0.0.1:6379?database=0',
],

'cache' => [
    'url' => 'tls://user:[email protected]:6380?database=1',
],

​
TLS / SSL 接続

TLS 暗号化を使う場合は scheme オプションを指定します。 
'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'),
],

​
クラスタリング

複数の Redis サーバーをクラスターとして使う場合は clusters キーを使います。 
'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 に設定されており、ネイティブ Redis クラスタリングが使われます。 フェイルオーバーを自動で処理するため、本番環境での推奨設定です。 Predis でクライアントサイドシャーディングを使う場合は options.cluster を削除します。 ただしクライアントサイドシャーディングはフェイルオーバーを処理しないため、キャッシュなど一時的なデータにのみ適しています。

​
Predis の設定

Predis を使うには predis/predis パッケージをインストールし、REDIS_CLIENT を predis に変更します。 
composer require predis/predis

REDIS_CLIENT=predis
Predis 固有の接続パラメーターを追加できます。 
'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,
],

​
Predis のリトライ設定

Predis 3.4.0 以降では Retry クラスを使ったリトライ設定が利用できます。 
use Predis\Retry;
use Predis\Retry\Strategy\ExponentialBackoff;

'default' => [
    'url' => env('REDIS_URL'),
    // ...
    'retry' => new Retry(
        new ExponentialBackoff(
            env('REDIS_BACKOFF_BASE', 100),
            env('REDIS_BACKOFF_CAP', 1000),
            true, // ジッターを有効化
        ),
        env('REDIS_MAX_RETRIES', 3)
    )
],

​
PhpRedis の設定

PhpRedis は PECL 経由でインストールします（Laravel Sail では導入済み）。 PhpRedis は以下の追加オプションをサポートします: name, persistent, persistent_id, prefix, read_timeout, retry_interval, max_retries, backoff_algorithm, backoff_base, backoff_cap, timeout, context 
'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],
    ],
],

​
リトライとバックオフ設定

接続失敗時のリトライ動作を設定します。 サポートされるバックオフアルゴリズム: default, decorrelated_jitter, equal_jitter, exponential, uniform, constant 
'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'),
    'max_retries' => env('REDIS_MAX_RETRIES', 3),
    'backoff_algorithm' => env('REDIS_BACKOFF_ALGORITHM', 'decorrelated_jitter'),
    'backoff_base' => env('REDIS_BACKOFF_BASE', 100),
    'backoff_cap' => env('REDIS_BACKOFF_CAP', 1000),
],

​
Unix ソケット接続

同一サーバー上の Redis に接続する場合、Unix ソケットを使うと TCP オーバーヘッドを削減できます。 
REDIS_HOST=/run/redis/redis.sock
REDIS_PORT=0

​
シリアライズと圧縮

PhpRedis では保存データのシリアライズと圧縮アルゴリズムを設定できます。 
'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_PHPPHP のシリアライズ
Redis::SERIALIZER_JSONJSON
Redis::SERIALIZER_IGBINARYigbinary
Redis::SERIALIZER_MSGPACKMessagePack
サポートされる圧縮アルゴリズム:
定数説明
Redis::COMPRESSION_NONE圧縮なし（デフォルト）
Redis::COMPRESSION_LZFLZF
Redis::COMPRESSION_ZSTDZstandard
Redis::COMPRESSION_LZ4LZ4

​
Redis との操作

​
Redis ファサード

Redis ファサードを使ってあらゆる Redis コマンドを実行できます。 ファサードはマジックメソッドでコマンドを Redis サーバーに転送します。 
<?php

namespace App\Http\Controllers;

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)
        ]);
    }
}
引数を受け取るコマンドは、そのままメソッドの引数として渡します。 
use Illuminate\Support\Facades\Redis;

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

$values = Redis::lrange('names', 5, 10);
command メソッドを使ってコマンド名と引数を明示的に指定することもできます。 
$values = Redis::command('lrange', ['name', 5, 10]);

​
複数接続の使い分け

config/database.php で複数の Redis 接続を定義し、connection() メソッドで切り替えられます。 
// 名前付き接続を取得
$redis = Redis::connection('connection-name');

// デフォルト接続を取得
$redis = Redis::connection();

​
トランザクション

transaction() メソッドは Redis の MULTI/EXEC コマンドをラップします。 クロージャ内のすべてのコマンドがアトミックに実行されます。 
use Redis;
use Illuminate\Support\Facades;

Facades\Redis::transaction(function (Redis $redis) {
    $redis->incr('user_visits', 1);
    $redis->incr('total_visits', 1);
});
トランザクション内では Redis から値を取得できません。 クロージャ全体が実行されてから EXEC でまとめて実行されるためです。

​
Lua スクリプト

eval() メソッドで Lua スクリプトをアトミックに実行できます。 スクリプト内で Redis の値を参照・更新できる点でトランザクションより柔軟です。 
$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');
引数の順序: Lua スクリプト → キー数 → キー名… → 追加引数… KEYS[1], KEYS[2] がキー名、ARGV[1] 以降が追加引数として渡されます。

​
パイプライン

大量のコマンドを一度に送信してネットワークのラウンドトリップを削減できます。 
use Redis;
use Illuminate\Support\Facades;

Facades\Redis::pipeline(function (Redis $pipe) {
    for ($i = 0; $i < 1000; $i++) {
        $pipe->set("key:$i", $i);
    }
});
パイプラインはコマンドをまとめて送信するだけで、アトミックではありません。 アトミックな操作が必要な場合はトランザクションまたは Lua スクリプトを使ってください。

​
Pub / Sub

Redis の publish / subscribe コマンドを使ってチャンネル経由でメッセージをやりとりできます。

​
サブスクライバー

subscribe() は長時間動作するプロセスなので、Artisan コマンド内で呼び出します。 
<?php

namespace App\Console\Commands;

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

class RedisSubscribe extends Command
{
    protected $signature = 'redis:subscribe';

    protected $description = 'Subscribe to a Redis channel';

    public function handle(): void
    {
        Redis::subscribe(['test-channel'], function (string $message) {
            echo $message;
        });
    }
}

​
パブリッシャー

別のリクエストやプロセスからメッセージを送信します。 
use Illuminate\Support\Facades\Redis;

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

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

psubscribe() でパターンマッチングのサブスクリプションができます。 
// すべてのチャンネルを購読
Redis::psubscribe(['*'], function (string $message, string $channel) {
    echo $message;
});

// users.* パターンのチャンネルを購読
Redis::psubscribe(['users.*'], function (string $message, string $channel) {
    echo $message;
});

​
まとめ

  • 本番環境: PhpRedis（PECL 拡張、高パフォーマンス）
  • 開発環境・インストールが難しい場合: Predis（Composer パッケージ）
  • Laravel Sail: PhpRedis がデフォルトで導入済み
  • 複数の Redis 接続は config/database.php で定義し、用途ごとに使い分ける（default / cache など）
  • クラスター環境では clusters キーを使う
  • 本番環境では TLS 接続と認証情報の設定を検討する
操作用途
ファサードメソッド通常の Redis コマンド
transaction()複数コマンドのアトミック実行（値の読み取りは不可）
eval()Lua スクリプト（読み取りを伴うアトミック操作）
pipeline()大量コマンドの高速送信（非アトミック）
subscribe() / publish()チャンネルメッセージング（Pub/Sub）
Last modified on April 13, 2026