Alpha ZealPHP is early-stage and under active development. APIs may change between minor versions until v1.0. Feedback and bug reports welcome on GitHub.
Esc
API Index — Namespaces, Packages, Reports, Indices

PhpredisDriver
in package
implements RedisDriver

FinalYes

phpredis-backed driver. Only instantiable when the redis PHP extension is loaded; the adapter falls back to predis otherwise. Tests skip the phpredis-specific path when the ext isn't present (covered by CI matrix).

Table of Contents

Interfaces

RedisDriver
Behavioural contract for a Redis/Valkey client lib (phpredis or predis).

Properties

$c  : Redis
$url  : string
Original URL kept so subscribe() can spawn fresh per-coroutine clients.

Methods

__construct()  : mixed
Connect to the Redis server at $url using the phpredis extension.
close()  : void
Close the underlying \Redis connection. Tolerant on failure — logs at debug level via elog() rather than throwing (H9 hardening).
decrby()  : int
Atomically decrement a plain string counter key by $by via DECRBY. Returns the new value.
del()  : int
Delete one or more keys. Returns the number of keys that were removed.
evalScript()  : mixed
Execute a Lua script server-side via EVAL. Server-atomic — no other command interleaves during execution. $keys are the KEYS[n] values (cluster-routing hint); $args are the ARGV[n] values.
exists()  : bool
Return true when the key exists in Redis.
expire()  : bool
Set an expiry of $ttlSeconds on $key via Redis EXPIRE. Returns true on success.
get()  : string|null
Get a plain string key. Returns null on miss or when the key doesn't exist.
hdel()  : int
Delete one or more hash fields via HDEL. Returns the number of fields removed.
hgetall()  : array<string, string>
Return all fields and values of a hash via HGETALL.
hincrby()  : int
Atomically increment a hash field by $by (integer) via HINCRBY. Returns the new value.
hincrbyfloat()  : float
Atomically increment a hash field by $by (float) via HINCRBYFLOAT. Returns the new value.
hmget()  : array<int, string|null>
Return the values of specific hash $fields via HMGET. Missing fields are returned as null at the corresponding index position.
hset()  : int
Set multiple hash fields via HMSET. Returns the number of fields written.
incrby()  : int
Atomically increment a plain string counter key by $by via INCRBY. Returns the new value.
mhgetall()  : array<int, array<string, string>>
Pipelined HGETALL for multiple keys (H3 hardening). Returns a list of hash maps in the same order as $keys; empty arrays for non-existent keys.
mhsetWithMembership()  : void
Pipelined bulk write: HMSET each row, optionally EXPIRE it, and optionally SADD its membership key to $setKey — all in a single pipeline round-trip (H3 hardening). Used by RedisBackend::mset().
name()  : string
Return the driver identifier string 'phpredis'.
ping()  : bool
Ping the Redis server. Returns true when the server responds with PONG.
pipeline()  : array<int, mixed>
Execute a batch of commands in a single pipelined round-trip via Redis::PIPELINE. The $batch callable receives the pipeline object and queues commands on it; results are returned as a flat list in command order.
publish()  : int
Publish $payload to a Redis pub/sub $channel via PUBLISH.
sadd()  : int
Add members to a Redis Set via SADD. Returns the number of members actually added (existing members are ignored). No-op (returns 0) when $members is empty.
scanCursor()  : array{0: string, 1: list}
Single-batch keyspace SCAN with cursor. Returns [next-cursor, keys].
scanKeys()  : Generator<int, string>
Full keyspace scan matching $match via SCAN. Yields string keys one at a time across all batches. Use scanCursor() for paginated access.
scard()  : int
Return the cardinality of a Redis Set via SCARD. O(1).
set()  : bool
Set a plain string key. Applies EX $ttlSeconds when provided.
srem()  : int
Remove members from a Redis Set via SREM. Returns the number of members removed.
sscan()  : Generator<int, string>
Full set scan via SSCAN. Yields string members one at a time across all scan batches. Use sscanCursor() for paginated access.
sscanCursor()  : array{0: string, 1: list}
Single-batch SSCAN with cursor. Returns [next-cursor, members].
subscribe()  : void
phpredis splits SUBSCRIBE / PSUBSCRIBE into two separate blocking methods, each with its own callback shape. The driver unifies them under the single RedisDriver::subscribe() contract by running both in parallel coroutines whose callbacks push frames into a shared Channel that the driver routes to the user-supplied consumer.
unlink()  : int
Asynchronously delete keys via UNLINK (non-blocking reclaim, unlike DEL).
xack()  : int
Acknowledge one or more stream entries via XACK, removing them from the consumer group's pending-entries list. Returns the number of entries successfully acknowledged. No-op (returns 0) when called with no IDs.
xadd()  : string
Append an entry to a Redis Stream via XADD. Returns the auto-generated entry ID (e.g. '1710000000000-0'). Applies MAXLEN ~ trimming when $maxLen is provided. Throws StoreException when $fields is empty.
xautoclaim()  : array{0: string, 1: list}>}
Claim pending stream entries that have been idle for at least $minIdleMs milliseconds via XAUTOCLAIM. Used to recover messages from dead consumers.
xgroupCreate()  : bool
Create a consumer group on $stream starting at $id (default '$' = only new entries). When $mkStream is true, creates the stream if it doesn't exist. Returns true on success, false when the group already exists (BUSYGROUP — treated as idempotent).
xreadGroup()  : array<string, array<int, array{id: string, payload: array}>>
Read new entries from one or more streams via XREADGROUP. Blocks for up to $blockMs milliseconds when no new entries are available.
buildClient()  : Redis
Build a fresh \Redis client connected per the URL.
parseUrl()  : array{scheme: string, host: string, port: int, pass: ?string, db: int, tls: bool}
Parse a redis:// or rediss:// (TLS) URL. Predis also accepts tls:// as a synonym for rediss://; phpredis is consistent with that.
wrap()  : StoreException
Wrap a \RedisException in a StoreException with a phpredis: prefix for uniform error handling.

Properties

$url

Original URL kept so subscribe() can spawn fresh per-coroutine clients.

private string $url

Methods

__construct()

Connect to the Redis server at $url using the phpredis extension.

public __construct(string $url) : mixed

Throws StoreException when ext-redis is not loaded, or when the connection attempt fails.

Parameters
$url : string

close()

Close the underlying \Redis connection. Tolerant on failure — logs at debug level via elog() rather than throwing (H9 hardening).

public close() : void

decrby()

Atomically decrement a plain string counter key by $by via DECRBY. Returns the new value.

public decrby(string $key, int $by) : int
Parameters
$key : string
$by : int
Return values
int

del()

Delete one or more keys. Returns the number of keys that were removed.

public del(string ...$keys) : int

No-op (returns 0) when called with an empty list.

Parameters
$keys : string
Return values
int

evalScript()

Execute a Lua script server-side via EVAL. Server-atomic — no other command interleaves during execution. $keys are the KEYS[n] values (cluster-routing hint); $args are the ARGV[n] values.

public evalScript(string $script, array<int, string> $keys, array<int, string> $args) : mixed
Parameters
$script : string
$keys : array<int, string>
$args : array<int, string>

exists()

Return true when the key exists in Redis.

public exists(string $key) : bool
Parameters
$key : string
Return values
bool

expire()

Set an expiry of $ttlSeconds on $key via Redis EXPIRE. Returns true on success.

public expire(string $key, int $ttlSeconds) : bool
Parameters
$key : string
$ttlSeconds : int
Return values
bool

get()

Get a plain string key. Returns null on miss or when the key doesn't exist.

public get(string $key) : string|null
Parameters
$key : string
Return values
string|null

hdel()

Delete one or more hash fields via HDEL. Returns the number of fields removed.

public hdel(string $key, string ...$fields) : int

No-op (returns 0) when called with an empty list.

Parameters
$key : string
$fields : string
Return values
int

hgetall()

Return all fields and values of a hash via HGETALL.

public hgetall(string $key) : array<string, string>

Returns an empty array when the key does not exist.

Parameters
$key : string
Return values
array<string, string>

hincrby()

Atomically increment a hash field by $by (integer) via HINCRBY. Returns the new value.

public hincrby(string $key, string $field, int $by) : int
Parameters
$key : string
$field : string
$by : int
Return values
int

hincrbyfloat()

Atomically increment a hash field by $by (float) via HINCRBYFLOAT. Returns the new value.

public hincrbyfloat(string $key, string $field, float $by) : float
Parameters
$key : string
$field : string
$by : float
Return values
float

hmget()

Return the values of specific hash $fields via HMGET. Missing fields are returned as null at the corresponding index position.

public hmget(string $key, array<int, string> $fields) : array<int, string|null>
Parameters
$key : string
$fields : array<int, string>
Return values
array<int, string|null>

hset()

Set multiple hash fields via HMSET. Returns the number of fields written.

public hset(string $key, array<string, string> $fields) : int

No-op (returns 0) when $fields is empty.

Parameters
$key : string
$fields : array<string, string>
Return values
int

incrby()

Atomically increment a plain string counter key by $by via INCRBY. Returns the new value.

public incrby(string $key, int $by) : int
Parameters
$key : string
$by : int
Return values
int

mhgetall()

Pipelined HGETALL for multiple keys (H3 hardening). Returns a list of hash maps in the same order as $keys; empty arrays for non-existent keys.

public mhgetall(array<int, string> $keys) : array<int, array<string, string>>
Parameters
$keys : array<int, string>
Return values
array<int, array<string, string>>

mhsetWithMembership()

Pipelined bulk write: HMSET each row, optionally EXPIRE it, and optionally SADD its membership key to $setKey — all in a single pipeline round-trip (H3 hardening). Used by RedisBackend::mset().

public mhsetWithMembership(array<int, array{rk: string, fields: array, sk?: string}> $writes[, string|null $setKey = null ][, int|null $ttl = null ]) : void
Parameters
$writes : array<int, array{rk: string, fields: array, sk?: string}>
$setKey : string|null = null
$ttl : int|null = null

name()

Return the driver identifier string 'phpredis'.

public name() : string
Return values
string

ping()

Ping the Redis server. Returns true when the server responds with PONG.

public ping() : bool
Return values
bool

pipeline()

Execute a batch of commands in a single pipelined round-trip via Redis::PIPELINE. The $batch callable receives the pipeline object and queues commands on it; results are returned as a flat list in command order.

public pipeline(callable $batch) : array<int, mixed>
Parameters
$batch : callable
Return values
array<int, mixed>

publish()

Publish $payload to a Redis pub/sub $channel via PUBLISH.

public publish(string $channel, string $payload) : int

Returns the number of subscribers that received the message.

Parameters
$channel : string
$payload : string
Return values
int —

receivers Redis delivered to

sadd()

Add members to a Redis Set via SADD. Returns the number of members actually added (existing members are ignored). No-op (returns 0) when $members is empty.

public sadd(string $key, array<int, string> $members) : int
Parameters
$key : string
$members : array<int, string>
Return values
int

scanCursor()

Single-batch keyspace SCAN with cursor. Returns [next-cursor, keys].

public scanCursor(string $match, string $cursor, int $count) : array{0: string, 1: list}

A returned cursor of '0' signals end-of-scan.

Parameters
$match : string
$cursor : string
$count : int
Return values
array{0: string, 1: list}

scanKeys()

Full keyspace scan matching $match via SCAN. Yields string keys one at a time across all batches. Use scanCursor() for paginated access.

public scanKeys(string $match[, int $batch = 200 ]) : Generator<int, string>
Parameters
$match : string
$batch : int = 200
Return values
Generator<int, string>

scard()

Return the cardinality of a Redis Set via SCARD. O(1).

public scard(string $key) : int
Parameters
$key : string
Return values
int

set()

Set a plain string key. Applies EX $ttlSeconds when provided.

public set(string $key, string $value[, int|null $ttlSeconds = null ]) : bool

Returns true on success.

Parameters
$key : string
$value : string
$ttlSeconds : int|null = null
Return values
bool

srem()

Remove members from a Redis Set via SREM. Returns the number of members removed.

public srem(string $key, array<int, string> $members) : int

No-op (returns 0) when $members is empty.

Parameters
$key : string
$members : array<int, string>
Return values
int

sscan()

Full set scan via SSCAN. Yields string members one at a time across all scan batches. Use sscanCursor() for paginated access.

public sscan(string $key[, int $batch = 100 ]) : Generator<int, string>
Parameters
$key : string
$batch : int = 100
Return values
Generator<int, string>

sscanCursor()

Single-batch SSCAN with cursor. Returns [next-cursor, members].

public sscanCursor(string $key, string $cursor, int $count) : array{0: string, 1: list}

A returned cursor of '0' signals end-of-scan. phpredis takes the cursor by reference (int|null) — this method drives it exactly once and coerces the result to the string-cursor contract.

Parameters
$key : string
$cursor : string
$count : int
Return values
array{0: string, 1: list}

subscribe()

phpredis splits SUBSCRIBE / PSUBSCRIBE into two separate blocking methods, each with its own callback shape. The driver unifies them under the single RedisDriver::subscribe() contract by running both in parallel coroutines whose callbacks push frames into a shared Channel that the driver routes to the user-supplied consumer.

public subscribe(array<string|int, mixed> $exactChannels, array<string|int, mixed> $patternChannels, callable $consumer) : void
Parameters
$exactChannels : array<string|int, mixed>

channels for SUBSCRIBE

$patternChannels : array<string|int, mixed>

patterns for PSUBSCRIBE (Redis * glob)

$consumer : callable

unlink()

Asynchronously delete keys via UNLINK (non-blocking reclaim, unlike DEL).

public unlink(string ...$keys) : int

Returns the number of keys that existed. No-op (returns 0) when called with an empty list.

Parameters
$keys : string
Return values
int

xack()

Acknowledge one or more stream entries via XACK, removing them from the consumer group's pending-entries list. Returns the number of entries successfully acknowledged. No-op (returns 0) when called with no IDs.

public xack(string $stream, string $group, string ...$ids) : int
Parameters
$stream : string
$group : string
$ids : string
Return values
int —

ids actually ACK'd

xadd()

Append an entry to a Redis Stream via XADD. Returns the auto-generated entry ID (e.g. '1710000000000-0'). Applies MAXLEN ~ trimming when $maxLen is provided. Throws StoreException when $fields is empty.

public xadd(string $stream, array<string, string> $fields[, int|null $maxLen = null ]) : string
Parameters
$stream : string
$fields : array<string, string>
$maxLen : int|null = null

if set, applied as MAXLEN ~ trimming

Return values
string

xautoclaim()

Claim pending stream entries that have been idle for at least $minIdleMs milliseconds via XAUTOCLAIM. Used to recover messages from dead consumers.

public xautoclaim(string $stream, string $group, string $consumer, int $minIdleMs[, string $start = '0-0' ][, int $count = 16 ]) : array{0: string, 1: list}>}

Returns [next-cursor, entries]; iterate until cursor is '0-0' to drain.

Parameters
$stream : string
$group : string
$consumer : string
$minIdleMs : int
$start : string = '0-0'
$count : int = 16
Return values
array{0: string, 1: list}>}

xgroupCreate()

Create a consumer group on $stream starting at $id (default '$' = only new entries). When $mkStream is true, creates the stream if it doesn't exist. Returns true on success, false when the group already exists (BUSYGROUP — treated as idempotent).

public xgroupCreate(string $stream, string $group[, string $id = '$' ][, bool $mkStream = true ]) : bool
Parameters
$stream : string
$group : string
$id : string = '$'
$mkStream : bool = true
Return values
bool

xreadGroup()

Read new entries from one or more streams via XREADGROUP. Blocks for up to $blockMs milliseconds when no new entries are available.

public xreadGroup(string $group, string $consumer, array<int, string> $streams, int $count, int $blockMs) : array<string, array<int, array{id: string, payload: array}>>

Returns a map of stream name → list of {id, payload} entries.

Parameters
$group : string
$consumer : string
$streams : array<int, string>
$count : int
$blockMs : int
Return values
array<string, array<int, array{id: string, payload: array}>>

buildClient()

Build a fresh \Redis client connected per the URL.

private static buildClient(string $url) : Redis
Parameters
$url : string
Return values
Redis

parseUrl()

Parse a redis:// or rediss:// (TLS) URL. Predis also accepts tls:// as a synonym for rediss://; phpredis is consistent with that.

private static parseUrl(string $url) : array{scheme: string, host: string, port: int, pass: ?string, db: int, tls: bool}
Parameters
$url : string
Return values
array{scheme: string, host: string, port: int, pass: ?string, db: int, tls: bool}

wrap()

Wrap a \RedisException in a StoreException with a phpredis: prefix for uniform error handling.

private wrap(RedisException $e) : StoreException
Parameters
$e : RedisException
Return values
StoreException
On this page