Configuration

This document explains how to configure the hypervel/redis package within Hyperf applications. It covers the structure of configuration files, available connection options, and how to set up single or multiple Redis connection pools.

For information about how the package integrates with Hyperf's dependency injection system, see Hyperf Integration. For detailed examples of multi-pool setups, see Multi-Pool Configuration.

Configuration File Location

The package uses Hyperf's standard configuration system. Redis configuration should be placed in a file at config/autoload/redis.php in your Hyperf application. This file should return an array where each key represents a named connection pool.

Sources: src/RedisFactory.php19-26

Configuration Structure

The configuration is organized as a nested array structure where top-level keys are pool names and values are pool configuration arrays:

Sources: src/RedisFactory.php21-25

Configuration Loading Flow

The following diagram shows how configuration flows from the config file through the system during application bootstrap:

Configuration Loading and Pool Initialization

Sources: src/RedisFactory.php19-26

Connection Configuration Options

Each pool configuration supports the following connection parameters:

Option	Type	Description	Default
host	string	Redis server hostname	'localhost'
port	int	Redis server port	6379
auth	string|null	Redis authentication password	null
db	int	Redis database number (0-15)	0
timeout	float	Connection timeout in seconds	0.0
reserved	mixed	Reserved parameter for Redis extension	null
retry_interval	int	Retry interval in milliseconds	0
read_timeout	float	Read timeout in seconds	0.0
cluster	array|null	Cluster configuration options	null
sentinel	array|null	Sentinel configuration options	null

Sources: Hyperf Redis documentation (standard connection options)

Pool Configuration Options

Each pool also supports a nested pool configuration array with connection pool management options:

Option	Type	Description	Default
min_connections	int	Minimum number of connections to maintain	1
max_connections	int	Maximum number of connections allowed	10
connect_timeout	float	Timeout when establishing new connection (seconds)	10.0
wait_timeout	float	Timeout when waiting for available connection (seconds)	3.0
heartbeat	int	Heartbeat interval in seconds (-1 to disable)	-1
max_idle_time	float	Maximum idle time before connection is closed (seconds)	60.0

Sources: Hyperf Pool documentation (standard pool options)

Single Pool Configuration Example

The simplest configuration defines a single default pool:

This configuration creates a single connection pool named default that can be accessed via the Redis facade without additional setup.

Sources: src/Redis.php19 src/RedisFactory.php21-25

Multiple Pool Configuration Example

Applications often need multiple Redis pools for different purposes. Here's a configuration with three pools:

Sources: src/Redis.php136-141 src/RedisFactory.php19-26

Accessing Named Pools

Once configured, named pools can be accessed using the connection() method on the Redis facade:

The connection() method retrieves a RedisProxy instance from the RedisFactory that is bound to the specified pool name.

Sources: src/Redis.php136-141

Configuration Resolution Diagram

The following diagram maps configuration keys to code entities that use them:

Configuration to Code Entity Mapping

Sources: src/RedisFactory.php19-26 src/Redis.php19 src/Redis.php128-131 src/Redis.php109-123

Configuration Validation

The RedisFactory validates that each configured pool name can be used to create a valid RedisProxy instance. If a pool name is requested that was not configured, an InvalidRedisProxyException is thrown:

This ensures that all pool references in application code correspond to actual configured pools.

Sources: src/RedisFactory.php28-36

Pool Name Usage in Context

Pool names are critical for context management because they are used to namespace coroutine-local connections. The context key format is redis.connection.{poolName}:

This means that stateful operations (like multi(), pipeline(), or select()) on different pools maintain separate connections in the coroutine context, preventing interference between pools.

Sources: src/Redis.php128-131 src/Redis.php97-104

Configuration Best Practices

Pool Sizing

The max_connections setting should be tuned based on:

• Expected concurrent coroutines accessing Redis
• Redis server's maxclients setting
• Available system resources

For high-concurrency applications, set max_connections to a value that can handle peak load:

Separate Pools for Different Use Cases

Use multiple pools to isolate different types of Redis operations:

Pool Name	Purpose	Recommended Settings
default	General application data	High max_connections
cache	Temporary cached data	Medium max_connections, low db number
session	User session storage	Low max_connections, dedicated db
queue	Job queue management	High max_connections, high wait_timeout

This isolation prevents one subsystem from exhausting connections needed by others.

Sources: src/RedisFactory.php19-26

Default Pool Name

The Redis class uses 'default' as its default pool name if none is specified:

This means that direct usage of the Redis facade (without calling connection()) always uses the default pool, so this pool must be configured for basic operations to work.

Sources: src/Redis.php19