Scan Operations

This document covers the specialized handling of scan operations in the RedisConnection transformation layer. Redis provides four scan commands (SCAN, ZSCAN, HSCAN, SSCAN) that iterate over collections using cursor-based pagination. These operations require custom transformation logic to adapt their cursor-by-reference pattern and return value format to Laravel conventions.

For general command transformations, see Command Transformations. For the overall transformation system architecture, see Transformation System.

---

Overview

Scan operations differ from other Redis commands in three critical ways:

1. Cursor-by-reference pattern: The cursor parameter is passed by reference and modified during execution
2. Dual return values: Results include both the updated cursor and the collection of items
3. Special completion semantics: A cursor value of 0 indicates iteration completion

The RedisConnection class provides custom implementations for all four scan operations to bridge the API differences between Hyperf Redis (which follows PHP Redis extension conventions) and Laravel Redis (which uses a simplified interface).

Sources: src/RedisConnection.php515-637

---

Scan Operation Types

The transformation layer implements four scan operations, each targeting a different Redis data structure:

Method	Purpose	Scans
scan()	Scan database keys	All keys in current database
zscan()	Scan sorted set members	Members and scores in a sorted set
hscan()	Scan hash fields	Field-value pairs in a hash
sscan()	Scan set members	Members in a set

All four methods share a common implementation pattern:

• Accept a cursor by reference
• Parse options using getScanOptions()
• Execute the underlying Redis scan command
• Format and return results based on shouldTransform flag

Sources: src/RedisConnection.php531-637

---

Cursor Management

Redis scan operations use a cursor-based iteration model where the cursor is passed by reference and updated after each call. The cursor starts at 0, changes with each iteration, and returns to 0 when iteration is complete.

Cursor-by-Reference Pattern

The cursor is modified in-place, allowing applications to track iteration state:

Sources: src/RedisConnection.php531-637

---

Options Parsing

All scan operations accept flexible option formats through the getScanOptions() helper method:

Implementation Details

src/RedisConnection.php515-523

This helper enables both calling styles:

Sources: src/RedisConnection.php515-523

---

Return Value Transformation

The scan operations return different values depending on the shouldTransform flag and the iteration state:

Transformation Mode (shouldTransform = true)

Condition	Return Value	Meaning
$cursor === 0 && empty($result)	false	No keys found (empty database/collection)
$cursor === 0 && !empty($result)	[0, $result]	Final iteration with results
$cursor !== 0	[$cursor, $result]	Iteration continues

Native Mode (shouldTransform = false)

The method delegates to the parent Hyperf implementation, which returns the raw PHP Redis extension result format.

Example: Scan Keys Operation

src/RedisConnection.php531-550

Sources: src/RedisConnection.php531-550

---

Scan Command Reference

Each scan method has identical transformation logic but operates on different data structures:

scan(&$cursor, ...$arguments)

Scans all keys in the current database.

Parameters:

• &$cursor - Cursor position (modified by reference)
• ...$arguments - Options array or variadic pattern/count

Returns:

• false - No keys found (when shouldTransform = true)
• [$cursor, $keys] - Updated cursor and array of matching keys

Example:

Sources: src/RedisConnection.php531-550

---

zscan($key, &$cursor, ...$arguments)

Scans members and scores in a sorted set.

Parameters:

• $key - Sorted set key
• &$cursor - Cursor position (modified by reference)
• ...$arguments - Options array or variadic pattern/count

Returns:

• false - No members found (when shouldTransform = true)
• [$cursor, $members] - Updated cursor and associative array of member => score pairs

Example:

Sources: src/RedisConnection.php559-579

---

hscan($key, &$cursor, ...$arguments)

Scans field-value pairs in a hash.

Parameters:

• $key - Hash key
• &$cursor - Cursor position (modified by reference)
• ...$arguments - Options array or variadic pattern/count

Returns:

• false - No fields found (when shouldTransform = true)
• [$cursor, $fields] - Updated cursor and associative array of field => value pairs

Example:

Sources: src/RedisConnection.php588-608

---

sscan($key, &$cursor, ...$arguments)

Scans members in a set.

Parameters:

• $key - Set key
• &$cursor - Cursor position (modified by reference)
• ...$arguments - Options array or variadic pattern/count

Returns:

• false - No members found (when shouldTransform = true)
• [$cursor, $members] - Updated cursor and array of member values

Example:

Sources: src/RedisConnection.php617-637

---

Dual-Mode Operation

Each scan method checks the shouldTransform flag to determine behavior:

Native Mode Behavior

When shouldTransform = false, the scan methods delegate to their parent implementations in Hyperf\Redis\RedisConnection. This provides direct access to the PHP Redis extension behavior without any transformations.

Transformation Mode Behavior

When shouldTransform = true, the methods apply Laravel-compatible transformations:

1. Options parsing: Flexible array or variadic format
2. Result normalization: Convert false to empty array
3. Return format: Wrap cursor and results in array
4. Empty handling: Return false when no results at cursor 0

Sources: src/RedisConnection.php531-637

---

Complete Scan Iteration Example

Sources: src/RedisConnection.php515-637

---

Edge Cases and Special Handling

Empty Database/Collection

When scanning an empty database or collection:

• First call with $cursor = 0 returns false immediately
• No iteration occurs
• Application can detect empty state without additional checks

False Values from Redis

The PHP Redis extension returns false when no keys match during a scan iteration. The transformation layer normalizes this to an empty array to simplify result handling:

This ensures the return value is always false (for empty at cursor 0) or [$cursor, $result] (array), never [$cursor, false].

Pattern Matching

All scan operations support pattern matching via the match option:

• Patterns use Redis glob-style syntax: *, ?, [abc], [a-z]
• Default pattern is * (match all)
• Pattern matching happens on the Redis server

Count Hint

The count option is a hint to Redis about how many elements to return per iteration:

• Default value is 10
• Actual number returned may be more or less than specified
• Higher counts reduce iteration overhead but increase response time per call
• Redis may return 0 elements even when more exist (continue iterating)

Sources: src/RedisConnection.php515-637