Transformation System

Purpose and Scope

The transformation system is the core mechanism within RedisConnection that enables dual-mode operation: commands can be executed with Laravel-compatible transformations or passed directly to the underlying Hyperf Redis client. This system consists of a control flag, a method routing mechanism, and specialized transformation methods that adapt API conventions between the two frameworks.

For details on specific command transformations (e.g., how get, set, zadd are transformed), see Command Transformations. For scan operation handling, see Scan Operations. For pub/sub operations, see Pub/Sub Operations.

---

Dual-Mode Architecture

The RedisConnection class operates in two distinct modes controlled by the shouldTransform boolean flag:

Mode	shouldTransform Value	Behavior	Use Case
Laravel-Compatible Mode	true	Commands are routed through transformation methods	Application code expecting Laravel Redis API
Native Hyperf Mode	false	Commands pass directly to underlying connection	Code that uses Hyperf conventions or needs raw access

The mode can be toggled at runtime using the shouldTransform() method, allowing flexible adaptation to different code contexts within the same application.

Sources: src/RedisConnection.php265 src/RedisConnection.php299-304 src/RedisConnection.php309-312 src/RedisConnection.php289-294

---

Magic Method Routing

The transformation system is implemented through the __call magic method, which intercepts all method calls not explicitly defined in the RedisConnection class. This method acts as a dispatcher that routes commands based on the current transformation mode.

Routing Flow Diagram

Sources: src/RedisConnection.php267-287

Routing Algorithm

The __call method implements a three-stage routing algorithm:

1. Subscribe Command Detection: If the method name is subscribe or psubscribe, route to callSubscribe() regardless of transformation mode. These commands require special timeout handling.

2. Transformation Mode Check: If shouldTransform is true, check for a transformation method using the naming convention call{MethodName} (e.g., get → callGet).

3. Fallback: If no transformation method exists or transformation is disabled, pass the call directly to the underlying Hyperf connection object.

Sources: src/RedisConnection.php270-281

---

Transformation Method Convention

Transformation methods follow a strict naming convention and are defined as protected methods within the RedisConnection class:

Original Method	Transformation Method	Purpose
get	callGet	Transform false → null
mget	callMget	Transform false values → null
set	callSet	Restructure expiry arguments
hmget	callHmget	Return array_values instead of assoc
hmset	callHmset	Parse variadic args to array
zadd	callZadd	Parse options and score/member pairs
eval	callEval	Reorder arguments
evalsha	callEvalsha	Load script and execute
flushdb	callFlushdb	Parse ASYNC flag
executeRaw	callExecuteRaw	Map to rawCommand

Each transformation method signature matches the Laravel Redis API, but internally calls the Hyperf Redis API with appropriately transformed arguments.

Sources: src/RedisConnection.php317-677

---

Mode Control Methods

Three methods control the transformation mode:

shouldTransform()

Enables or disables transformation mode. Returns $this for method chaining.

public function shouldTransform(bool $shouldTransform = true): static

Usage Pattern:

$connection->shouldTransform(true)->get('key'); // Laravel mode
$connection->shouldTransform(false)->get('key'); // Hyperf mode

Sources: src/RedisConnection.php299-304

getShouldTransform()

Returns the current transformation state. Used for conditional logic or debugging.

public function getShouldTransform(): bool

Sources: src/RedisConnection.php309-312

release()

Resets the transformation flag to false before returning the connection to the pool. This ensures connections start in a clean state when reused.

public function release(): void
{
 $this->shouldTransform = false;
 parent::release();
}

This automatic reset prevents state leakage between different uses of the same connection instance from the pool.

Sources: src/RedisConnection.php289-294

---

Error Handling and Retry Logic

The __call method wraps all command execution in a try-catch block that delegates exception handling to a retry() method inherited from the parent class. This provides connection recovery and automatic retry capabilities:

The retry mechanism is transparent to the caller and handles transient connection failures without requiring application-level error handling.

Sources: src/RedisConnection.php282-286

---

Integration with Connection Lifecycle

The transformation system integrates with the connection pool lifecycle through the release() method. When a connection is returned to the pool, the transformation flag is automatically reset:

This lifecycle ensures that each acquisition of a connection from the pool starts with a predictable state (shouldTransform = false), and callers must explicitly enable transformation mode if needed.

Sources: src/RedisConnection.php289-294

---

Code Entity Reference

Key Classes and Methods

Entity	Type	Location	Purpose
RedisConnection	Class	src/RedisConnection.php260	Main transformation layer class
shouldTransform	Property	src/RedisConnection.php265	Transformation mode flag
__call	Method	src/RedisConnection.php267-287	Magic method routing dispatcher
shouldTransform()	Method	src/RedisConnection.php299-304	Mode setter
getShouldTransform()	Method	src/RedisConnection.php309-312	Mode getter
release()	Method	src/RedisConnection.php289-294	Connection cleanup
callSubscribe()	Method	src/RedisConnection.php679-695	Special subscribe handler
HyperfRedisConnection	Parent Class	src/RedisConnection.php7-260	Base connection class

Sources: src/RedisConnection.php1-714