PHPackages tcgunel/laravel-redis-sentinel-drivers - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Caching](/categories/caching) 4. / 5. tcgunel/laravel-redis-sentinel-drivers ActiveLibrary[Caching](/categories/caching) tcgunel/laravel-redis-sentinel-drivers ====================================== Redis Sentinel integration for Laravel and Lumen. v3.0.0(2y ago)03MITPHPPHP >=5.6.4 Since Nov 24Pushed 2y agoCompare [ Source](https://github.com/tcgunel/laravel-redis-sentinel-drivers)[ Packagist](https://packagist.org/packages/tcgunel/laravel-redis-sentinel-drivers)[ RSS](/packages/tcgunel-laravel-redis-sentinel-drivers/feed)WikiDiscussions 2.x Synced 2mo ago READMEChangelogDependencies (13)Versions (3)Used By (0) Fork of monospice/laravel-redis-sentinel-drivers Laravel Drivers for Redis Sentinel ================================== [](#laravel-drivers-for-redis-sentinel) [![Build Status](https://camo.githubusercontent.com/d76e82f3a1e9fdfe0212b6c0e3724276d3a11c94c7c270865700525c9d3ee16a/68747470733a2f2f7472617669732d63692e6f72672f6d6f6e6f73706963652f6c61726176656c2d72656469732d73656e74696e656c2d647269766572732e7376673f6272616e63683d322e78)](https://travis-ci.org/monospice/laravel-redis-sentinel-drivers)[![Scrutinizer Code Quality](https://camo.githubusercontent.com/e4f6a575744db2e439b252ed1bff4ec9c6201b094e7df320ba64c88c6033da21/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f6d6f6e6f73706963652f6c61726176656c2d72656469732d73656e74696e656c2d647269766572732f6261646765732f7175616c6974792d73636f72652e706e673f623d322e78)](https://scrutinizer-ci.com/g/monospice/laravel-redis-sentinel-drivers/?branch=2.x)[![Latest Stable Version](https://camo.githubusercontent.com/793412fe526de0d94be94ae40ffe4e5bdee04700974009b2ed92804624209e88/68747470733a2f2f706f7365722e707567782e6f72672f6d6f6e6f73706963652f6c61726176656c2d72656469732d73656e74696e656c2d647269766572732f762f737461626c65)](https://packagist.org/packages/monospice/laravel-redis-sentinel-drivers)[![Total Downloads](https://camo.githubusercontent.com/c3af8eaa2f43b9824630e96ba38246389d1d9eb01338156b14289b447a45b807/68747470733a2f2f706f7365722e707567782e6f72672f6d6f6e6f73706963652f6c61726176656c2d72656469732d73656e74696e656c2d647269766572732f646f776e6c6f616473)](https://packagist.org/packages/monospice/laravel-redis-sentinel-drivers)[![License](https://camo.githubusercontent.com/b1a3a6b517745a5e6d9f80113796a0274db62927b06220ac3d3d1416d05e3c1c/68747470733a2f2f706f7365722e707567782e6f72672f6d6f6e6f73706963652f6c61726176656c2d72656469732d73656e74696e656c2d647269766572732f6c6963656e7365)](#license) #### Redis Sentinel integration for Laravel and Lumen. [](#redis-sentinel-integration-for-laravel-and-lumen) [Redis Sentinel](https://redis.io/topics/sentinel) facilitates high-availability, monitoring, and load-balancing for Redis servers configured for master-slave replication. [Laravel](https://laravel.com) includes built-in support for Redis, but we cannot configure Sentinel setups flexibly out-of-the-box. This limits configuration of Sentinel to a single service. For instance, if we wish to use Redis behind Sentinel for both the cache and session in Laravel's API, we cannot set separate Redis databases for for both types of data like we can in a standard, single-server Redis setup without Sentinel. This causes issues when we need to clear the cache, because Laravel erases stored session information as well. This package wraps the configuration of Laravel's broadcasting, cache, session, and queue APIs for Sentinel with the ability to set options for our Redis services independently. It adds Sentinel support for [Laravel Horizon](#laravel-horizon)and fixes other compatibility issues. We configure the package separately from Laravel's standard Redis configuration so we can choose to use the Sentinel connections as needed by the environment. A developer may use a standalone Redis server in their local environment, while production environments operate a Redis Sentinel set of servers. Contents -------- [](#contents) - [Quickstart **(TL;DR)**](#quickstart-tldr) - [Requirements](#requirements) - [Installation](#installation) - [Configuration Options](#configuration) - [Environment-Based Configuration](#environment-based-configuration) - [Standard Laravel Configuration Files](#using-standard-configuration-files) - [Package Configuration File](#using-a-package-configuration-file) - [Hybrid Configuration](#hybrid-configuration) - [Override the Standard Redis API](#override-the-standard-redis-api) - [Executing Redis Commands (RedisSentinel Facade)](#executing-redis-commands-redissentinel-facade) - [Dependency Injection](#dependency-injection) - [Other Sentinel Considerations](#other-sentinel-considerations) - [Laravel Horizon](#laravel-horizon) - [Testing](#testing) - [License](#license) - [Appendix: Environment Variables](#appendix-environment-variables) - [Appendix: Configuration Examples](#appendix-configuration-examples) Requirements ------------ [](#requirements) - PHP 5.4 or greater - [Redis](https://redis.io) 2.8 or greater (for Sentinel support) - [Predis](https://github.com/nrk/predis) 1.1 or greater (for Sentinel client support) - [Laravel](https://laravel.com) or [Lumen](https://lumen.laravel.com) 5.0 or greater (4.x doesn't support the required Predis version) **Note:** Laravel 5.4 introduced the ability to use the [PhpRedis](https://github.com/phpredis/phpredis)extension as a Redis client for the framework. This package does not yet support the PhpRedis option. This Readme assumes prior knowledge of configuring [Redis](https://redis.io) for [Redis Sentinel](https://redis.io/topics/sentinel) and [using Redis with Laravel](https://laravel.com/docs/redis) or [Lumen](https://lumen.laravel.com/docs/cache). Installation ------------ [](#installation) We're using Laravel, so we'll install through Composer, of course! #### For Laravel/Lumen 5.4 and above: [](#for-laravellumen-54-and-above) ``` composer require monospice/laravel-redis-sentinel-drivers ``` #### For Laravel/Lumen 5.3 and below: [](#for-laravellumen-53-and-below) ``` composer require monospice/laravel-redis-sentinel-drivers:^1.0 ``` **Note:** According to the Laravel release schedule, all Laravel versions prior to 5.4 exited their active development and support periods in August of 2017. After December, 2017, this package will no longer provide feature releases on the `1.x` branch for Laravel versions earlier than 5.4. If the project does not already use Redis with Laravel, this will install the [Predis](https://github.com/nrk/predis) package as well. #### Register the Service Provider [](#register-the-service-provider) Laravel 5.5 brings [package discovery](https://laravel.com/docs/packages#package-discovery)! *No service provider registration required in Laravel 5.5+.* To use the drivers in Laravel 5.4 and below, add the package's service provider to *config/app.php*: ``` 'providers' => [ ... Monospice\LaravelRedisSentinel\RedisSentinelServiceProvider::class, ... ], ``` In Lumen, register the service provider in *bootstrap/app.php*: ``` $app->register(Monospice\LaravelRedisSentinel\RedisSentinelServiceProvider::class); ``` Quickstart (TL;DR) ------------------ [](#quickstart-tldr) After [installing](#installation) the package, set the following in *.env*: ``` CACHE_DRIVER=redis-sentinel SESSION_DRIVER=redis-sentinel QUEUE_CONNECTION=redis-sentinel # Laravel >= 5.7 QUEUE_DRIVER=redis-sentinel # Laravel = 5.7 QUEUE_DRIVER=redis-sentinel # Laravel [ 'default' => [ [ 'host' => env('REDIS_HOST', 'localhost'), 'port' => env('REDIS_PORT', 26379), ], ], 'options' => [ 'service' => env('REDIS_SENTINEL_SERVICE', 'mymaster'), 'parameters' => [ 'password' => env('REDIS_PASSWORD', null), 'database' => 0, ], ], ], ``` As you can see, our `'default'` connection includes the address or hostname of the Sentinel server and the port that the application connects to (typically 26379). Because Sentinel doesn't support authentication directly, we'll set the password for our Redis server in the `'parameters'` array, which also includes the Redis database to use for the connection. The `'service'` option declares the service name of the set of Redis servers configured in Sentinel as a service. Take note of the sub-array in the top level array for the `'default'`connection. If we choose to add additional Sentinel servers to this configuration, we'll wrap the definition of each host in another array, like we can see in the following section. Of course, be sure to add the environment configuration variables from the example above to *.env*. #### Advanced Configuration [](#advanced-configuration) The configuration block above is almost a drop-in replacement for Laravel's built-in `'redis'` connection configuration that we could use to configure an application for Sentinel without this package. However, we cannot configure Laravel's standard Redis connections for anything more complex than this basic Sentinel setup because of limitations in the way Laravel parses its Redis configuration. A single Sentinel server or connection is typically insufficient for highly-available or complex applications. Read the [examples in the appendix](#appendix-configuration-examples) for more robust configuration instructions: - [Connections with Multiple Sentinel Hosts](#multi-sentinel-connection-configuration) - [Multiple Service-Specific Connections](#multi-service-connection-configuration) #### Other Sentinel Connection Options [](#other-sentinel-connection-options) The Predis client supports some additional configuration options that determine how it handles connections to Sentinel servers. We can add these to the global `'options'` array for all Sentinel connections or to a local `'options'` array for a single connection. The default values are shown below: ``` 'options' => [ ... // The default amount of time (in seconds) the client waits before // determining that a connection attempt to a Sentinel server failed. 'sentinel_timeout' => 0.100, // The default number of attempts to retry a command when the client fails // to connect to a Redis or Sentinel server. A value of 0 instructs the // client to throw an exception after the first failed attempt, while a // value of -1 causes the client to continue to retry commands indefinitely. 'retry_limit' => 20, // The default amount of time (in milliseconds) that the client waits before // attempting to contact another Sentinel server or retry a command if the // previous server did not respond. 'retry_wait' => 1000, // Instructs the client to query the first reachable Sentinel server for an // updated set of Sentinels each time the client needs to establish a // connection with a Redis master or replica. 'update_sentinels' => false, ], ``` ### Broadcasting, Cache, Session, and Queue Drivers [](#broadcasting-cache-session-and-queue-drivers) After configuring the Sentinel database connections, we can instruct Laravel to use these connections for the application's other redis-enabled services. Remember that we don't need to set Sentinel connections for all of these services. We could select a standard Redis connection for one and a Sentinel connection for another, if desired, but we likely want to take advantage of Sentinel for all of our Redis connections if it's available. **Note:** We can omit (or remove) the following configuration blocks entirely and the package will configure these services for us. If we created custom Sentinel connections as above, we may need to [declare those connection names](#broadcast_redis_connection-broadcast_redis_sentinel_connection). #### Broadcasting [](#broadcasting) Add the following connection definition to *config/broadcasting.php* in the `'connections'` array: ``` 'connections' => [ ... 'redis-sentinel' => [ 'driver' => 'redis-sentinel', 'connection' => 'default', ], ], ``` ...and change the `BROADCAST_DRIVER` environment variable to `redis-sentinel`in *.env*. If the application contains a specific connection in the `'redis-sentinel'`database configuration for the event broadcasting, replace `'default'` with its name. #### Cache [](#cache) Add the following store definition to *config/cache.php* in the `'stores'`array: ``` 'stores' => [ ... 'redis-sentinel' => [ 'driver' => 'redis-sentinel', 'connection' => 'default', ], ], ``` ...and change the `CACHE_DRIVER` environment variable to `redis-sentinel` in *.env*. If the application contains a specific connection in the `'redis-sentinel'`database configuration for the cache, replace `'default'` with its name. #### Session [](#session) Change the `SESSION_DRIVER` environment variable to `redis-sentinel` in *.env*. Then, in *config/session.php*, set the `'connection'` directive to `'default'`, or the name of the specific connection created for storing sessions from the `'redis-sentinel'` database configuration. #### Queue [](#queue) Add the following connection definition to *config/queue.php* in the `'connections'` array: ``` 'connections' => [ ... 'redis-sentinel' => [ 'driver' => 'redis-sentinel', 'connection' => 'default', 'queue' => 'default', 'retry_after' => 90, // Laravel >= 5.4.30 'expire' => 90, // Laravel < 5.4.30 ], ], ``` ...and change the `QUEUE_CONNECTION` (Laravel 5.7+) or `QUEUE_DRIVER` (Laravel <= 5.6) environment variable to `redis-sentinel` in *.env*. If the application contains a specific connection in the `'redis-sentinel'`database configuration for the queue, replace `'connection' => 'default'` with its name. Using a Package Configuration File ---------------------------------- [](#using-a-package-configuration-file) Lumen projects don't include configuration files by default. Instead, by convention, Lumen reads configuration information from the environment. If we wish to configure this package through config files as described in the [previous section](#using-standard-configuration-files), rather than using the [environment-based configuration](#environment-based-configuration), we can add a single package configuration file: *config/redis-sentinel.php*. This alleviates the need to create several standard config files in Lumen. The package configuration file contains elements that the package merges back into the main configuration locations at runtime. To illustrate, when the custom *redis-sentinel.php* file contains: ``` return [ 'database' => 'redis-sentinel' => [ /* ...Redis Sentinel connections... */ ] ] ]; ``` ...the package will set the `database.redis-sentinel` configuration value from the value of `redis-sentinel.database.redis-sentinel` when the application boots [unless the key already exists](#hybrid-configuration). We can customize the package's [internal config file](config/redis-sentinel.php)by copying it into our project's *config/* directory and changing the values as needed. Lumen users may need to create this directory if it doesn't exist. A custom package config file needs only to contain the top-level elements that developer wishes to customize: in the code shown above, the custom config file only overrides the package's default configuration for Redis Sentinel connections, so the package will still automatically configure the broadcasting, cache, session, and queue services using environment variables. Hybrid Configuration -------------------- [](#hybrid-configuration) Although unnecessary in most cases, developers may combine two or more of the configuration methods provided by this package. For example, an application may contain a [standard](#using-standard-configuration-files) or [package](#using-a-package-configuration-file) config file that defines the Redis Sentinel connections, but rely on the package's automatic [environment-based configuration](#environment-based-configuration) to set up the cache, session, queue, and broadcasting services for Sentinel. The package uses configuration data in this order of precedence: 1. Standard Laravel configuration files 2. A custom package configuration file 3. Automatic environment-based configuration This means that package-specific values in the standard config files override values in a custom package config file, which, in turn, override the package's default automatic configuration through environment variables. In other words, a custom package config file inherits the values from the package's default configuration that it does not explicitly declare, and the main application configuration receives the values from both of these that it does not provide in a standard config file. Override the Standard Redis API ------------------------------- [](#override-the-standard-redis-api) This package adds Redis Sentinel drivers for Laravel's caching, session, and queue APIs, and the developer may select which of these to utilize Sentinel connections for. However, Laravel also provides [an API](https://laravel.com/docs/redis#interacting-with-redis)for interacting with Redis directly through the `Redis` facade, or through the Redis connection manager which we can resolve through the application container (`app('redis')`, dependency injection, etc.). When installed, this package does not impose the use of Sentinel for all Redis requests. In fact, we can choose to use Sentinel connections for some features and continue to use Laravel's standard Redis connections for others. By default, this package does not replace Laravel's built-in Redis API. As an example, we may decide to use Sentinel connections for the application's cache and sessions, but directly interact with a single Redis server using Laravel's standard Redis connections. That said, this package provides the option to override Laravel's Redis API so that any Redis commands use the Sentinel connection configuration defined by the `'redis-sentinel'` database driver. To use this feature, add the following configuration directive to the root of the `'redis'` connection definition in *config/database.php* (if not using [environment-based configuration](#environment-based-configuration)): ``` 'redis' => [ ... 'driver' => env('REDIS_DRIVER', 'default'), ... ], ``` ...and add the environment variable `REDIS_DRIVER` to *.env* with the value `redis-sentinel`. When enabled, Redis commands executed through the `Redis` facade or the `redis`service (`app('redis')`, etc) will operate using the Sentinel connections. This makes it easier for developers to use a standalone Redis server in their local environments and switch to a full Sentinel set of servers in production. **Note:** When using the package with [Laravel Horizon](#laravel-horizon), this change will cause Horizon to run over a Sentinel connection as well. Executing Redis Commands (RedisSentinel Facade) ----------------------------------------------- [](#executing-redis-commands-redissentinel-facade) If we need to send Redis commands to Redis instances behind a Sentinel server directly, such as we can through the `Redis` facade, but we don't want to [override Laravel's Redis API](#override-the-standard-redis-api) as above, we can use the `RedisSentinel` facade provided by this package or resolve the `redis-sentinel`service from the application container: ``` // Uses the 'default' connection defined in the 'redis-sentinel' config block: RedisSentinel::get('some-key'); app('redis-sentinel')->get('some-key'); // Uses the 'default' connection defined in the standard 'redis' config block: Redis::get('some-key'); app('redis')->get('some-key'); ``` This provides support for uncommon use cases for which an application may need to connect to both standard Redis servers and Sentinel clusters in the same environment. When possible, follow the approach described in the previous section to uniformly connect to Sentinel throughout the application to decouple the code from the Redis implementation. The facade is not auto-aliased in Laravel 5.5+ for future compatibility with the PhpRedis extension. To enable the facade in Laravel, add the following alias to the `'aliases'` array in *config/app.php*: ``` 'aliases' => [ ... 'RedisSentinel' => Monospice\LaravelRedisSentinel\RedisSentinel::class, ... ], ``` In Lumen, add the alias to *bootstrap/app.php*: ``` class_alias('Monospice\LaravelRedisSentinel\RedisSentinel', 'RedisSentinel'); ``` ### Dependency Injection [](#dependency-injection) For those that prefer to declare the Redis Sentinel manager as a dependency of a class rather than using the facade, we can type-hint the interface that the container will resolve when building an object from the container: ``` use Monospice\LaravelRedisSentinel\Contracts\Factory as RedisSentinel; ... public function __construct(RedisSentinel $sentinel) { $sentinel->get('some-key'); } ``` The above explicitly requests an instance of the package's Sentinel service. If we [override the Redis API](#override-the-standard-redis-api), we can use the standard Redis contract instead, and the application will inject the appropriate service based on the configuration: ``` use Illuminate\Contracts\Redis\Factory as Redis; ... public function __construct(Redis $redis) { // Either a Sentinel connection or a standard Redis connection depending on // the value of REDIS_DRIVER or config('database.redis.driver'): $redis->get('some-key'); } ``` Other Sentinel Considerations ----------------------------- [](#other-sentinel-considerations) The following sections describe some characteristics to keep in mind when working with Sentinel connections. ### Read and Write Operations [](#read-and-write-operations) To spread load between available resources, the client attempts to execute read operations on Redis slave servers when initializing a connection. Commands that write data will always execute on the master server. ### Transactions [](#transactions) All commands in a transaction, even read-only commands, execute on the master Redis server. When it makes sense to do so, avoid calling read commands within a transaction to improve load-balancing. If a transaction aborts because of a connection failure, the package attempts to reconnect and retry the transaction until it exhausts the configured number of allowed attempts (`retry_limit`), or until the entire transaction succeeds. **Important:** Predis provides a specialized MULTI/EXEC abstraction that we can obtain by calling `transaction()` with no arguments. This API is *not*protected by Sentinel connection failure handling. For high-availability, use the Laravel API by passing a closure to `transaction()`. ### Publish/Subscribe [](#publishsubscribe) For PUB/SUB messaging, the client publishes messages to the master server. When subscribing, the package attempts to connect to a slave server first before falling-back to the master. Like with read operations, this helps to distribute the load away from the master because messages published to the master propagate to each of the slaves. Applications with long-running subscribers need to extend the timeout of the connection or disable it by setting `read_write_timeout` to `0`. Additionally, we also need to extend or disable the `timeout` configuration directive on the Redis servers that the application subscribes to. When a subscriber connection fails, the package will attempt to reconnect to another server and resume listening for messages. We may want to set the value of `retry_limit` to `-1` on connections with long-running subscribers so that the client continues to retry forever. Note that a subscriber may miss messages published to a channel while re-establishing the connection. **Important:** Predis provides a PUB/SUB consumer that we can obtain by calling `pubSubLoop()` with no arguments. This API is *not* protected by Sentinel connection failure handling. For high-availability, use the Laravel API by passing a closure to `subscribe()` or `psubscribe()`. Laravel Horizon --------------- [](#laravel-horizon) Versions 2.4.0 and greater of this package provide for the use of Sentinel connections with the [Laravel Horizon](https://horizon.laravel.com) queue management tool in compatible applications (Laravel 5.5+). After [installing Horizon](https://laravel.com/docs/horizon#installation), we need to update some configuration settings in *config/horizon.php*: If needed, change `'use' => 'default'` to the name of the Sentinel connection to use for the Horizon backend as configured in *config/database.php*. **Important:** The standard `'redis'` connections array in *config/database.php*must contain an element with the same key as the Sentinel connection specified for the `'use'` directive or Horizon throws an exception. Currently, Horizon does not provide a way for this package to handle this behavior, but an (in-progress) pull request may eliminate this requirement in the future. This element can contain any value (but a matching Redis connection config seems most appropriate). Change the backend driver for Horizon's internal metadata to `'redis-sentinel'`by adding the following element to the top-level array: ``` 'driver' => env('HORIZON_DRIVER', 'redis'); ``` ...and assign the value of `redis-sentinel` to `HORIZON_DRIVER` in *.env*. Then, add an entry to the `'waits'` array for any Sentinel queues: ``` 'waits' => [ ... 'redis-sentinel:default' => 60, ], ``` Next, change the connection driver to `redis-sentinel` for each of the queue workers that should use Sentinel connections in the `'environments'` block: ``` ... 'supervisor-1' => [ 'connection' => 'redis-sentinel', ... ], ... ``` Horizon will now use the application's Redis Sentinel connections to monitor and process our queues. **Note:** If we already configured the package to [override Laravel's standard Redis API](#override-the-standard-redis-api) (by setting `REDIS_DRIVER` to `redis-sentinel`, for example), we don't need to change `HORIZON_DRIVER` to `'redis-sentinel'`. The package already routes all Redis operations through Sentinel connections. Testing ------- [](#testing) This package includes a PHPUnit test suite with unit tests for the package's classes and an integration test suite for Sentinel-specific functionality and compatibility fixes. These tests do not verify every Redis command because Predis and Laravel both contain full test suites themselves, and because the package code simply wraps these libraries. ``` $ phpunit --testsuite unit $ phpunit --testsuite integration ``` The unit tests do not require live Redis servers. Read the next section for integration testing environment suggestions. **Note:** Composer does not download this package's testing files with a normal installation. We need to clone the package repository directly or install it with the `--prefer-source` option. ### Integration Tests [](#integration-tests) This package's integration test suite validates Sentinel- and Redis-specific functionality against real servers. These tests require at least one Sentinel server that monitors a Redis master. Additionally, at least one replica should synchronize with the master for optimal test coverage. Developers may supply their own servers or start an environment using the package's tools described below. To customize the Sentinel connection settings used by the integration tests, copy *phpunit.xml.dist* to *phpunit.xml* and change the constants defined in the `...` block. We can run the [*start-cluster.sh*](start-cluster.sh) script provided in the project's root directory to spin up Redis and Sentinel servers for a testing environment. Read the script help page for usage information. ``` $ ./start-cluster.sh help ``` Docker users may wish to use the script to start testing servers in a container: ``` $ docker run --name redis-sentinel \ -v "$(pwd):/project" \ -w /project \ -u "$(id -u):$(id -g)" \ -e BIND_ADDRESS=0.0.0.0 \ -e SENTINEL_PORTS='26379-26381' \ -e REDIS_GROUP_1='service1 6379-6381' \ -e REDIS_GROUP_2='service2 6382-6384' \ -e LOGGING=yes \ -p 6379-6384:6379-6384 \ -p 26379-26381:26379-26381 \ --entrypoint start-cluster.sh \ redis:alpine ``` The package provides a [Compose file](docker-compose.yml) with the same options for running tests: ``` $ export CONTAINER_USER_ID="$(id -u):$(id -g)" $ docker-compose up -d cluster $ docker-compose run --rm tests [--testsuite ...] ``` Developers can also customize the Compose file by copying *docker-compose.yml*to *docker-compose.override.yml*. License ------- [](#license) The MIT License (MIT). Please see the [LICENSE File](LICENSE) for more information. --- Appendix: Environment Variables ------------------------------- [](#appendix-environment-variables) The package consumes the following environment variables when using the default [environment-based configuration](#environment-based-configuration). Developers only need to supply values for the variables that apply to their particular application and Redis setup. The default values are sufficient in most cases. ### `REDIS_{HOST,PORT,PASSWORD,DATABASE}` [](#redis_hostportpassworddatabase) The basic connection parameters used by default for all Sentinel connections. To simplify environment configuration, this package attempts to read both the `REDIS_*` and the `REDIS_SENTINEL_*` environment variables that specify values shared by multiple Sentinel connections. If an application does not execute commands through both Redis Sentinel and standard Redis connections [at the same time](#executing-redis-commands-redissentinel-facade), this feature allows developers to use the same environment variale names in development (with a single Redis server) and in production (with a full set of Sentinel servers). - `REDIS_HOST` - One [or more](#specifying-multiple-hosts) hostnames or IP addresses. Defaults to `localhost` when unset. - `REDIS_PORT` - The listening port of the Sentinel servers. Defaults to `26379` for Sentinel connections when unset. - `REDIS_PASSWORD` - The password, if any, used to authenticate with the Redis servers *behind* Sentinel (Sentinels don't support password auth themselves). - `REDIS_DATABASE` - The number of the database to select when issuing commands to the Redis servers behind Sentinel (`0` to `15` in a normal Redis config). Defaults to `0`. ### `REDIS_SENTINEL_{HOST,PORT,PASSWORD,DATABASE}` [](#redis_sentinel_hostportpassworddatabase) Set these variables instead of the above when the application uses both standard Redis and Redis Sentinel connections at the same time. - `REDIS_SENTINEL_HOST` - See `REDIS_HOST`. - `REDIS_SENTINEL_PORT` - See `REDIS_PORT`. - `REDIS_SENTINEL_PASSWORD` - See `REDIS_PASSWORD`. - `REDIS_SENTINEL_DATABASE` - See `REDIS_DATABASE`. ### `REDIS_SENTINEL_SERVICE` [](#redis_sentinel_service) The Redis master group name (as specified in the Sentinel server configuration file) that identifies the default Sentinel service used by all Sentinel connections. Defaults to `mymaster`. Set `REDIS_CACHE_SERVICE`, `REDIS_SESSION_SERVICE`, or `REDIS_QUEUE_SERVICE` to override this value for a service-specific connection. ### `REDIS_SENTINEL_{TIMEOUT,RETRY_LIMIT,RETRY_WAIT,DISCOVERY}` [](#redis_sentinel_timeoutretry_limitretry_waitdiscovery) The Predis client supports some additional configuration options that determine how it handles connections to Sentinel servers. - `REDIS_SENTINEL_TIMEOUT` - The amount of time (in seconds) the client waits before determining that a connection attempt to a Sentinel server failed. Defaults to `0.100`. - `REDIS_SENTINEL_RETRY_LIMIT` - The number of attempts the client tries to contact a Sentinel server before it determines that it cannot reach all Sentinel servers in a quorum. A value of `0` instructs the client to throw an exception after the first failed attempt, while a value of `-1` causes the client to continue to retry connections to Sentinel indefinitely. Defaults to `20`. - `REDIS_SENTINEL_RETRY_WAIT` - The amount of time (in milliseconds) the client waits before attempting to contact another Sentinel server if the previous server did not respond. Defaults to `1000`. - `REDIS_SENTINEL_DISCOVERY` - Instructs the client to query the first reachable Sentinel server for an updated set of Sentinels each time the client needs to establish a connection with a Redis master or slave server. Defaults to `false`. ### `REDIS_DRIVER` [](#redis_driver) Set the value of this variable to `redis-sentinel` to [override Laravel's standard Redis API](#override-the-standard-redis-api). ### `BROADCAST_DRIVER`, `CACHE_DRIVER`, `SESSION_DRIVER`, `QUEUE_CONNECTION` [](#broadcast_driver-cache_driver-session_driver-queue_connection) Laravel uses these to select the backends for the application broadcasting, cache, session, and queue services. Set the value to `redis-sentinel` for each service that the application should use Sentinel connections for. **Note:** Laravel 5.7 renamed `QUEUE_DRIVER` to `QUEUE_CONNECTION` in the default configuration files. ### `REDIS_{BROADCAST,CACHE,SESSION,QUEUE}_{HOST,PORT,PASSWORD,DATABASE,SERVICE}` [](#redis_broadcastcachesessionqueue_hostportpassworddatabaseservice) These variables configure service-specific connection parameters when they differ from the default Sentinel connection parameters for the broadcasting, cache, session, and queue connections. For example: - `REDIS_BROADCAST_HOST` - Overrides `REDIS_HOST` or `REDIS_SENTINEL_HOST` for the default *broadcasting* connection. - `REDIS_CACHE_PORT` - Overrides `REDIS_PORT` or `REDIS_SENTINEL_PORT` for the default *cache* connection. - `REDIS_SESSION_PASSWORD` - Overrides `REDIS_PASSWORD` or `REDIS_SENTINEL_PASSWORD` for the default *session* connection. - `REDIS_QUEUE_DATABASE` - Overrides `REDIS_DATABASE` or `REDIS_SENTINEL_DATABASE` for the default *queue* connection. - `REDIS_QUEUE_SERVICE` - Overrides `REDIS_SENTINEL_SERVICE` for the default *queue* connection. ### `BROADCAST_REDIS_CONNECTION`, `BROADCAST_REDIS_SENTINEL_CONNECTION` [](#broadcast_redis_connection-broadcast_redis_sentinel_connection) The name of the Sentinel connection to select for application broadcasting when `BROADCAST_DRIVER` equals `redis-sentinel`. It defaults to the package's internal, auto-configured *broadcasting* connection when unset. ### `CACHE_REDIS_CONNECTION`, `CACHE_REDIS_SENTINEL_CONNECTION` [](#cache_redis_connection-cache_redis_sentinel_connection) The name of the Sentinel connection to select for the application cache when `CACHE_DRIVER` equals `redis-sentinel`. It defaults to the package's internal, auto-configured *cache* connection when unset. ### `QUEUE_REDIS_CONNECTION`, `QUEUE_REDIS_SENTINEL_CONNECTION` [](#queue_redis_connection-queue_redis_sentinel_connection) The name of the Sentinel connection to select for the application queue when `QUEUE_CONNECTION` (Laravel 5.7+) or `QUEUE_DRIVER` (Laravel <= 5.6) equals `redis-sentinel`. It defaults to the package's internal, auto-configured *queue* connection when unset. ### `SESSION_CONNECTION` [](#session_connection) The name of the Sentinel connection to select for storing application sessions when `SESSION_DRIVER` equals `redis-sentinel`. It defaults to the package's internal, auto-configured *session* connection when unset unless the application configuration already contains a value for `session.connection`. ### `REDIS_SENTINEL_AUTO_BOOT` [](#redis_sentinel_auto_boot) When set to `true`, this flag instructs the package to boot the package after it registers its services without waiting for the application boot phase. This provides a way for applications that use Sentinel connections in other service providers to initialize the package immediately. Appendix: Configuration Examples -------------------------------- [](#appendix-configuration-examples) - [Environment-based Configuration Examples](#environment-based-configuration-examples) - [Development vs. Production](#development-vs-production) - [Configuration File Examples](#configuration-file-examples) - [Multi-Sentinel Configuration](#multi-sentinel-connection-configuration) - [Multi-Service Configuration](#multi-service-connection-configuration) ### Environment-based Configuration Examples [](#environment-based-configuration-examples) Supplemental examples for [environment-based-configuration](#environment-based-configuration). #### Development vs. Production [](#development-vs-production) This example shows how we might change the values of environment variables between environments when we run a single Redis server in development and a full set of Sentinel servers in production. ``` # Development: # Production: CACHE_DRIVER=redis CACHE_DRIVER=redis-sentinel SESSION_DRIVER=redis SESSION_DRIVER=redis-sentinel QUEUE_CONNECTION=redis QUEUE_CONNECTION=redis-sentinel REDIS_HOST=localhost REDIS_HOST=sentinel1, sentinel2, sentinel3 REDIS_PORT=6379 REDIS_PORT=26379 REDIS_SENTINEL_SERVICE=null REDIS_SENTINEL_SERVICE=mymaster ``` Don't forget to run the `artisan config:cache` command in production when possible. This dramatically improves the configuration loading time for the application and this package. [Best practice](https://github.com/vlucas/phpdotenv#usage-notes) suggests that we avoid using the development *.env* file in production environments. Consider other means to set environment variables: > "phpdotenv is made for development environments, and generally should not be used in production. In production, the actual environment variables should be set so that there is no overhead of loading the .env file on each request. This can be achieved via an automated deployment process with tools like Vagrant, chef, or Puppet, or can be set manually with cloud hosts..." ### Configuration File Examples [](#configuration-file-examples) These examples demonstrate how to setup Laravel's standard configuration files to configure the package for more-advanced setups. For an introduction to using configuration files, read the [config file documentation](#using-standard-configuration-files). #### Multi-Sentinel Connection Configuration [](#multi-sentinel-connection-configuration) In a true highly-available Redis setup, we'll run more than one Sentinel server in a quorum. This adds redundancy for a failure event during which one or more Sentinel servers become unresponsive. We can add multiple Sentinel server definitions to our `'default'` connection in *config/database.php*: ``` ... 'redis-sentinel' => [ 'default' => [ [ 'host' => 'sentinel1.example.com', 'port' => 26379, ], [ 'host' => 'sentinel2.example.com', 'port' => 26379, ], [ 'host' => 'sentinel3.example.com' 'port' => 26379, ], ], 'options' => [ 'service' => env('REDIS_SENTINEL_SERVICE', 'mymaster'), 'parameters' => [ 'password' => env('REDIS_PASSWORD', null), 'database' => 0, ], ], ], ``` With this configuration, we declare three Sentinel servers that can handle requests for our Redis service, `mymaster` (the master group name as specified in the Sentinel server configuration file). If one of the Sentinel servers fails, the Predis client will select a different Sentinel server to send requests to. Typically, in a clustered environment, we don't want to hard-code each server into our configuration like above. We may install some form of load balancing or service discovery to route requests to a Sentinel server through an aggregate hostname, such as `sentinels.example.com`, for flexible deployment and arbritrary scaling. #### Multi-service Connection Configuration [](#multi-service-connection-configuration) As we mentioned previously, we likely want to separate the Redis connections Laravel uses for each of our services. For instance, we'd use separate databases on a Redis server for our cache and session storage. In this example, we may also want to create a database on a different set of Redis servers managed by Sentinel for something like a feed. For this setup, we'll configure multiple `'redis-sentinel'` connections: ``` ... 'redis-sentinel' => [ 'cache' => [ [ 'host' => env('REDIS_HOST', 'localhost'), 'port' => env('REDIS_PORT', 26379), ], 'options' => [ 'service' => env('REDIS_SENTINEL_SERVICE', 'mymaster'), 'parameters' => [ 'password' => env('REDIS_PASSWORD', null), 'database' => 0, ], ], ], 'session' => [ [ 'host' => env('REDIS_HOST', 'localhost'), 'port' => env('REDIS_PORT', 26379), ], 'options' => [ 'service' => env('REDIS_SENTINEL_SERVICE', 'mymaster'), 'parameters' => [ 'password' => env('REDIS_PASSWORD', null), 'database' => 1, ], ], ], 'feed' => [ [ 'host' => env('REDIS_HOST', 'localhost'), 'port' => env('REDIS_PORT', 26379), ], 'options' => [ 'service' => env('REDIS_SENTINEL_FEED_SERVICE', 'feed-service'), 'parameters' => [ 'password' => env('REDIS_PASSWORD', null), 'database' => 0, ], ], ], ], ``` Notice that we removed the global `'options'` array and created a local `'options'` array for each connection. In this example setup, we store the application cache and sessions on one Redis server set, and feed data in another set. In the first connection block, we set the Redis database for storing cache data to `0`, and the database for session data to `1`, which allows us to clear our application cache without erasing user sessions. This example setup includes a second set of Redis servers for storing feed data. The example Sentinel servers contain configuration for the first set with the service name, `mymaster`, and for the secord set with the service name, `feed-service`. The local connection options allow us to specify which service (Redis master group name) the connection makes requests for. In particular, we set the service name of the `'feed'` connection to `'feed-service'`. For more information about Sentinel service configuration, see the [Redis Sentinel Documentation](https://redis.io/topics/sentinel). ### Health Score 19 — LowBetter than 10% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity3 Limited adoption so far Community11 Small or concentrated contributor base Maturity38 Early-stage or recently created project Bus Factor1 Top contributor holds 89.5% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~0 days Total 3 Last Release 900d ago Major Versions 2.x-dev → 3.x-dev2023-11-24 ### Community Maintainers ![](https://www.gravatar.com/avatar/36dffe883e88aeef07c26067af3d6a7eda1c2a81f1ae45fdd430b721665131da?d=identicon)[Mobius Studio](/maintainers/Mobius%20Studio) --- Top Contributors [![cyrossignol](https://avatars.githubusercontent.com/u/4282384?v=4)](https://github.com/cyrossignol "cyrossignol (51 commits)")[![jacovdbergh](https://avatars.githubusercontent.com/u/24895833?v=4)](https://github.com/jacovdbergh "jacovdbergh (3 commits)")[![pdbreen](https://avatars.githubusercontent.com/u/1670907?v=4)](https://github.com/pdbreen "pdbreen (1 commits)")[![tolgaCTRLF5](https://avatars.githubusercontent.com/u/33447585?v=4)](https://github.com/tolgaCTRLF5 "tolgaCTRLF5 (1 commits)")[![yupmin-ct](https://avatars.githubusercontent.com/u/15603368?v=4)](https://github.com/yupmin-ct "yupmin-ct (1 commits)") --- Tags laravellumenredissentinel ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/tcgunel-laravel-redis-sentinel-drivers/health.svg) ``` [![Health](https://phpackages.com/badges/tcgunel-laravel-redis-sentinel-drivers/health.svg)](https://phpackages.com/packages/tcgunel-laravel-redis-sentinel-drivers) ``` ### Alternatives [monospice/laravel-redis-sentinel-drivers Redis Sentinel integration for Laravel and Lumen. 103830.5k](/packages/monospice-laravel-redis-sentinel-drivers)[laravel/pulse Laravel Pulse is a real-time application performance monitoring tool and dashboard for your Laravel application. 1.7k12.1M99](/packages/laravel-pulse)[yangusik/laravel-balanced-queue Laravel queue management with load balancing between partitions (user groups) 786.4k](/packages/yangusik-laravel-balanced-queue)[namoshek/laravel-redis-sentinel An extension of Laravels Redis driver which supports connecting to a Redis master through Redis Sentinel. 38679.0k](/packages/namoshek-laravel-redis-sentinel)[encore/redis-manager Redis manager for laravel 25243.1k](/packages/encore-redis-manager)[ginnerpeace/laravel-redis-lock Simple redis distributed locks for Laravel. 15114.4k](/packages/ginnerpeace-laravel-redis-lock) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)