> ## 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

> Configuration et utilisation de Redis dans Laravel : cache, session, queue, Pub/Sub.

Redis est un store clé/valeur en mémoire, utilisé comme backend par de nombreuses fonctionnalités Laravel.
De la configuration aux opérations et au Pub/Sub, voici comment utiliser Redis avec Laravel.

<CardGroup cols={3}>
  <Card title="Cache" icon="database" href="/fr/cache">
    Redis comme driver de cache.
  </Card>

  <Card title="Queue" icon="list" href="/fr/queues">
    Redis comme driver de queue.
  </Card>

  <Card title="Broadcasting" icon="radio" href="/fr/broadcasting">
    Communication temps réel via Pub/Sub.
  </Card>
</CardGroup>

## Qu'est-ce que Redis

[Redis](https://redis.io) est un store clé/valeur haute performance open source.
Il gère différents types (chaînes, hashes, listes, sets, sorted sets…) — c'est un « data structure server ».

Usages fréquents dans Laravel :

```mermaid theme={null}
flowchart LR
    A["Application<br>Laravel"] --> B["Redis"]

    subgraph uses ["Usages"]
        C["Cache"]
        D["Session"]
        E["Queue"]
        F["Broadcasting"]
    end

    B --> C
    B --> D
    B --> E
    B --> F
```

## Choix du client

Laravel supporte **PhpRedis** (extension) et **Predis** (package PHP).

| Aspect         | PhpRedis           | Predis                          |
| -------------- | ------------------ | ------------------------------- |
| Implémentation | Extension PHP en C | Package PHP pur                 |
| Installation   | Extension PECL     | `composer require`              |
| Performance    | Haute              | Légèrement inférieure           |
| Laravel Sail   | Inclus par défaut  | À installer                     |
| Recommandé     | Production         | Dev / environnements restreints |

<Info>
  Sous Laravel 13, le client par défaut est PhpRedis. Recommandé en production.
  Laravel Sail inclut PhpRedis.
</Info>

## Configuration

### `config/database.php`

```php theme={null}
'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'),
    ],

],
```

### Variables d'environnement

```ini theme={null}
REDIS_CLIENT=phpredis
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=null
REDIS_DB=0
REDIS_CACHE_DB=1
```

Vous pouvez utiliser une URL :

```php theme={null}
'default' => [
    'url' => 'tcp://127.0.0.1:6379?database=0',
],

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

### TLS / SSL

```php theme={null}
'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'),
],
```

### Cluster

```php theme={null}
'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'),
            ],
        ],
    ],

],
```

Par défaut, `options.cluster = redis` utilise le clustering natif Redis avec failover automatique — recommandé en production.

Pour le sharding côté client avec Predis, retirez `options.cluster` (sans failover, adapté à des données éphémères).

### Configuration Predis

Installez le package et changez le client :

```shell theme={null}
composer require predis/predis
```

```ini theme={null}
REDIS_CLIENT=predis
```

Paramètres de connexion spécifiques à [Predis](https://github.com/nrk/predis/wiki/Connection-Parameters) :

```php theme={null}
'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 Predis

À partir de Predis 3.4.0, `max_retries` et `retry` (avec `NoBackoff`, `EqualBackoff` ou `ExponentialBackoff`) sont disponibles.

```php theme={null}
use Predis\Retry\Strategy\ExponentialBackoff;

'default' => [
    'url' => env('REDIS_URL'),
    // ...
    'retry' => [
        ExponentialBackoff::class => [
            env('REDIS_BACKOFF_BASE', 100),
            env('REDIS_BACKOFF_CAP', 1000),
            true, // Jitter
        ],
    ],
    'max_retries' => env('REDIS_MAX_RETRIES', 3),
],
```

En cluster, réglez le retry dans `parameters`.

```php theme={null}
use Predis\Retry\Strategy\NoBackoff;

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

'options' => [
    'cluster' => env('REDIS_CLUSTER', 'redis'),
    'parameters' => [
        'retry' => [
            NoBackoff::class => [],
        ],
        'max_retries' => env('REDIS_MAX_RETRIES', 3),
    ],
],
```

### Configuration PhpRedis

PhpRedis s'installe via PECL (déjà présent avec Laravel Sail).
Options supplémentaires : `name`, `persistent`, `persistent_id`, `prefix`, `read_timeout`, `retry_interval`, `max_retries`, `backoff_algorithm`, `backoff_base`, `backoff_cap`, `timeout`, `context`.

```php theme={null}
'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 et backoff

Algorithmes supportés : `default`, `decorrelated_jitter`, `equal_jitter`, `exponential`, `uniform`, `constant`.

```php theme={null}
'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),
],
```

#### Socket Unix

Sur le même serveur, économisez l'overhead TCP.

```ini theme={null}
REDIS_HOST=/run/redis/redis.sock
REDIS_PORT=0
```

#### Sérialisation et compression

```php theme={null}
'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,
    ],

],
```

Sérialiseurs :

| Constante                    | Description       |
| ---------------------------- | ----------------- |
| `Redis::SERIALIZER_NONE`     | Aucune (défaut)   |
| `Redis::SERIALIZER_PHP`      | Sérialisation PHP |
| `Redis::SERIALIZER_JSON`     | JSON              |
| `Redis::SERIALIZER_IGBINARY` | igbinary          |
| `Redis::SERIALIZER_MSGPACK`  | MessagePack       |

Compressions :

| Constante                 | Description     |
| ------------------------- | --------------- |
| `Redis::COMPRESSION_NONE` | Aucune (défaut) |
| `Redis::COMPRESSION_LZF`  | LZF             |
| `Redis::COMPRESSION_ZSTD` | Zstandard       |
| `Redis::COMPRESSION_LZ4`  | LZ4             |

## Utiliser Redis

### Façade Redis

Exécutez toute commande Redis via la façade. Elle transmet magiquement les appels.

```php theme={null}
<?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)
        ]);
    }
}
```

Passez les arguments directement.

```php theme={null}
use Illuminate\Support\Facades\Redis;

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

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

Ou explicitement via `command` :

```php theme={null}
$values = Redis::command('lrange', ['name', 5, 10]);
```

### Plusieurs connexions

Basculez avec `connection()`.

```php theme={null}
$redis = Redis::connection('connection-name');

$redis = Redis::connection();
```

### Transactions

`transaction()` encapsule `MULTI`/`EXEC` de Redis. Toutes les commandes s'exécutent de manière atomique.

```php theme={null}
use Redis;
use Illuminate\Support\Facades;

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

<Warning>
  Les lectures ne sont pas possibles dans une transaction : `EXEC` exécute tout en bloc à la fin.
</Warning>

### Scripts Lua

`eval()` exécute atomiquement un script Lua qui peut lire et écrire.

```php theme={null}
$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 : script Lua → nombre de clés → clés… → args supplémentaires.

`KEYS[1]`, `KEYS[2]` = clés ; `ARGV[1]…` = args.

### Pipeline

Envoyez beaucoup de commandes en une fois pour économiser les allers-retours réseau.

```php theme={null}
use Redis;
use Illuminate\Support\Facades;

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

```mermaid theme={null}
sequenceDiagram
    participant App as Application<br>Laravel
    participant Redis

    Note over App,Redis: Sans pipeline (aller-retour par commande)
    App->>Redis: SET key:0 0
    Redis-->>App: OK
    App->>Redis: SET key:1 1
    Redis-->>App: OK

    Note over App,Redis: Pipeline (envoi groupé)
    App->>Redis: SET key:0 0 / SET key:1 1 / ...
    Redis-->>App: OK / OK / ...
```

<Tip>
  Le pipeline groupe l'envoi mais n'est pas atomique. Pour l'atomicité, utilisez une transaction ou un script Lua.
</Tip>

## Pub / Sub

Utilisez `publish` / `subscribe` pour communiquer par canaux.

### Souscripteur

Long-running : dans une commande Artisan.

```php theme={null}
<?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;
        });
    }
}
```

### Publisher

Depuis une autre requête / process :

```php theme={null}
use Illuminate\Support\Facades\Redis;

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

### Souscription avec wildcard

`psubscribe()` supporte les patterns.

```php theme={null}
// Tous les canaux
Redis::psubscribe(['*'], function (string $message, string $channel) {
    echo $message;
});

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

## Récapitulatif

<AccordionGroup>
  <Accordion title="Choix du client">
    * **Production** : PhpRedis (extension PECL, haute performance)
    * **Dev / environnement contraint** : Predis (Composer)
    * **Laravel Sail** : PhpRedis inclus
  </Accordion>

  <Accordion title="Configuration">
    * Connexions multiples via `config/database.php` (par exemple `default` / `cache`)
    * `clusters` pour un cluster
    * En production, envisagez TLS et authentification
  </Accordion>

  <Accordion title="Opérations">
    | Opération                   | Usage                                   |
    | --------------------------- | --------------------------------------- |
    | Méthodes de façade          | Commandes Redis courantes               |
    | `transaction()`             | Exécution atomique (lecture impossible) |
    | `eval()`                    | Script Lua atomique avec lecture        |
    | `pipeline()`                | Envoi en bloc (non atomique)            |
    | `subscribe()` / `publish()` | Pub/Sub                                 |
  </Accordion>
</AccordionGroup>


## Related topics

- [Cache](/fr/cache.md)
- [Laravel Sail](/fr/sail.md)
- [Queues et jobs](/fr/queues.md)
- [Personnalisation de la limitation de débit](/fr/advanced/rate-limiting.md)
- [Laravel Reverb](/fr/reverb.md)