Redis Client

Purpose and Scope

The Redis class is the primary entry point for executing Redis commands in the Hypervel Redis package. It serves as an orchestrator that manages connection lifecycle, executes commands through a magic method proxy pattern, integrates with Hyperf's coroutine context for stateful operations, and dispatches observability events.

This page documents the core Redis client class and its responsibilities. For specific topics:

• Basic command execution patterns: see Basic Operations
• Coroutine context connection management: see Context Management
• Event system and observability: see Event System
• Transformation layer implementation: see RedisConnection
• Multi-pool configuration: see Redis Factory

Sources: src/Redis.php1-142

---

Class Structure

The Redis class uses dependency injection and the magic method pattern to provide a flexible Redis client interface.

Constructor and Dependencies

Diagram: Redis Client Dependencies

Component	Purpose	Source
Redis	Main client class with command proxy logic	src/Redis.php17-24
PoolFactory	Hyperf's factory for obtaining connection pools	src/Redis.php22
RedisConnection	Transformation layer that executes commands	src/Redis.php36-38
Context	Coroutine-aware storage for connection reuse	src/Redis.php28-29
ApplicationContext	Service container accessor	src/Redis.php138-140

Sources: src/Redis.php17-24

Key Properties and Methods

Member	Type	Purpose
$poolName	string	Name of the connection pool (default: 'default')
$factory	PoolFactory	Factory for obtaining connection pools
__call()	Method	Magic method that intercepts all Redis commands
connection()	Method	Returns a named RedisProxy instance
getConnection()	Method	Obtains connection from context or pool
shouldUseSameConnection()	Method	Determines if command requires context storage
releaseContextConnection()	Method	Releases connection stored in context
getContextKey()	Method	Generates coroutine context storage key

Sources: src/Redis.php19 src/Redis.php26-77 src/Redis.php82-91 src/Redis.php97-104 src/Redis.php109-123 src/Redis.php128-131 src/Redis.php136-141

---

Command Execution Flow

All Redis commands are executed through the __call() magic method, which implements a comprehensive execution pipeline.

Diagram: Command Execution Pipeline

Execution Phases

The __call() method implements a five-phase execution pipeline:

1. Context Check src/Redis.php28: Determines if a connection already exists in the coroutine context
2. Connection Acquisition src/Redis.php29: Obtains connection from context or pool via getConnection()
3. Command Execution src/Redis.php36-38: Invokes the command on RedisConnection with timing
4. Event Dispatch src/Redis.php43-53: Dispatches CommandExecuted event with metrics
5. Connection Lifecycle src/Redis.php55-69: Decides whether to store, defer, or release connection

Sources: src/Redis.php26-77

---

Connection Management

The Redis client implements intelligent connection management that optimizes for both stateless and stateful operations.

Diagram: Connection Lifecycle Decision Tree

Context Key Generation

Each connection pool uses a unique context key to store connections in coroutine context:

redis.connection.{poolName}

For example:

• Default pool: redis.connection.default
• Cache pool: redis.connection.cache
• Session pool: redis.connection.session

This ensures connections are isolated by pool within the same coroutine.

Sources: src/Redis.php128-131

Connection Acquisition Logic

The getConnection() method implements a two-tier acquisition strategy:

Diagram: Connection Acquisition Strategy

Sources: src/Redis.php109-123

---

Special Command Handling

Certain Redis commands require maintaining the same connection across multiple operations. The Redis client identifies these commands and automatically stores the connection in coroutine context.

Commands Requiring Same Connection

Command	Reason	Behavior
multi	Transaction block start	Connection stored until exec() or discard()
pipeline	Batched command execution	Connection stored until exec()
select	Database selection	Connection stored and database ID tracked

Sources: src/Redis.php99-103

Select Command Handling

The select command receives special treatment to track the active database:

Diagram: Select Command Flow

When select is executed:

1. The database argument is extracted src/Redis.php59
2. RedisConnection::setDatabase() is called to track the active DB src/Redis.php60
3. Connection is stored in context for subsequent commands src/Redis.php62
4. Cleanup is deferred to end of coroutine src/Redis.php63-65

Sources: src/Redis.php57-65

Deferred Connection Release

For special commands, connection release is deferred using Hyperf's defer() function:

This ensures:

• Connection remains available throughout the coroutine's execution
• Automatic cleanup when coroutine completes
• No manual connection management required by application code

The releaseContextConnection() method retrieves the connection from context, removes it, and calls release():

Sources: src/Redis.php63-65 src/Redis.php82-91

---

Event Dispatching

Every Redis command execution triggers a CommandExecuted event, providing comprehensive observability.

Event Properties

The CommandExecuted event includes:

Property	Type	Purpose
$name	string	Command name (e.g., 'set', 'get', 'multi')
$arguments	array	Command arguments
$time	float	Execution time in milliseconds
$connection	RedisConnection	Connection object used
$poolName	string	Name of the connection pool
$result	mixed	Command return value
$exception	?Throwable	Exception if command failed

Sources: src/Redis.php44-52

Event Timing

Execution timing is measured with microsecond precision:

Diagram: Timing Measurement

The timing calculation src/Redis.php31 src/Redis.php42 converts microseconds to milliseconds and rounds to 2 decimal places, providing human-readable metrics suitable for logging and monitoring.

Sources: src/Redis.php31 src/Redis.php42-53

---

Named Connection Access

The connection() method provides access to named Redis connections configured in the application.

Method Signature

This method:

1. Retrieves the RedisFactory from the container src/Redis.php138-140
2. Calls RedisFactory::get($name) to obtain a RedisProxy
3. Returns the proxy bound to the specified pool

Usage Pattern

For details on how RedisFactory manages these named connections, see Redis Factory.

For the RedisProxy class that extends Redis with pool-specific configuration, see Redis Proxy.

Sources: src/Redis.php136-141

---

Class Mixin Documentation

The @mixin annotation indicates that the Redis class proxies all methods from RedisConnection:

This provides IDE autocomplete and static analysis support for all Redis commands available through the transformation layer. See RedisConnection for the complete method catalog.

Sources: src/Redis.php15-16