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

> Configuración y uso de Redis en Laravel para caché, sesión, colas y Pub/Sub

Redis es un almacén clave-valor en memoria que se usa como backend en muchas funcionalidades de Laravel.
Explicamos su uso en Laravel: configuración, operaciones y Pub/Sub.

<CardGroup cols={3}>
  <Card title="Caché" icon="database" href="/es/cache">
    Usar Redis como driver de caché
  </Card>

  <Card title="Colas" icon="list" href="/es/queues">
    Usar Redis como driver de colas
  </Card>

  <Card title="Broadcasting" icon="radio" href="/es/broadcasting">
    Comunicación en tiempo real con Pub/Sub
  </Card>
</CardGroup>

## ¿Qué es Redis?

[Redis](https://redis.io) es un almacén clave-valor rápido de código abierto.
Soporta múltiples estructuras de datos (strings, hashes, listas, sets, sorted sets, etc.) y se conoce también como "servidor de estructuras de datos".

En Laravel, Redis se usa para:

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

    subgraph uses ["Usos principales"]
        C["Caché<br>Cache"]
        D["Sesión<br>Session"]
        E["Cola<br>Queue"]
        F["Broadcasting"]
    end

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

## Elección de cliente

Laravel soporta dos clientes: **PhpRedis** (extensión de PHP) y **Predis** (paquete PHP).

| Aspecto        | PhpRedis                | Predis                                                      |
| -------------- | ----------------------- | ----------------------------------------------------------- |
| Implementación | Extensión de PHP en C   | Paquete PHP puro                                            |
| Instalación    | Requiere extensión PECL | Solo con `composer require`                                 |
| Rendimiento    | Alto                    | Un poco menor que PhpRedis                                  |
| Laravel Sail   | Ya incluido por defecto | Instalación adicional                                       |
| Recomendado en | Producción              | Desarrollo o entornos donde no puedas instalar la extensión |

<Info>
  En Laravel 13 el cliente por defecto es PhpRedis. En producción se recomienda PhpRedis.
  Con Laravel Sail, PhpRedis ya viene instalado.
</Info>

## Configuración

### config/database.php

La configuración de Redis se gestiona en el array `redis` de `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 de entorno

Configura la conexión en `.env`.

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

También puedes indicarla con formato 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',
],
```

### Conexión TLS / SSL

Para cifrado TLS, indica la opción `scheme`.

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

### Clustering

Para usar varios servidores Redis como cluster, utiliza la clave `clusters`.

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

],
```

Por defecto, `options.cluster` es `redis`, es decir, se usa el clustering nativo de Redis.
Como gestiona el failover automáticamente, es la configuración recomendada en producción.

Para usar client-side sharding con Predis, elimina `options.cluster`.
Pero el client-side sharding no gestiona failover, así que solo es adecuado para datos temporales como caché.

### Configuración de Predis

Para usar Predis, instala el paquete `predis/predis` y cambia `REDIS_CLIENT` a `predis`.

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

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

Puedes añadir [parámetros de conexión](https://github.com/nrk/predis/wiki/Connection-Parameters) específicos de Predis.

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

#### Configuración de reintentos de Predis

Desde Predis 3.4.0 hay reintentos y backoff integrados. Con `max_retries` indicas el número de reintentos y con `retry` la estrategia de backoff. `retry` acepta un array cuya clave es una de las clases `NoBackoff`, `EqualBackoff` o `ExponentialBackoff`.

```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, // Activa jitter
        ],
    ],
    'max_retries' => env('REDIS_MAX_RETRIES', 3),
],
```

Con Redis cluster y Predis, configura los reintentos en la opción `parameters` de la configuración del cluster.

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

### Configuración de PhpRedis

PhpRedis se instala vía PECL (ya viene en Laravel Sail).
PhpRedis admite estas opciones adicionales:
`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],
    ],
],
```

#### Reintentos y backoff

Configura el comportamiento de reintentos ante fallos de conexión.
Algoritmos soportados: `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),
],
```

#### Conexión con socket Unix

Si conectas a un Redis en el mismo servidor, usa un socket Unix para reducir la sobrecarga de TCP.

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

#### Serialización y compresión

En PhpRedis puedes configurar la serialización y el algoritmo de compresión.

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

],
```

Serializadores soportados:

| Constante                    | Descripción                     |
| ---------------------------- | ------------------------------- |
| `Redis::SERIALIZER_NONE`     | Sin serialización (por defecto) |
| `Redis::SERIALIZER_PHP`      | Serialización de PHP            |
| `Redis::SERIALIZER_JSON`     | JSON                            |
| `Redis::SERIALIZER_IGBINARY` | igbinary                        |
| `Redis::SERIALIZER_MSGPACK`  | MessagePack                     |

Algoritmos de compresión soportados:

| Constante                 | Descripción                  |
| ------------------------- | ---------------------------- |
| `Redis::COMPRESSION_NONE` | Sin compresión (por defecto) |
| `Redis::COMPRESSION_LZF`  | LZF                          |
| `Redis::COMPRESSION_ZSTD` | Zstandard                    |
| `Redis::COMPRESSION_LZ4`  | LZ4                          |

## Operaciones con Redis

### Fachada Redis

Con la fachada `Redis` puedes ejecutar cualquier comando de Redis.
La fachada reenvía los comandos al servidor usando métodos mágicos.

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

Los argumentos de los comandos se pasan tal cual al método.

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

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

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

También puedes usar `command` para indicar explícitamente el nombre del comando y sus argumentos.

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

### Uso de varias conexiones

Define varias conexiones Redis en `config/database.php` y cambia con `connection()`.

```php theme={null}
// Obtiene una conexión con nombre
$redis = Redis::connection('connection-name');

// Obtiene la conexión por defecto
$redis = Redis::connection();
```

### Transacciones

El método `transaction()` envuelve los comandos `MULTI`/`EXEC` de Redis.
Todos los comandos dentro del closure se ejecutan de forma atómica.

```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>
  Dentro de una transacción no puedes obtener valores de Redis.
  El closure completo se ejecuta y después `EXEC` los ejecuta todos.
</Warning>

### Scripts Lua

Con `eval()` ejecutas un script Lua de forma atómica.
Es más flexible que las transacciones porque puedes leer y actualizar valores de Redis dentro del script.

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

Orden de los argumentos: script Lua → número de claves → nombres de claves… → argumentos adicionales…

`KEYS[1]`, `KEYS[2]` son los nombres de las claves; `ARGV[1]` en adelante son los argumentos adicionales.

### Pipeline

Envía muchos comandos de una vez para reducir los round trips de red.

```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 Aplicación<br>Laravel
    participant Redis

    Note over App,Redis: Normal (round trip por comando)
    App->>Redis: SET key:0 0
    Redis-->>App: OK
    App->>Redis: SET key:1 1
    Redis-->>App: OK

    Note over App,Redis: Pipeline (envío en lote)
    App->>Redis: SET key:0 0 / SET key:1 1 / ...
    Redis-->>App: OK / OK / ...
```

<Tip>
  El pipeline solo agrupa comandos en el envío; no es atómico.
  Si necesitas atomicidad, usa transacciones o scripts Lua.
</Tip>

## Pub / Sub

Con los comandos `publish` / `subscribe` puedes intercambiar mensajes a través de canales.

### Suscriptor

`subscribe()` es un proceso de larga duración, así que se invoca dentro de un comando 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;
        });
    }
}
```

### Publicador

Publica desde otra solicitud o proceso.

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

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

### Suscripción con comodines

Con `psubscribe()` puedes suscribirte a patrones.

```php theme={null}
// Se suscribe a todos los canales
Redis::psubscribe(['*'], function (string $message, string $channel) {
    echo $message;
});

// Se suscribe a los canales que coincidan con users.*
Redis::psubscribe(['users.*'], function (string $message, string $channel) {
    echo $message;
});
```

## Resumen

<AccordionGroup>
  <Accordion title="Elección de cliente">
    * **Producción**: PhpRedis (extensión PECL, alto rendimiento)
    * **Desarrollo o entornos donde no puedas instalar la extensión**: Predis (paquete Composer)
    * **Laravel Sail**: ya trae PhpRedis por defecto
  </Accordion>

  <Accordion title="Puntos de configuración de la conexión">
    * Define varias conexiones Redis en `config/database.php` según el uso (`default` / `cache`, etc.)
    * En clusters, usa la clave `clusters`
    * En producción, considera TLS y configuración de credenciales
  </Accordion>

  <Accordion title="Cuándo usar cada operación">
    | Operación                   | Uso                                                              |
    | --------------------------- | ---------------------------------------------------------------- |
    | Métodos de la fachada       | Comandos Redis habituales                                        |
    | `transaction()`             | Ejecución atómica de varios comandos (no se pueden leer valores) |
    | `eval()`                    | Script Lua (operación atómica con lecturas incluidas)            |
    | `pipeline()`                | Envío rápido de muchos comandos (no atómico)                     |
    | `subscribe()` / `publish()` | Mensajería por canales (Pub/Sub)                                 |
  </Accordion>
</AccordionGroup>


## Related topics

- [Caché](/es/cache.md)
- [Laravel Sail](/es/sail.md)
- [Personalización del rate limiting](/es/advanced/rate-limiting.md)
- [Laravel Pulse](/es/pulse.md)
- [Colas y jobs](/es/queues.md)