Laravel Redis Sentinel Laravel Package

Getting Started

Redis Sentinel support for Laravel. It registers a Sentinel-aware Redis connector so Cache, Session, Queue, and Redis:: facades can talk to a highly-available Sentinel-managed Redis master without any application code changes — only configuration differs from a normal single-host setup.

composer require namoshek/laravel-redis-sentinel

The service provider is auto-discovered; there is nothing to register by hand. In Laravel 11+/12/13 the package hooks into the framework's Redis manager rather than replacing the Redis facade, so existing Redis::connection(...) calls keep working.

First place to look: config/database.php → redis. A Sentinel connection is defined like any other connection, but instead of a single host/port you declare the Sentinel service (master group) name and the list of Sentinel endpoints to ask for the current master:

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

    'default' => [
        'driver'   => 'sentinel',                 // <- provided by this package
        'service'  => env('REDIS_SENTINEL_SERVICE', 'mymaster'),
        'hosts'    => [                            // sentinel nodes, not redis nodes
            ['host' => env('REDIS_SENTINEL_HOST_1', '127.0.0.1'), 'port' => env('REDIS_SENTINEL_PORT_1', 26379)],
            ['host' => env('REDIS_SENTINEL_HOST_2', '127.0.0.2'), 'port' => env('REDIS_SENTINEL_PORT_2', 26379)],
        ],
        'password' => env('REDIS_PASSWORD'),
        'database' => env('REDIS_DB', 0),
        'timeout'  => 1.0,
    ],
],

Check the package's README/published config for the exact key names and available options in your installed version before rolling this into production — key names have stayed stable but the option set (timeout, persistent, prefix, per-connection options) is worth reading once.

Verify from a shell (the Sentinel nodes themselves are plain Redis with a sentinel role):

redis-cli -p 26379 SENTINEL get-master-addr-by-name mymaster

Then confirm Laravel resolves the connection through the master:

php artisan tinker
>>> Redis::connection()->ping();
>>> Redis::set('smoke', 'ok'); Redis::get('smoke');

First realistic use case: you already run Redis in HA (three Sentinels, one master, replicas) for cache/session/queue, and Laravel is the last piece still pinned to a single host. You swap the host list for the sentinel list, point CACHE_STORE/SESSION_DRIVER/QUEUE_CONNECTION at that connection name, and nothing else in the app changes.

Implementation Patterns

Separate connections per workload. Don't funnel cache, sessions, and queues through one Sentinel connection. Declare several connections in config/database.php (e.g. sentinel-cache on database 1, sentinel-queue on database 2) and select them by name via the connection key in config/cache.php, config/session.php, and config/queue.php. Each connection resolves the master independently, which also limits the blast radius of a stale connection during failover.

Cache/Session/Queue wiring. Set:

// config/cache.php
'redis' => ['driver' => 'redis', 'connection' => 'sentinel-cache', ...],

// config/session.php
'driver' => 'redis', 'connection' => 'sentinel-session',

Horizon is the notable exception — see the gotchas below, since Horizon reads its own connection config from config/horizon.php.

Keep the standard connection as a fallback. A pattern that pays off in development and CI: keep the ordinary default connection with a single host, and add Sentinel connections alongside it. .env decides which one the app uses. Local dev and CI then need no Sentinel cluster at all, and you get a clean A/B when something misbehaves in staging.

Env-driven Sentinel lists. Sentinel node addresses are infrastructure, not app config. Loop or enumerate them as REDIS_SENTINEL_HOST_1..N env vars and build the list in config/database.php. This keeps deploy-time variation out of code and lets you add a fourth Sentinel node without a PHP change.

One config per environment. Because Sentinel resolves to whichever node is master at connection time, the same config works identically against staging and production clusters — only the host list, service name, and password differ. Avoid encoding master IPs anywhere.

Integration tips.

• Use the Redis facade for raw access (Redis::connection('sentinel-cache')->keys(...)) and the higher-level drivers for everything else; the Sentinel layer is transparent below both.
• Prefer phpredis for production Sentinel work unless you have a reason not to — it's the better-tested path and gives you persistent connections and timeouts that matter more in an HA setup.
• Set a short timeout (sub-second to ~1s). When a Sentinel node is unhealthy, a long timeout turns every request into a slow request; the connector should move to the next node quickly.
• Use the same Sentinel-enabled connection for predis-based and phpredis-based consumers consistently; mixing clients in one app is a common source of "works in web, fails in worker" reports.
• Keep queue workers, schedulers, and Horizon on the same connection name so a single config change fans out everywhere.

Testing. Run a disposable Sentinel stack (docker-compose with redis:7, one master, two replicas, three sentinels) in CI and point a feature test at it. Simulate failover with redis-cli -p 26379 SENTINEL failover mymaster and assert your app recovers within your reconnect expectations — this is the one test that actually exercises the package.

Gotchas and Tips

Failover is not automatic for long-lived processes. The connector asks Sentinel for the master when it connects. A queue worker or Octane server that connected three hours ago is still holding a socket to the old master after a failover. Symptoms: writes silently failing, READONLY You can't write against a read only replica. Plan for it: restart workers on deploy, keep worker --timeout/--max-time short enough that connections turn over, and set up a health check that restarts consumers after a topology change.

Horizon needs its own attention. Horizon builds connections from config/horizon.php and holds them for a long time; a Sentinel-backed default connection is not automatically used for Horizon's own supervisor/worker connections. Configure the Horizon connection explicitly and budget for a Horizon restart after any failover, or you'll be debugging phantom job stalls.

Sentinel hosts ≠ Redis hosts. The most common misconfiguration is pasting Redis master/replica addresses into the Sentinel host list. Sentinel listens on port 26379 by default and speaks a different protocol; the connector uses it only to discover the master. Verify with SENTINEL get-master-addr-by-name.

The driver key is what activates the package. If you omit 'driver' => 'sentinel', Laravel's stock connector takes over and silently tries to connect straight to whatever host you left in the array — usually producing a confusing connection-refused to 127.0.0.1:6379 rather than anything Sentinel-related. If Sentinel support "doesn't work", check that first.

Password/auth mismatches. Sentinel itself may be unauthenticated while the Redis master requires a password (or vice versa). Two different credentials can be in play; make sure the password you set is the Redis one and that Sentinel access (if requirepass/ACL is enabled on the sentinels) is handled at the infrastructure level.

Debugging checklist, in order: redis-cli -p 26379 SENTINEL get-master-addr-by-name <service> → redis-cli -h <master> -p 6379 ping → php artisan tinker Redis::connection('your-sentinel-connection')->ping() → check storage/logs/laravel.log for the connector's exception, which usually names the sentinel host it failed on. config:clear after editing config/database.php — a cached config is the second-most-common cause of "my change did nothing".

Extension points. The connector/connection classes are ordinary resolvable classes; if you need custom behaviour (extra retry logic, a metrics wrapper, resolving master from a secret manager instead of env), extend the provided classes and rebind them rather than forking the package. Keeping that surface small makes minor-version upgrades painless.

Version posture for this release (v1.3.0). The only functional change is Laravel 13 support; everything else is dependabot bumps of GitHub Actions (actions/checkout 5→6, actions/cache 4→5, sonarqube-scan-action 6→7) which have zero impact on consumers. No breaking changes, no deprecations, no config changes — a routine upgrade. The practical takeaway: if you're planning a Laravel 12→13 move and Redis Sentinel is in your stack, this package is no longer a blocker. If you're staying on 11/12, upgrading is still safe but not urgent; pin it and let it ride with your next dependency update. Keep an eye on the framework version constraint in composer.json when you bump Laravel, since Redis internals (RedisManager, connector interfaces) are the part of the framework most likely to shift between majors.