Command Transformations

Purpose and Scope

This document catalogs all specific Redis command transformations implemented in the RedisConnection class. Each transformation adapts a Laravel-style API call into its phpredis/Hyperf-compatible equivalent, handling differences in argument order, option formats, and return value interpretation.

For information about the overall transformation system architecture and the __call routing mechanism, see Transformation System. For scan operations (scan, zscan, hscan, sscan), see Scan Operations. For pub/sub transformations (subscribe, psubscribe), see Pub/Sub Operations.

---

Transformation Categories

Command transformations are organized into logical groups based on Redis data types and operations. The RedisConnection class implements over 20 distinct transformations, each invoked through protected call* methods when the shouldTransform flag is enabled.

Diagram: Command Transformation Routing Architecture

Sources: src/RedisConnection.php267-287 src/RedisConnection.php314-714

---

String Command Transformations

GET Command

Purpose: Transforms false return value to null for non-existent keys.

Laravel API:

Transformation Details:

Aspect	Laravel Style	phpredis Native
Method Signature	get(string $key): ?string	get(string $key): string|false
Non-existent Key	Returns null	Returns false
Existing Key	Returns string value	Returns string value

Implementation:

The transformation at src/RedisConnection.php317-322 performs a simple ternary check:

• Calls $this->connection->get($key) (phpredis native method)
• Returns the result if not false, otherwise returns null

This provides more idiomatic PHP handling by using null instead of false for missing values, consistent with Laravel conventions.

Sources: src/RedisConnection.php317-322

---

MGET Command

Purpose: Transforms false values in the result array to null for non-existent keys.

Laravel API:

Transformation Details:

Aspect	Laravel Style	phpredis Native
Method Signature	mget(array $keys): array	mGet(array $keys): array
Non-existent Keys	Array contains null	Array contains false
Element Order	Matches input key order	Matches input key order

Implementation:

The transformation at src/RedisConnection.php327-332 applies the same false to null conversion as callGet, but uses array_map to process each element in the result array from $this->connection->mGet($keys).

Sources: src/RedisConnection.php327-332

---

SET Command

Purpose: Transforms expiration options from Laravel's flat parameter format to phpredis array format.

Laravel API:

Transformation Details:

Parameter	Laravel Position	phpredis Format	Description
$key	1	1	Key name
$value	2	2	Value to set
$expireResolution	3 (optional)	In options array	'EX' or 'PX'
$expireTTL	4 (optional)	In options array	Expiration time
$flag	5 (optional)	In options array	'NX', 'XX', etc.

Implementation:

The transformation at src/RedisConnection.php337-344 converts Laravel's flat parameter signature into phpredis's options array format. When $expireResolution is provided, it constructs an array: [$flag, $expireResolution => $expireTTL], otherwise passes null as the options parameter.

Sources: src/RedisConnection.php337-344

---

SETNX Command

Purpose: Casts boolean return value to integer for consistency.

Laravel API:

Transformation Details:

Aspect	Laravel Style	phpredis Native
Return Type	int (1 or 0)	bool (true or false)
Success	Returns 1	Returns true
Failure	Returns 0	Returns false

Implementation:

The transformation at src/RedisConnection.php349-352 performs type casting: (int) $this->connection->setNx($key, $value), converting phpredis's boolean return to integer (1 or 0).

Sources: src/RedisConnection.php349-352

---

Hash Command Transformations

HMGET Command

Purpose: Converts variadic arguments to array and returns indexed array instead of associative array.

Laravel API:

Transformation Details:

Aspect	Laravel Style	phpredis Native
Field Arguments	Variadic or array	Array only
Return Type	Indexed array	Associative array
Missing Fields	false in array	false in array

Diagram: HMGET Argument Processing Flow

Implementation:

The transformation at src/RedisConnection.php357-366 handles two cases:

1. Single array argument: Unwraps the array (line 359-361)
2. Variadic arguments: Uses them directly

Then applies array_values() to the result of $this->connection->hMGet() to convert from associative to indexed array.

Sources: src/RedisConnection.php357-366

---

HMSET Command

Purpose: Converts variadic field-value pairs to associative array.

Laravel API:

Transformation Details:

Input Format	Transformation	Example
Associative Array	Pass through	['name' => 'John'] → ['name' => 'John']
Variadic Pairs	Convert to associative	'name', 'John', 'email', 'john@example.com' → ['name' => 'John', 'email' => 'john@example.com']

Implementation:

The transformation at src/RedisConnection.php371-382 handles two input formats:

1. Single array: Pass through (line 373-375)
2. Variadic pairs: Uses Collection::nth(2) to extract even indices (keys) and Collection::nth(2, 1) for odd indices (values), then combines them with combine() (line 376-378)

The Collection class is from Hypervel\Support\Collection (line 9).

Sources: src/RedisConnection.php371-382

---

HSETNX Command

Purpose: Casts boolean return value to integer.

Laravel API:

Transformation Details:

Aspect	Laravel Style	phpredis Native
Return Type	int (1 or 0)	bool (true or false)

Implementation:

The transformation at src/RedisConnection.php387-390 performs type casting: (int) $this->connection->hSetNx($hash, $key, $value).

Sources: src/RedisConnection.php387-390

---

List Command Transformations

LREM Command

Purpose: Swaps argument order to match Laravel's convention (count before value).

Laravel API:

Transformation Details:

Position	Laravel Style	phpredis Native
1	Key	Key
2	Count	Value
3	Value	Count

Comparison:

• Laravel: lrem($key, $count, $value)
• phpredis: lRem($key, $value, $count)

Implementation:

The transformation at src/RedisConnection.php395-398 swaps argument positions: $this->connection->lRem($key, $value, $count) where Laravel's ($key, $count, $value) becomes phpredis's ($key, $value, $count).

Sources: src/RedisConnection.php395-398

---

BLPOP Command

Purpose: Transforms empty result array to null.

Laravel API:

Transformation Details:

Aspect	Laravel Style	phpredis Native
Timeout Result	Returns null	Returns empty array []
Success Result	Returns [key, value]	Returns [key, value]

Implementation:

The transformation at src/RedisConnection.php403-408 converts empty array results to null: empty($result) ? null : $result.

Sources: src/RedisConnection.php403-408

---

BRPOP Command

Purpose: Identical transformation to BLPOP - converts empty array to null.

Implementation:

The transformation at src/RedisConnection.php413-418 is identical to callBlpop: converts empty array to null.

Sources: src/RedisConnection.php413-418

---

Set Command Transformations

SPOP Command

Purpose: Ensures count parameter is properly passed through.

Laravel API:

Implementation:

The transformation at src/RedisConnection.php425-428 normalizes the count parameter with a default value of 1, then delegates to $this->connection->sPop($key, $count).

Sources: src/RedisConnection.php425-428

---

Sorted Set Command Transformations

ZADD Command

Purpose: Parses Laravel-style options and arguments into phpredis format.

Laravel API:

Diagram: ZADD Argument Processing Flow

Supported Options:

• NX / nx - Only add new elements
• XX / xx - Only update existing elements
• CH / ch - Return number of changed elements
• INCR / incr - Increment score
• GT / gt - Only update if new score is greater
• LT / lt - Only update if new score is less

Implementation:

The transformation at src/RedisConnection.php433-457 performs complex argument processing:

1. Array Unpacking (line 435-440): If last argument is an array, unpacks member => score pairs into flat list
2. Option Extraction (line 444-450): Scans first 3 arguments for option flags (NX, XX, CH, INCR, GT, LT - case insensitive)
3. Final Call (line 452-456): Calls $this->connection->zAdd($key, $options, ...array_values($dictionary))

Option flags are detected using in_array() with strict comparison (line 445).

Sources: src/RedisConnection.php433-457

---

ZRANGEBYSCORE Command

Purpose: Transforms Laravel-style limit options to phpredis array format.

Laravel API:

Transformation Details:

Option Format	Laravel Style	phpredis Style
Limit (associative)	['offset' => 10, 'count' => 5]	[10, 5]
Limit (indexed)	[10, 5]	[10, 5]

Implementation:

The transformation at src/RedisConnection.php462-472 converts associative limit format to indexed array:

• Checks if $options['limit'] exists and is not a list (line 464)
• Converts ['offset' => X, 'count' => Y] to [X, Y] (line 465-468)
• Delegates to $this->connection->zRangeByScore($key, $min, $max, $options) (line 471)

Sources: src/RedisConnection.php462-472

---

ZREVRANGEBYSCORE Command

Purpose: Identical transformation to ZRANGEBYSCORE but for reverse order.

Implementation:

The transformation at src/RedisConnection.php477-487 is identical to callZrangebyscore but calls $this->connection->zRevRangeByScore() instead.

Sources: src/RedisConnection.php477-487

---

ZINTERSTORE Command

Purpose: Extracts weights and aggregate options from Laravel-style options array.

Laravel API:

Transformation Details:

Option	Laravel Format	phpredis Format	Default
weights	['weights' => [2, 3]]	Parameter 3	null
aggregate	['aggregate' => 'max']	Parameter 4	'sum'

Implementation:

The transformation at src/RedisConnection.php492-500 extracts options and passes them as separate parameters to $this->connection->zinterstore():

• Parameter 3: $options['weights'] ?? null
• Parameter 4: $options['aggregate'] ?? 'sum' (defaults to 'sum')

Sources: src/RedisConnection.php492-500

---

ZUNIONSTORE Command

Purpose: Identical transformation to ZINTERSTORE but for union operation.

Implementation:

The transformation at src/RedisConnection.php505-513 is identical to callZinterstore but calls $this->connection->zunionstore() instead.

Sources: src/RedisConnection.php505-513

---

Script Command Transformations

EVAL Command

Purpose: Reorders arguments to match phpredis signature.

Laravel API:

Transformation Details:

Position	Laravel Style	phpredis Style
1	Script string	Script string
2	Number of keys	Arguments array
3+	Keys and arguments	Number of keys

Comparison:

• Laravel: eval($script, $numKeys, ...$keysAndArgs)
• phpredis: eval($script, $argsArray, $numKeys)

Implementation:

The transformation at src/RedisConnection.php642-645 reorders parameters for phpredis: eval($script, $arguments, $numberOfKeys) where Laravel passes ($script, $numberOfKeys, ...$arguments).

Sources: src/RedisConnection.php642-645

---

EVALSHA Command

Purpose: Automatically loads script and evaluates by SHA1 hash.

Laravel API:

Transformation Details:

This transformation performs two operations:

1. Loads the script to get its SHA1 hash
2. Executes using the SHA1 hash

Implementation:

The transformation at src/RedisConnection.php650-657 performs two operations:

1. Loads script via $this->connection->script('load', $script) to get SHA1 hash (line 653)
2. Executes using evalSha() with the hash, arguments array, and key count (line 652-656)

Sources: src/RedisConnection.php650-657

---

Database Command Transformations

FLUSHDB Command

Purpose: Converts Laravel's ASYNC string flag to phpredis boolean parameter.

Laravel API:

Transformation Details:

Argument	Laravel Style	phpredis Style
Sync	No argument or any non-'ASYNC'	false or no argument
Async	'ASYNC' string	true

Implementation:

The transformation at src/RedisConnection.php662-669 converts string flag to boolean:

• Checks if first argument is 'ASYNC' (case-insensitive via strtoupper()) (line 664)
• If yes, calls $this->connection->flushdb(true) (line 665)
• Otherwise calls $this->connection->flushdb() with no argument (line 668)

Sources: src/RedisConnection.php662-669

---

Raw Command Transformations

EXECUTERAW Command

Purpose: Spreads parameter array into variadic arguments for rawCommand.

Laravel API:

Transformation Details:

Input Format	Output Format
Array of command parts	Variadic arguments
['SET', 'key', 'value']	rawCommand('SET', 'key', 'value')

Implementation:

The transformation at src/RedisConnection.php674-677 spreads the parameter array: $this->connection->rawCommand(...$parameters), allowing execution of arbitrary Redis commands.

Sources: src/RedisConnection.php674-677

---

Transformation Routing

The __call magic method in RedisConnection orchestrates all transformations through a consistent routing mechanism.

Diagram: __call Method Routing Logic

Key Routing Logic:

1. Pub/Sub Priority: Subscribe commands always route to callSubscribe regardless of shouldTransform flag
2. Transform Check: If shouldTransform is true, check for corresponding call* method
3. Method Existence: Only invoke transformation if call{Method} exists
4. Fallback: If no transformation exists, call native phpredis method directly

Implementation Reference:

The routing logic is implemented in src/RedisConnection.php267-287 The method performs these steps:

1. Pub/Sub Check: Priority routing for subscribe/psubscribe commands (line 270-272)
2. Transform Check: If shouldTransform is enabled, attempt transformation (line 274)
3. Method Construction: Build method name as 'call' . ucfirst($name) (line 275)
4. Method Existence: Check if transformation method exists (line 276)
5. Invocation: Call transformation or fallback to native phpredis (line 277-281)
6. Error Handling: Retry logic wraps all operations (line 282-284)

Sources: src/RedisConnection.php267-287

---

Complete Transformation Reference

The following table provides a comprehensive reference of all command transformations implemented in RedisConnection.

Command	Method	Primary Transformation	Return Transformation
get	callGet	None	false → null
mget	callMget	None	Array elements: false → null
set	callSet	Flat args → options array	None
setnx	callSetnx	None	bool → int
hmget	callHmget	Variadic → array	Associative → indexed
hmset	callHmset	Variadic pairs → assoc array	None
hsetnx	callHsetnx	None	bool → int
lrem	callLrem	Swap count and value args	None
blpop	callBlpop	None	Empty array → null
brpop	callBrpop	None	Empty array → null
spop	callSpop	Set default count = 1	None
zadd	callZadd	Extract options, unpack arrays	None
zrangebyscore	callZrangebyscore	Convert limit to indexed array	None
zrevrangebyscore	callZrevrangebyscore	Convert limit to indexed array	None
zinterstore	callZinterstore	Extract weights and aggregate	None
zunionstore	callZunionstore	Extract weights and aggregate	None
eval	callEval	Reorder args and numkeys	None
evalsha	callEvalsha	Load script, reorder args	None
flushdb	callFlushdb	'ASYNC' → true	None
executeRaw	callExecuteRaw	Array → variadic	None

Sources: src/RedisConnection.php314-677

---

Usage Examples

String Operations

Hash Operations

List Operations

Sorted Set Operations

Script Operations

Sources: src/RedisConnection.php314-677