Architecture Overview

This document explains the high-level architecture of the Hypervel Redis package, showing how the transformation layer, connection management, and factory pattern work together to provide Laravel-compatible Redis operations on top of Hyperf's infrastructure. It covers the system layers, core components, and key architectural patterns.

For detailed documentation of specific components, see Redis Client, RedisConnection, and Connection Management. For configuration and setup, see Configuration.

Purpose and Scope

The Hypervel Redis package bridges the gap between Laravel's Redis API conventions and Hyperf's Redis client implementation. The architecture consists of three primary layers: the application-facing facade layer, the transformation layer that adapts method signatures and return values, and the underlying Hyperf connection pooling infrastructure. This document focuses on how these layers interact and the design patterns that enable Laravel compatibility while maintaining Hyperf's performance characteristics.

System Layers

The package is organized into three distinct architectural layers, each with specific responsibilities:

Sources: src/Redis.php1-143 src/RedisConnection.php1-715 src/RedisFactory.php1-38 src/RedisPool.php1-17

Application Layer

The application layer interacts with the package through two primary entry points:

• The Redis class (src/Redis.php17-143) serves as the default client for simple use cases
• The RedisFactory class (src/RedisFactory.php12-37) provides access to named connection pools

Hypervel Layer

This layer contains the package's core functionality:

Component	File	Responsibility
Redis	src/Redis.php	Command execution facade, context management, event dispatching
RedisFactory	src/RedisFactory.php	Multi-pool proxy registry and creation
RedisProxy	Referenced in factory	Pool-specific Redis client instances
RedisConnection	src/RedisConnection.php	Laravel transformation layer (highest importance)
RedisPool	src/RedisPool.php	Custom pool that creates RedisConnection instances

Framework and Infrastructure Layers

The package builds on Hyperf's Redis infrastructure (src/RedisConnection.php7) and pool management system (src/RedisPool.php8), integrating with the coroutine context (src/Redis.php11) and event system (src/Redis.php7).

Sources: src/Redis.php1-143 src/RedisConnection.php1-715 src/RedisFactory.php1-38 src/RedisPool.php1-17

Core Components

The package consists of five primary components that work together to provide Laravel-compatible Redis operations:

Sources: src/Redis.php17-143 src/RedisFactory.php12-37 src/RedisPool.php10-16 src/RedisConnection.php260-287

Component Responsibilities

Redis Client

The Redis class (src/Redis.php17-143) acts as the primary command execution facade:

• Implements __call() magic method to intercept all Redis commands (src/Redis.php26-77)
• Manages connection lifecycle using coroutine context (src/Redis.php28-29 src/Redis.php82-91)
• Dispatches CommandExecuted events for observability (src/Redis.php43-53)
• Determines when connections should be reused via shouldUseSameConnection() (src/Redis.php97-104)

For detailed client documentation, see Redis Client.

RedisConnection

The RedisConnection class (src/RedisConnection.php260-714) is the most critical component:

• Extends HyperfRedisConnection (src/RedisConnection.php260)
• Contains shouldTransform flag that controls transformation mode (src/RedisConnection.php265)
• Implements __call() to route commands through transformation methods (src/RedisConnection.php267-287)
• Provides Laravel-compatible method implementations like callGet(), callSet(), callHmget(), etc.

For comprehensive transformation documentation, see RedisConnection.

RedisFactory and RedisProxy

The factory pattern enables multi-pool support:

• RedisFactory reads configuration and creates RedisProxy instances (src/RedisFactory.php19-26)
• Each RedisProxy extends Redis with a specific pool name
• Application code retrieves named connections via factory->get('poolName') (src/RedisFactory.php28-36)

For multi-pool configuration, see Connection Management.

RedisPool

The RedisPool class (src/RedisPool.php10-16) customizes Hyperf's pool implementation:

• Extends HyperfRedisPool (src/RedisPool.php10)
• Overrides createConnection() to instantiate RedisConnection instead of base Hyperf connection (src/RedisPool.php12-15)

Sources: src/Redis.php17-143 src/RedisConnection.php260-714 src/RedisFactory.php12-37 src/RedisPool.php10-17

Transformation Architecture

The transformation system is the core value proposition of this package. It enables Laravel developers to use familiar Redis APIs while running on Hyperf infrastructure:

Sources: src/RedisConnection.php267-287

Dual-Mode Operation

The RedisConnection class supports two operational modes controlled by the shouldTransform property (src/RedisConnection.php265):

1. Transform Mode (enabled): Laravel-compatible behavior with custom method implementations
2. Native Mode (disabled): Direct pass-through to Hyperf Redis client

The mode is set via the shouldTransform() method (src/RedisConnection.php299-304) and automatically enabled by the Redis facade (src/Redis.php122).

Transformation Method Routing

The __call() magic method (src/RedisConnection.php267-287) implements transformation routing:

1. Special handling for subscribe and psubscribe commands (src/RedisConnection.php270-272)
2. Check if shouldTransform flag is enabled (src/RedisConnection.php274)
3. Construct method name call{CommandName} using ucfirst() (src/RedisConnection.php275)
4. Call transformation method if it exists (src/RedisConnection.php276-278)
5. Fall back to native Hyperf client call (src/RedisConnection.php281)

Key Transformations

The most important transformations bridge specific API differences:

Laravel Method	Transformation Method	Key Difference
get()	callGet() line 317	Returns null instead of false for missing keys
mget()	callMget() line 327	Maps false values to null in arrays
set()	callSet() line 337	Restructures expiry arguments
hmget()	callHmget() line 357	Returns array_values() instead of associative array
hmset()	callHmset() line 371	Flattens field-value pairs
zadd()	callZadd() line 433	Parses options array format
scan()	scan() line 531	Returns [cursor, results] array

For detailed transformation documentation, see Command Transformations.

Sources: src/RedisConnection.php267-714

Connection Lifecycle

The connection lifecycle demonstrates how the package manages Redis connections efficiently while supporting stateful operations:

Sources: src/Redis.php26-77 src/Redis.php109-123 src/Redis.php82-91

Connection Acquisition

The getConnection() method (src/Redis.php109-123) implements a two-tier acquisition strategy:

1. Check coroutine context for existing connection (src/Redis.php111-113)
2. If not found, acquire new connection from pool (src/Redis.php115-116)
3. Enable transformation mode on the connection (src/Redis.php122)

Context Storage

Connections are stored in coroutine context using a pool-specific key (src/Redis.php128-131):

redis.connection.{poolName}

This enables multiple named pools to maintain separate connections within the same coroutine.

Connection Release Strategy

The release logic (src/Redis.php55-69) implements three strategies:

1. Already in Context: No release (src/Redis.php55-56)
2. Stateful Commands: Store in context with deferred cleanup (src/Redis.php57-65)
3. Normal Commands: Immediate release (src/Redis.php67-68)

Stateful commands requiring same-connection behavior include:

• multi - Transaction mode
• pipeline - Pipeline mode
• select - Database selection

These are defined in shouldUseSameConnection() (src/Redis.php97-104).

Deferred Cleanup

For stateful commands, connection release is deferred using Hyperf's defer() function (src/Redis.php63-65), which executes at coroutine completion. The cleanup is handled by releaseContextConnection() (src/Redis.php82-91).

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

Multi-Pool Architecture

The multi-pool system enables applications to maintain separate Redis connections for different purposes (default, cache, session, etc.):

Sources: src/RedisFactory.php12-37 src/Redis.php17-143

Factory Initialization

The RedisFactory constructor (src/RedisFactory.php19-26) reads Redis configuration and creates a RedisProxy instance for each configured pool:

This populates the proxies array (src/RedisFactory.php17) with named proxy instances.

Pool-Specific Clients

Each RedisProxy instance:

• Extends the base Redis client class
• Has a specific poolName property set during construction
• Uses that pool name for all connection operations (src/Redis.php19 src/Redis.php116)

Accessing Named Pools

Applications can access named pools in two ways:

1. Via Factory: Direct factory access

   (src/RedisFactory.php28-36)

2. Via Redis Client: Using the connection() method

   (src/Redis.php136-141)

Pool Isolation

Each pool maintains:

• Separate connection configurations
• Independent connection pools via PoolFactory->getPool($poolName) (src/Redis.php116)
• Isolated coroutine context keys (src/Redis.php128-131)
• Dedicated Redis servers or databases

For configuration details, see Multi-Pool Configuration.

Sources: src/RedisFactory.php12-37 src/Redis.php17-143 src/Redis.php128-131

Event System Integration

The package integrates with Hyperf's event system to provide observability:

The CommandExecuted event (src/Redis.php7 src/Redis.php44-52) contains:

• Command name
• Command arguments
• Execution time in milliseconds
• Connection instance
• Pool name
• Result (if successful)
• Exception (if failed)

Events are dispatched regardless of command success or failure (src/Redis.php43-53), enabling comprehensive observability.

For event system usage, see Event System.

Sources: src/Redis.php7 src/Redis.php26-77

Summary

The Hypervel Redis architecture achieves Laravel compatibility through three key design patterns:

1. Transformation Layer: The RedisConnection class with dual-mode operation controlled by shouldTransform flag
2. Context-Aware Connection Management: Coroutine context storage enabling stateful operations like transactions and database selection
3. Factory Pattern: Multi-pool support via RedisFactory and pool-specific RedisProxy instances

The package builds on Hyperf's connection pooling infrastructure while providing a Laravel-compatible API surface, allowing developers to migrate applications from Laravel to Hyperf with minimal Redis code changes.

Sources: src/Redis.php1-143 src/RedisConnection.php1-715 src/RedisFactory.php1-38 src/RedisPool.php1-17