Incrementally iterates matching keys with a mutable cursor.
The objective is to understand the behavior and operational limits, not only the method name.
What It Does
Incrementally iterates matching keys with a mutable cursor.
Syntax and Return Value
Redis::scan(...)The return value and exceptional cases depend on the call described here: SCAn may return duplicates or zero elements in a page; do not treat it as a consistent snapshot.
Requirements: install and enable the corresponding PHP driver or extension and configure the service before running the examples.
Example 1: Basic Use
Requires the phpredis extension and a running Redis server. Keys use a guide-specific prefix; clean up example keys after experimenting.
<?php
$redis = new Redis();
$redis->connect(getenv('REDIS_HOST') ?: '127.0.0.1', (int) (getenv('REDIS_PORT') ?: 6379), 2.0);
$cursor = null;
do { $keys = $redis->scan($cursor, "guide:scan:*", 3); if ($keys !== false) foreach ($keys as $key) echo $key . PHP_EOL; } while ($cursor !== 0);Example 2: A Second Scenario
Requires the phpredis extension and a running Redis server. Keys use a guide-specific prefix; clean up example keys after experimenting.
<?php
$redis = new Redis();
$redis->connect(getenv('REDIS_HOST') ?: '127.0.0.1', (int) (getenv('REDIS_PORT') ?: 6379), 2.0);
$cursor = null;
do { $keys = $redis->scan($cursor, "guide:scan:*", 4); if ($keys !== false) foreach ($keys as $key) echo $key . PHP_EOL; } while ($cursor !== 0);Example 3: Practical Checks
Requires the phpredis extension and a running Redis server. Keys use a guide-specific prefix; clean up example keys after experimenting.
<?php
$redis = new Redis();
$redis->connect(getenv('REDIS_HOST') ?: '127.0.0.1', (int) (getenv('REDIS_PORT') ?: 6379), 2.0);
$cursor = null;
do { $keys = $redis->scan($cursor, "guide:scan:*", 5); if ($keys !== false) foreach ($keys as $key) echo $key . PHP_EOL; } while ($cursor !== 0);Important Behavior and Edge Cases
SCAn may return duplicates or zero elements in a page; do not treat it as a consistent snapshot.
For production use, also account for error handling, data validation, resource limits and environment-specific driver behavior.
Comparison with Related Approaches
| Approach | Important distinction |
|---|---|
| Redis::scan | Incrementally iterates matching keys with a mutable cursor. |
| Related API / pattern | KEYS scans the entire key space at once and can block Redis. |
Common Beginner Mistakes
| Mistake | Correct approach |
|---|---|
| Assuming the happy path covers edge cases | SCAn may return duplicates or zero elements in a page; do not treat it as a consistent snapshot. |
| Using a related API interchangeably | KEYS scans the entire key space at once and can block Redis. |
Key Takeaways
- Incrementally iterates matching keys with a mutable cursor.
- SCAn may return duplicates or zero elements in a page; do not treat it as a consistent snapshot.
- KEYS scans the entire key space at once and can block Redis.
Choose this API or pattern when its exact semantics match your task, and verify the result against the database driver and runtime used by your application.