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

PredisDriver
in package
implements RedisDriver

FinalYes

predis-backed driver. Pure PHP — works without ext-redis. Slower than phpredis but parity-tested against the same RedisClientTest cases.

predis::__call() returns mixed; this driver narrows each return at the boundary so StoreException is thrown if the wire shape doesn't match expectations (vs casting mixed and hiding bugs).

Table of Contents

Interfaces

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

Properties

$c  : Client

Methods

__construct()  : mixed
Construct from EITHER: - a redis://... URL string (single-node, default path), OR - a pre-built Predis\Client (for Cluster / Sentinel / advanced pre-wired configurations — see Store::fromPredisClient()).
close()  : void
Disconnect from Redis, silently swallowing any errors (tolerant close).
decrby()  : int
del()  : int
evalScript()  : mixed
exists()  : bool
expire()  : bool
get()  : string|null
hdel()  : int
hgetall()  : array<string, string>
hincrby()  : int
hincrbyfloat()  : float
hmget()  : array<int, string|null>
hset()  : int
incrby()  : int
mhgetall()  : array<int, array<string, string>>
Pipelined batch HGETALL for multiple hash keys. Returns an indexed array (same order as $keys) where each element is an array<string,string> of field→value pairs (empty array for a missing key). Uses Predis\Command\RawCommand to keep PHPStan happy on the pipeline surface; pairs the flat multi-bulk response into assoc form for both old and new predis response shapes.
mhsetWithMembership()  : void
Pipelined batch HMSET with optional per-key TTL and optional set-membership tracking.
name()  : string
ping()  : bool
pipeline()  : array<int, mixed>
Execute a batch of Redis commands in a single pipeline round-trip.
publish()  : int
Publish a message to a Redis pub/sub channel. Returns the number of subscribers that received the message.
sadd()  : int
scanCursor()  : array{0: string, 1: list}
One-batch cursor-based SCAN MATCH (S-3). Same semantics as sscanCursor but against the keyspace via SCAN.
scanKeys()  : Generator<int, string>
scard()  : int
set()  : bool
srem()  : int
sscan()  : Generator<int, string>
sscanCursor()  : array{0: string, 1: list}
One-batch cursor-based SSCAN (S-3). Returns [nextCursor, members].
subscribe()  : void
Enter a blocking pub/sub loop, dispatching each received message to $consumer($payload, $channel, $pattern).
unlink()  : int
Non-blocking key deletion via UNLINK (async reclaim, unlike DEL).
xack()  : int
Acknowledge one or more processed stream entries (XACK). Returns the number of entries successfully acknowledged. Unrecognised IDs are silently ignored by Redis.
xadd()  : string
Append an entry to a Redis Stream (XADD). Returns the auto-generated entry ID.
xautoclaim()  : array{0: string, 1: list}>}
Claim pending stream entries idle for at least $minIdleMs milliseconds (XAUTOCLAIM).
xgroupCreate()  : bool
Create a consumer group (XGROUP CREATE). Returns true on success, false when the group already exists (BUSYGROUP — idempotent). When $mkStream is true, the stream is created if absent (MKSTREAM).
xreadGroup()  : array<string, array<int, array{id: string, payload: array}>>
Read new entries from one or more streams as a consumer group member (XREADGROUP GROUP … BLOCK).
asInt()  : int
Narrow a mixed Redis response to int. Accepts numeric strings.
asString()  : string
Narrow a mixed Redis response to string. Accepts scalars and objects with __toString.
isOkStatus()  : bool
Return true when the raw Redis response equals $expect (string comparison, with __toString fallback for predis status objects like Status::get('OK')).
scanResult()  : array{0: int, 1: array}
Normalize a SCAN/SSCAN result tuple into [int cursor, list<string>].
wrap()  : StoreException
Wrap a PredisException in a StoreException for uniform error handling across drivers.

Properties

Methods

__construct()

Construct from EITHER: - a redis://... URL string (single-node, default path), OR - a pre-built Predis\Client (for Cluster / Sentinel / advanced pre-wired configurations — see Store::fromPredisClient()).

public __construct(string|Client $urlOrClient) : mixed

Cluster: new PredisClient(['tcp://n1:7000', 'tcp://n2:7000'], ['cluster' => 'redis']) Sentinel: new PredisClient(['tcp://sentinel1:26379', ...], ['replication' => 'sentinel', 'service' => 'mymaster'])

Parameters
$urlOrClient : string|Client

close()

Disconnect from Redis, silently swallowing any errors (tolerant close).

public close() : void

decrby()

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

del()

public del(string ...$keys) : int
Parameters
$keys : string
Return values
int

evalScript()

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

exists()

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

expire()

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

get()

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

hdel()

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

hgetall()

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

hincrby()

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

hincrbyfloat()

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

hmget()

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

hset()

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

incrby()

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

mhgetall()

Pipelined batch HGETALL for multiple hash keys. Returns an indexed array (same order as $keys) where each element is an array<string,string> of field→value pairs (empty array for a missing key). Uses Predis\Command\RawCommand to keep PHPStan happy on the pipeline surface; pairs the flat multi-bulk response into assoc form for both old and new predis response shapes.

public mhgetall(array<string|int, mixed> $keys) : array<int, array<string, string>>
Parameters
$keys : array<string|int, mixed>

full Redis keys (already prefixed by caller)

Return values
array<int, array<string, string>>

mhsetWithMembership()

Pipelined batch HMSET with optional per-key TTL and optional set-membership tracking.

public mhsetWithMembership(array<string|int, mixed> $writes[, string|null $setKey = null ][, int|null $ttl = null ]) : void

Each entry in $writes is array{rk: string, fields: array<string,string>, sk?: string}: rk is the hash key, fields are the field→value pairs, sk (when $setKey is set) is the member to add to the tracking SET. All commands run in a single pipeline round-trip.

Parameters
$writes : array<string|int, mixed>
$setKey : string|null = null
$ttl : int|null = null

pipeline()

Execute a batch of Redis commands in a single pipeline round-trip.

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

$batch receives the predis Pipeline object; queue commands on it. Returns an indexed array of raw responses in command order.

Parameters
$batch : callable
Return values
array<int, mixed>

publish()

Publish a message to a Redis pub/sub channel. Returns the number of subscribers that received the message.

public publish(string $channel, string $payload) : int
Parameters
$channel : string
$payload : string
Return values
int —

receivers Redis delivered to

sadd()

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

scanCursor()

One-batch cursor-based SCAN MATCH (S-3). Same semantics as sscanCursor but against the keyspace via SCAN.

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

scanKeys()

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

scard()

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

set()

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

srem()

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

sscan()

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

sscanCursor()

One-batch cursor-based SSCAN (S-3). Returns [nextCursor, members].

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

$cursor === '0' starts a fresh scan; when the returned next-cursor is '0' the scan is exhausted. Use when iterating large SETs without blocking on a full generator drain — required for paginated UIs.

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

subscribe()

Enter a blocking pub/sub loop, dispatching each received message to $consumer($payload, $channel, $pattern).

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

Exact channels use SUBSCRIBE; pattern channels use PSUBSCRIBE. Throw PubSubStopException from inside $consumer to cleanly exit the loop.

Parameters
$exactChannels : array<string|int, mixed>

channels for SUBSCRIBE

$patternChannels : array<string|int, mixed>

patterns for PSUBSCRIBE (Redis * glob)

$consumer : callable

unlink()

Non-blocking key deletion via UNLINK (async reclaim, unlike DEL).

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

Returns the number of keys scheduled for deletion. Returns 0 for empty input.

Parameters
$keys : string
Return values
int

xack()

Acknowledge one or more processed stream entries (XACK). Returns the number of entries successfully acknowledged. Unrecognised IDs are silently ignored by Redis.

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 (XADD). Returns the auto-generated entry ID.

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

When $maxLen is set, trims the stream to approximately that length (MAXLEN ~). Throws StoreException when $fields is empty.

Parameters
$stream : string
$fields : array<string|int, mixed>

field=>value pairs forming the stream entry

$maxLen : int|null = null

if set, applied as MAXLEN ~ trimming

Return values
string

xautoclaim()

Claim pending stream entries idle for at least $minIdleMs milliseconds (XAUTOCLAIM).

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

Returns [nextCursor, list<array{id:string, payload:array<string,string>}>]. Iterate until nextCursor === '0-0' to drain all orphan entries. Compatible with Redis 6 (2-element response) and Redis 7 (3-element response with deleted IDs).

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 (XGROUP CREATE). Returns true on success, false when the group already exists (BUSYGROUP — idempotent). When $mkStream is true, the stream is created if absent (MKSTREAM).

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 as a consumer group member (XREADGROUP GROUP … BLOCK).

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

Returns array<streamName, list<array{id:string, payload:array<string,string>}>>. Returns [] on timeout (blocking expired with no messages) or empty $streams.

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

keyed by stream

asInt()

Narrow a mixed Redis response to int. Accepts numeric strings.

private asInt(mixed $r, string $op) : int

Throws StoreException with the $op context when the value is neither.

Parameters
$r : mixed
$op : string
Return values
int

asString()

Narrow a mixed Redis response to string. Accepts scalars and objects with __toString.

private asString(mixed $r, string $op) : string

Throws StoreException with the $op context for non-stringable values.

Parameters
$r : mixed
$op : string
Return values
string

isOkStatus()

Return true when the raw Redis response equals $expect (string comparison, with __toString fallback for predis status objects like Status::get('OK')).

private isOkStatus(mixed $r[, string $expect = 'OK' ]) : bool
Parameters
$r : mixed
$expect : string = 'OK'
Return values
bool

scanResult()

Normalize a SCAN/SSCAN result tuple into [int cursor, list<string>].

private scanResult(mixed $res, string $op) : array{0: int, 1: array}
Parameters
$res : mixed
$op : string
Return values
array{0: int, 1: array}

wrap()

Wrap a PredisException in a StoreException for uniform error handling across drivers.

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