Redis - Knowledge of Laravel

Redis is a fast in-memory key-value store used by many Laravel features as a backend. This page covers everything from configuration to commands and Pub/Sub.

Cache

Use Redis as a cache driver

Queues

Use Redis as a queue driver

Broadcasting

Real-time messaging with Pub/Sub

Introduction

Redis is an open source, advanced key-value store. It is often referred to as a data structure server since keys can contain strings, hashes, lists, sets, and sorted sets. Laravel uses Redis across multiple features:

Choosing a client

Laravel supports two Redis clients: PhpRedis (a PHP extension) and Predis (a PHP package).

	PhpRedis	Predis
Implementation	C-based PHP extension	Pure PHP package
Install	PECL extension required	`composer require` only
Performance	Faster	Slightly slower
Laravel Sail	Pre-installed	Manual install needed
Best for	Production	Development / restricted environments

Laravel 13 defaults to PhpRedis. PhpRedis is recommended for production. If you use Laravel Sail, PhpRedis is already installed in your Docker container.

Configuration

config/database.php

Redis settings live in the redis array in config/database.php:

'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'),
    ],

],

Environment variables

Set the connection details in your .env file:

REDIS_CLIENT=phpredis
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=null
REDIS_DB=0
REDIS_CACHE_DB=1

You can also use a URL format:

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

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

TLS / SSL connections

To use TLS encryption, add the scheme option to a connection:

'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

Define a Redis cluster using the clusters key in config/database.php:

'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'),
            ],
        ],
    ],

],

By default, options.cluster is set to redis, enabling native Redis clustering with automatic failover. To use client-side sharding with Predis instead, remove the options.cluster key. Note that client-side sharding does not handle failover and is best suited for transient cached data.

Predis

Install the package and set the environment variable:

composer require predis/predis

REDIS_CLIENT=predis

Predis supports additional connection parameters:

'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,
],

Retry and backoff (Predis)

Predis 3.4.0+ supports built-in retry configuration:

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, // Enables jitter
        ),
        env('REDIS_MAX_RETRIES', 3)
    )
],

PhpRedis

PhpRedis is installed via PECL (pre-installed in Laravel Sail). It supports these additional options: name, persistent, persistent_id, prefix, read_timeout, retry_interval, max_retries, backoff_algorithm, backoff_base, backoff_cap, timeout, and 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],
    ],
],

Retry and backoff (PhpRedis)

Configure reconnection behavior with these options. Supported backoff algorithms: 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 socket connections

Use a Unix socket instead of TCP to eliminate TCP overhead when Redis runs on the same server:

REDIS_HOST=/run/redis/redis.sock
REDIS_PORT=0

Serialization and compression

Configure a serializer and compression algorithm in the options array:

'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,
    ],

],

Available serializers: Redis::SERIALIZER_NONE (default), Redis::SERIALIZER_PHP, Redis::SERIALIZER_JSON, Redis::SERIALIZER_IGBINARY, Redis::SERIALIZER_MSGPACK. Available compression algorithms: Redis::COMPRESSION_NONE (default), Redis::COMPRESSION_LZF, Redis::COMPRESSION_ZSTD, Redis::COMPRESSION_LZ4.

Interacting with Redis

The Redis facade

The Redis facade supports dynamic methods — you can call any Redis command directly on it:

<?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)
        ]);
    }
}

Pass arguments just as you would to the Redis command:

use Illuminate\Support\Facades\Redis;

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

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

Use the command method to pass the command name and arguments explicitly:

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

Multiple connections

Switch between named connections defined in config/database.php:

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

// Default connection
$redis = Redis::connection();

Transactions

transaction() wraps Redis’s MULTI/EXEC commands. All commands in the closure run as a single atomic operation:

use Redis;
use Illuminate\Support\Facades;

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

You cannot read values from Redis inside a transaction — the entire closure is queued and executed as one atomic block by EXEC.

Lua scripts

The eval method executes a Lua script atomically and can read Redis values during execution:

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

Arguments: Lua script → number of keys → key names → additional arguments. Keys are accessed as KEYS[1], KEYS[2], etc., and extra arguments as ARGV[1], etc.

Pipelining

Send many commands at once to reduce network round trips. Commands are executed in order but not atomically:

use Redis;
use Illuminate\Support\Facades;

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

Pipelining is not atomic. For atomic multi-command operations, use transaction() or a Lua script instead.

Pub / Sub

Laravel provides a convenient interface to Redis’s publish and subscribe commands.

Subscribing

Because subscribe starts a long-running process, call it from an Artisan command:

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

Publishing

Publish messages from any part of your application:

use Illuminate\Support\Facades\Redis;

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

Wildcard subscriptions

Use psubscribe to subscribe to channels matching a pattern. The channel name is passed as the second argument:

// Subscribe to all channels
Redis::psubscribe(['*'], function (string $message, string $channel) {
    echo $message;
});

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

Quick reference

Choosing a client

Production: PhpRedis (PECL extension, best performance)
Development / restricted environments: Predis (composer require predis/predis)
Laravel Sail: PhpRedis is pre-installed

Operation comparison

Method	Use case
Facade methods	Regular Redis commands
`transaction()`	Atomic multi-command (no reads inside)
`eval()`	Lua script (atomic + reads)
`pipeline()`	Bulk commands, fewer round trips (not atomic)
`subscribe()` / `publish()`	Channel messaging (Pub/Sub)

Documentation Index

Cache

Queues

Broadcasting

​Introduction

​Choosing a client

​Configuration

​config/database.php

​Environment variables

​TLS / SSL connections

​Clusters

​Predis

​Retry and backoff (Predis)

​PhpRedis

​Retry and backoff (PhpRedis)

​Unix socket connections

​Serialization and compression

​Interacting with Redis

​The Redis facade

​Multiple connections

​Transactions

​Lua scripts

​Pipelining

​Pub / Sub

​Subscribing

​Publishing

​Wildcard subscriptions

​Quick reference

Introduction

Choosing a client

Configuration

config/database.php

Environment variables

TLS / SSL connections

Clusters

Predis

Retry and backoff (Predis)

PhpRedis

Retry and backoff (PhpRedis)

Unix socket connections

Serialization and compression

Interacting with Redis

The Redis facade

Multiple connections

Transactions

Lua scripts

Pipelining

Pub / Sub

Subscribing

Publishing

Wildcard subscriptions

Quick reference