-The best way to support the project is through [GitHub sponsors](https://github.com/sponsors/michael-grunder). Many of the reward tiers grant access to our [slack channel](https://phpredis.slack.com) where [myself](https://github.com/michael-grunder) and [Pavlo](https://github.com/yatsukhnenko) are regularly available to answer questions. Additionally this will allow you to provide feedback on which fixes and new features to prioritize.
+## Become a Sponsor
+PhpRedis will always be free and open source software and if you or your company has found it useful please consider supporting the project. Developing a large, complex, and performant library like PhpRedis takes a great deal of time and effort, and support is greatly appreciated! :heart:
-You can also make a one-time contribution with [](https://www.paypal.me/michaelgrunder/5)
+The ongoing development of PhpRedis is made possible thanks to the generous support of [Relay](https://relay.so), which funds the vast majority of work on the project. Relay is a high-performance in-memory cache and drop-in replacement for PhpRedis, which handles millions of requests per second without breaking a sweat.
-## Sponsors
-
-
-
-
+The best way to support the project is through [GitHub Sponsors](https://github.com/sponsors/michael-grunder). Many of the reward tiers grant access to our [Slack](https://phpredis.slack.com) where [myself](https://github.com/michael-grunder) and [Pavlo](https://github.com/yatsukhnenko) are regularly available to answer questions. Additionally this will allow you to provide feedback on which fixes and features to prioritize. You can also make a one-time contribution with [PayPal](https://www.paypal.me/michaelgrunder/5).
-# Table of contents
------
+## Table of contents
1. [Installing/Configuring](#installingconfiguring)
* [Installation](#installation)
* [PHP Session handler](#php-session-handler)
- * [Distributed Redis Array](./array.md#readme)
+ * [Distributed Redis Array](./arrays.md#readme)
* [Redis Cluster support](./cluster.md#readme)
* [Redis Sentinel support](./sentinel.md#readme)
* [Running the unit tests](#running-the-unit-tests)
-1. [Classes and methods](#classes-and-methods)
+2. [API Documentation](#api-documentation)
+3. [Classes and methods](#classes-and-methods)
* [Usage](#usage)
* [Connection](#connection)
* [Retry and backoff](#retry-and-backoff)
@@ -51,31 +57,26 @@ You can also make a one-time contribution with [
* [Transactions](#transactions)
* [Scripting](#scripting)
+ * [Local Helper Methods](#local-helper-methods)
* [Introspection](#introspection)
------
-
-# Installing/Configuring
------
+## Installing/Configuring
-## Installation
+### Installation
For everything you should need to install PhpRedis on your system,
see the [INSTALL.md](./INSTALL.md) page.
-## PHP Session handler
+### PHP Session handler
-phpredis can be used to store PHP sessions. To do this, configure `session.save_handler` and `session.save_path` in your php.ini to tell phpredis where to store the sessions:
-~~~
-session.save_handler = redis
-session.save_path = "tcp://host1:6379?weight=1, tcp://host2:6379?weight=2&timeout=2.5, tcp://host3:6379?weight=2&read_timeout=2.5"
-~~~
+phpredis can be used to store PHP sessions. To do this, configure `session.save_handler` and `session.save_path` in your php.ini to tell phpredis where to store the sessions.
`session.save_path` can have a simple `host:port` format too, but you need to provide the `tcp://` scheme if you want to use the parameters. The following parameters are available:
-* weight (integer): the weight of a host is used in comparison with the others in order to customize the session distribution on several hosts. If host A has twice the weight of host B, it will get twice the amount of sessions. In the example, *host1* stores 20% of all the sessions (1/(1+2+2)) while *host2* and *host3* each store 40% (2/(1+2+2)). The target host is determined once and for all at the start of the session, and doesn't change. The default weight is 1.
+* weight (integer): the weight of a host is used in comparison with the others to customize the session distribution on several hosts. If host A has twice the weight of host B, it will get twice the amount of sessions. In the example, *host1* stores 20% of all the sessions (1/(1+2+2)) while *host2* and *host3* each store 40% (2/(1+2+2)). The target host is determined once and for all at the start of the session, and doesn't change. The default weight is 1.
* timeout (float): the connection timeout to a redis host, expressed in seconds. If the host is unreachable in that amount of time, the session storage will be unavailable for the client. The default timeout is very high (86400 seconds).
-* persistent (integer, should be 1 or 0): defines if a persistent connection should be used.
+* read_timeout (float): the timeout for read operations on an established connection, expressed in seconds. If a Redis response is not received within this time, the session operation fails. The default is `0` (no timeout), meaning PHP can hang indefinitely if Redis becomes unresponsive or a connection goes stale. Setting this to a low value (e.g. `2.5`) is strongly recommended in production environments.
+* persistent (integer, should be 1 or 0): defines if a persistent connection should be used. The default value is `0` (persistent connection is not used).
* prefix (string, defaults to "PHPREDIS_SESSION:"): used as a prefix to the Redis key in which the session is stored. The key is composed of the prefix followed by the session ID.
* auth (string, or an array with one or two elements): used to authenticate with the server prior to sending commands.
* database (integer): selects a different database.
@@ -84,12 +85,32 @@ Sessions have a lifetime expressed in seconds and stored in the INI variable "se
The session handler requires a version of Redis supporting `EX` and `NX` options of `SET` command (at least 2.6.12).
phpredis can also connect to a unix domain socket: `session.save_path = "unix:///var/run/redis/redis.sock?persistent=1&weight=1&database=0"`.
-### Session locking
+#### Examples
+
+Multiple Redis servers:
+~~~
+session.save_handler = redis
+session.save_path = "tcp://host1:6379?weight=1, tcp://host2:6379?weight=2&timeout=2.5, tcp://host3:6379?weight=2&read_timeout=2.5"
+~~~
+
+Login to Redis using username and password:
+~~~
+session.save_handler = redis
+session.save_path = "tcp://127.0.0.1:6379?auth[]=user&auth[]=password"
+~~~
+
+Login to Redis using username, password, and set prefix:
+~~~
+session.save_handler = redis
+session.save_path = "tcp://127.0.0.1:6379?auth[]=user&auth[]=password&prefix=user_PHPREDIS_SESSION:"
+~~~
+
+#### Session locking
**Support**: Locking feature is currently only supported for Redis setup with single master instance (e.g. classic master/slave Sentinel environment).
So locking may not work properly in RedisArray or RedisCluster environments.
-Following INI variables can be used to configure session locking:
+The following INI variables can be used to configure session locking:
~~~
; Should the locking be enabled? Defaults to: 0.
redis.session.locking_enabled = 1
@@ -101,7 +122,17 @@ redis.session.lock_wait_time = 50000
redis.session.lock_retries = 2000
~~~
-## Running the unit tests
+#### Session compression
+
+The following INI variables can be used to configure session compression:
+~~~
+; Should session compression be enabled? Possible values are zstd, lzf, lz4, none. Defaults to: none
+redis.session.compression = zstd
+; What compression level should be used? Compression level depends on used library. For most deployments range 1-9 should be fine. Defaults to: 3
+redis.session.compression_level = 3
+~~~
+
+### Running the unit tests
phpredis uses a small custom unit test suite for testing functionality of the various classes. To run tests, simply do the following:
@@ -130,29 +161,32 @@ Note that it is possible to run only tests which match a substring of the test i
php tests/TestRedis.php --class Redis --test echo
~~~
-# Classes and methods
------
+## API Documentation
+
+The [API Documentation](https://phpredis.github.io/phpredis) are a work in progress, but will eventually replace our **ONE README TO RULE THEM ALL** docs.
-## Usage
+## Classes and methods
+
+### Usage
1. [Class Redis](#class-redis)
1. [Class RedisException](#class-redisexception)
1. [Predefined constants](#predefined-constants)
-### Class Redis
+#### Class Redis
-----
_**Description**_: Creates a Redis client
-##### *Example*
+###### *Example*
~~~php
$redis = new Redis();
~~~
Starting from version 6.0.0 it's possible to specify configuration options.
-This allows to connect lazily to the server without explicitly invoking `connect` command.
+This allows to connect lazily to the server without explicitly invoking `connect` / `pconnect`.
-##### *Example*
+###### *Example*
~~~php
$redis = new Redis([
@@ -160,6 +194,7 @@ $redis = new Redis([
'port' => 6379,
'connectTimeout' => 2.5,
'auth' => ['phpredis', 'phpredis'],
+ 'database' => 2,
'ssl' => ['verify_peer' => false],
'backoff' => [
'algorithm' => Redis::BACKOFF_ALGORITHM_DECORRELATED_JITTER,
@@ -169,24 +204,25 @@ $redis = new Redis([
]);
~~~
-##### *Parameters*
+###### *Parameters* (optional)
-*host*: string. can be a host, or the path to a unix domain socket.
-*port*: int (default is 6379, should be -1 for unix domain socket)
-*connectTimeout*: float, value in seconds (default is 0 meaning unlimited)
-*retryInterval*: int, value in milliseconds (optional)
-*readTimeout*: float, value in seconds (default is 0 meaning unlimited)
-*persistent*: mixed, if value is string then it used as persistend id, else value casts to boolean
-*auth*: mixed, authentication information
-*ssl*: array, SSL context options
+*host*: string, the hostname/FQDN/IP address or the path to a unix domain socket; since v5.0.0 it is possible to specify schema
+*port*: int, actual port (e.g. `6379`) or `-1` (or `0`) for unix domain socket; setting to < `0` with non-UDS will assume default of `6379`
+*connectTimeout*: float, value in seconds (default is 0 meaning unlimited)
+*retryInterval*: int, value in milliseconds (optional)
+*readTimeout*: float, value in seconds (default is 0 meaning unlimited)
+*persistent*: mixed, If the value is a string it is used as a persistent ID. Non-strings are cast to boolean.
+*auth*: mixed, authentication information
+*database*: int, database number
+*ssl*: array, SSL context options
-### Class RedisException
+#### Class RedisException
-----
phpredis throws a [RedisException](#class-redisexception) object if it can't reach the Redis server. That can happen in case of connectivity issues,
-if the Redis service is down, or if the redis host is overloaded. In any other problematic case that does not involve an
+if the Redis service is down, or if the Redis host is overloaded. In any other problematic case that does not involve an
unreachable server (such as a key not existing, an invalid command, etc), phpredis will return `FALSE`.
-### Predefined constants
+#### Predefined constants
-----
_**Description**_: Available Redis Constants
@@ -197,12 +233,12 @@ Redis::REDIS_SET - Set
Redis::REDIS_LIST - List
Redis::REDIS_ZSET - Sorted set
Redis::REDIS_HASH - Hash
+Redis::REDIS_STREAM - Stream
+Redis::REDIS_VECTORSET - Vector set
Redis::REDIS_NOT_FOUND - Not found / other
~~~
-@TODO: OPT_SERIALIZER, AFTER, BEFORE,...
-
-## Connection
+### Connection
1. [connect, open](#connect-open) - Connect to a server
1. [pconnect, popen](#pconnect-popen) - Connect to a server (persistent)
@@ -215,25 +251,25 @@ Redis::REDIS_NOT_FOUND - Not found / other
1. [ping](#ping) - Ping the server
1. [echo](#echo) - Echo the given string
-### connect, open
+#### connect, open
-----
-_**Description**_: Connects to a Redis instance.
+_**Description**_: Connects to a Redis instance. If phpredis cannot reach the server it will usually throw a [`RedisException`](#class-redisexception); only rarely will `FALSE` be returned without an exception.
-##### *Parameters*
+###### *Parameters*
-*host*: string. can be a host, or the path to a unix domain socket. Starting from version 5.0.0 it is possible to specify schema
-*port*: int, optional
-*timeout*: float, value in seconds (optional, default is 0 meaning it will use default_socket_timeout)
-*reserved*: should be '' if retry_interval is specified
-*retry_interval*: int, value in milliseconds (optional)
-*read_timeout*: float, value in seconds (optional, default is 0 meaning it will use default_socket_timeout)
-*others*: array, with PhpRedis >= 5.3.0, it allows setting _auth_ and [_stream_](https://www.php.net/manual/en/context.ssl.php) configuration.
+*host*: string, *host*: string, the hostname/FQDN/IP address or the path to a unix domain socket; since v5.0.0 it is possible to specify schema
+*port*: int, actual port (e.g. `6379`) or `-1` (or `0`) for unix domain socket; setting to < `0` with non-UDS will assume default of `6379`, optional
+*timeout*: float, value in seconds (optional, default is 0 meaning it will use default_socket_timeout)
+*reserved*: should be '' if retry_interval is specified
+*retry_interval*: int, value in milliseconds, optional
+*read_timeout*: float, value in seconds (optional, default is 0 meaning it will use default_socket_timeout)
+*others*: array, with PhpRedis >= 5.3.0, it allows setting _auth_ and [_stream_](https://www.php.net/manual/en/context.ssl.php) configuration.
-##### *Return value*
+###### *Return value*
-*BOOL*: `TRUE` on success, `FALSE` on error.
+*BOOL*: `TRUE` on success. Failures typically raise a `RedisException`, though in some edge cases `FALSE` may be returned instead.
-##### *Example*
+###### *Example*
~~~php
$redis->connect('127.0.0.1', 6379);
@@ -247,11 +283,46 @@ $redis->connect('/tmp/redis.sock', 0, 1.5, NULL, 0, 1.5); // Unix socket with 1.
/* With PhpRedis >= 5.3.0 you can specify authentication and stream information on connect */
$redis->connect('127.0.0.1', 6379, 1, '', 0, 0, ['auth' => ['phpredis', 'phpredis']]);
+
+/* TLS connections can customise the underlying PHP stream context */
+$redis->connect('tls://redis.example.com', 6380, 1.5, null, 0, 0, [
+ 'auth' => ['app-user', 'strong-password'],
+ 'stream' => [
+ 'verify_peer' => true, // validate the server certificate against cafile/capath
+ 'verify_peer_name' => true, // require the certificate common/SAN name to match peer_name
+ 'peer_name' => 'redis.example.com', // expected hostname presented by the server certificate
+ 'cafile' => '/etc/ssl/redis-ca.pem', // CA or bundle used to trust the server certificate
+ 'capath' => '/etc/ssl/certs', // directory alternative to cafile
+ 'allow_self_signed' => false, // set to true if you rely on a self-signed certificate
+ 'local_cert' => '/etc/ssl/client.crt', // client certificate for mutual TLS (optional)
+ 'local_pk' => '/etc/ssl/client.key', // private key that matches local_cert (optional)
+ 'passphrase' => 'secret', // passphrase for local_pk if it is encrypted (optional)
+ 'ciphers' => 'HIGH:!aNULL:!MD5', // TLS cipher list provided to OpenSSL (optional)
+ ],
+]);
+
+try {
+ $redis->connect('redis.invalid', 6379);
+} catch (RedisException $ex) {
+ echo "Connection failed: {$ex->getMessage()}";
+}
~~~
+When you pass a `stream` key PhpRedis forwards the options to [`stream_socket_client`](https://www.php.net/manual/en/context.ssl.php).
+Commonly used options include:
+
+- `verify_peer`, `verify_peer_name`, `peer_name`: control server certificate validation behaviour.
+- `cafile`/`capath`: provide the trusted certificate authority bundle when the default store is insufficient.
+- `allow_self_signed`: permits self-signed certificates when set to `true`.
+- `local_cert`, `local_pk`, `passphrase`: configure client-side certificates for mutual TLS.
+- `ciphers`: restrict the negotiated TLS cipher suites.
+- Any other SSL context option supported by PHP (e.g. `SNI_enabled`, `disable_compression`) can also be supplied.
+
+The same array format can be used with `pconnect`/`popen`.
+
**Note:** `open` is an alias for `connect` and will be removed in future versions of phpredis.
-### pconnect, popen
+#### pconnect, popen
-----
_**Description**_: Connects to a Redis instance or reuse a connection already established with `pconnect`/`popen`.
@@ -259,28 +330,28 @@ The connection will not be closed on end of request until the php process ends.
So be prepared for too many open FD's errors (specially on redis server side) when using persistent
connections on many servers connecting to one redis server.
-Also more than one persistent connection can be made identified by either host + port + timeout
+Also more than one persistent connection can be made, identified by either host + port + timeout
or host + persistent_id or unix socket + timeout.
-Starting from version 4.2.1, it became possible to use connection pooling by setting INI variable `redis.pconnect.pooling_enabled` to 1.
+Since v4.2.1, it became possible to use connection pooling by setting INI variable `redis.pconnect.pooling_enabled` to 1.
-This feature is not available in threaded versions. `pconnect` and `popen` then working like their non
+This feature is not available in threaded versions. `pconnect` and `popen` then work like their non
persistent equivalents.
-##### *Parameters*
+###### *Parameters*
-*host*: string. can be a host, or the path to a unix domain socket. Starting from version 5.0.0 it is possible to specify schema
-*port*: int, optional
-*timeout*: float, value in seconds (optional, default is 0 meaning it will use default_socket_timeout)
-*persistent_id*: string. identity for the requested persistent connection
-*retry_interval*: int, value in milliseconds (optional)
-*read_timeout*: float, value in seconds (optional, default is 0 meaning it will use default_socket_timeout)
+*host*: string, *host*: string, the hostname/FQDN/IP address or the path to a unix domain socket; since v5.0.0 it is possible to specify schema
+*port*: int, actual port (e.g. `6379`) or `-1` (or `0`) for unix domain socket; setting to < `0` with non-UDS will assume default of `6379`, optional
+*timeout*: float, value in seconds (optional, default is 0 meaning it will use default_socket_timeout)
+*persistent_id*: string. identity for the requested persistent connection
+*retry_interval*: int, value in milliseconds (optional)
+*read_timeout*: float, value in seconds (optional, default is 0 meaning it will use default_socket_timeout)
-##### *Return value*
+###### *Return value*
*BOOL*: `TRUE` on success, `FALSE` on error.
-##### *Example*
+###### *Example*
~~~php
$redis->pconnect('127.0.0.1', 6379);
@@ -294,20 +365,20 @@ $redis->pconnect('/tmp/redis.sock'); // unix domain socket - would be another co
**Note:** `popen` is an alias for `pconnect` and will be removed in future versions of phpredis.
-### auth
+#### auth
-----
_**Description**_: Authenticate the connection using a password or a username and password.
*Warning*: The password is sent in plain-text over the network.
-##### *Parameters*
+###### *Parameters*
*MIXED*: password
-##### *Return value*
+###### *Return value*
*BOOL*: `TRUE` if the connection is authenticated, `FALSE` otherwise.
*Note*: In order to authenticate with a username and password you need Redis >= 6.0.
-##### *Example*
+###### *Example*
~~~php
/* Authenticate with the password 'foobared' */
$redis->auth('foobared');
@@ -323,60 +394,60 @@ $redis->auth(['user' => 'phpredis', 'pass' => 'phpredis']);
$redis->auth(['pass' => 'phpredis']);
~~~
-### select
+#### select
-----
_**Description**_: Change the selected database for the current connection.
-##### *Parameters*
+###### *Parameters*
*INTEGER*: dbindex, the database number to switch to.
-##### *Return value*
+###### *Return value*
`TRUE` in case of success, `FALSE` in case of failure.
-##### *Example*
+###### *Example*
See method for example: [move](#move)
-### swapdb
+#### swapdb
-----
-_**Description**_: Swap one Redis database with another atomically
+_**Description**_: Swap one Redis database with another atomically
-##### *Parameters*
-*INTEGER*: db1
-*INTEGER*: db2
+###### *Parameters*
+*INTEGER*: db1
+*INTEGER*: db2
-##### *Return value*
+###### *Return value*
`TRUE` on success and `FALSE` on failure.
*Note*: Requires Redis >= 4.0.0
-##### *Example*
+###### *Example*
~~~php
$redis->swapdb(0, 1); /* Swaps DB 0 with DB 1 atomically */
~~~
-### close
+#### close
-----
_**Description**_: Disconnects from the Redis instance.
*Note*: Closing a persistent connection requires PhpRedis >= 4.2.0.
-##### *Parameters*
+###### *Parameters*
None.
-##### *Return value*
+###### *Return value*
*BOOL*: `TRUE` on success, `FALSE` on failure.
-### setOption
+#### setOption
-----
_**Description**_: Set client option.
-##### *Parameters*
-*parameter name*
+###### *Parameters*
+*parameter name*
*parameter value*
-##### *Return value*
+###### *Return value*
*BOOL*: `TRUE` on success, `FALSE` on error.
-##### *Example*
+###### *Example*
~~~php
$redis->setOption(Redis::OPT_SERIALIZER, Redis::SERIALIZER_NONE); // Don't serialize data
$redis->setOption(Redis::OPT_SERIALIZER, Redis::SERIALIZER_PHP); // Use built-in serialize/unserialize
@@ -387,9 +458,9 @@ $redis->setOption(Redis::OPT_SERIALIZER, Redis::SERIALIZER_JSON); // Use JSON t
$redis->setOption(Redis::OPT_PREFIX, 'myAppName:'); // use custom prefix on all keys
/* Options for the SCAN family of commands, indicating whether to abstract
- empty results from the user. If set to SCAN_NORETRY (the default), phpredis
+ empty results from the user. If set to SCAN_NORETRY (the default), phpredis
will just issue one SCAN command at a time, sometimes returning an empty
- array of results. If set to SCAN_RETRY, phpredis will retry the scan command
+ array of results. If set to SCAN_RETRY, phpredis will retry the scan command
until keys come back OR Redis returns an iterator of zero
*/
$redis->setOption(Redis::OPT_SCAN, Redis::SCAN_NORETRY);
@@ -402,36 +473,36 @@ $redis->setOption(Redis::OPT_SCAN, Redis::SCAN_NOPREFIX);
~~~
-### getOption
+#### getOption
-----
_**Description**_: Get client option.
-##### *Parameters*
+###### *Parameters*
*parameter name*
-##### *Return value*
+###### *Return value*
Parameter value.
-##### *Example*
+###### *Example*
~~~php
-// return Redis::SERIALIZER_NONE, Redis::SERIALIZER_PHP,
+// return Redis::SERIALIZER_NONE, Redis::SERIALIZER_PHP,
// Redis::SERIALIZER_IGBINARY, Redis::SERIALIZER_MSGPACK or Redis::SERIALIZER_JSON
$redis->getOption(Redis::OPT_SERIALIZER);
~~~
-### ping
+#### ping
-----
_**Description**_: Check the current connection status.
-##### *Prototype*
+###### *Prototype*
~~~php
$redis->ping([string $message]);
~~~
-##### *Return value*
+###### *Return value*
*Mixed*: This method returns `TRUE` on success, or the passed string if called with an argument.
-##### *Example*
+###### *Example*
~~~php
/* When called without an argument, PING returns `TRUE` */
$redis->ping();
@@ -442,34 +513,34 @@ $redis->ping('hello');
*Note*: Prior to PhpRedis 5.0.0 this command simply returned the string `+PONG`.
-### echo
+#### echo
-----
_**Description**_: Sends a string to Redis, which replies with the same string
-##### *Parameters*
+###### *Parameters*
*STRING*: The message to send.
-##### *Return value*
+###### *Return value*
*STRING*: the same message.
-## Retry and backoff
+### Retry and backoff
1. [Maximum retries](#maximum-retries)
1. [Backoff algorithms](#backoff-algorithms)
-### Maximum retries
-You can set and get the maximum retries upon connection issues using the `OPT_MAX_RETRIES` option. Note that this is the number of _retries_, meaning if you set this option to _n_, there will be a maximum _n+1_ attemps overall. Defaults to 10.
+#### Maximum retries
+You can set and get the maximum retries upon connection issues using the `OPT_MAX_RETRIES` option. Note that this is the number of _retries_, meaning if you set this option to _n_, there will be a maximum _n+1_ attempts overall. Defaults to 10.
-##### *Example*
+###### *Example*
~~~php
$redis->setOption(Redis::OPT_MAX_RETRIES, 5);
$redis->getOption(Redis::OPT_MAX_RETRIES);
~~~
-### Backoff algorithms
+#### Backoff algorithms
You can set the backoff algorithm using the `Redis::OPT_BACKOFF_ALGORITHM` option and choose among the following algorithms described in this blog post by Marc Brooker from AWS: [Exponential Backoff And Jitter](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter):
* Default: `Redis::BACKOFF_ALGORITHM_DEFAULT`
@@ -482,7 +553,7 @@ You can set the backoff algorithm using the `Redis::OPT_BACKOFF_ALGORITHM` optio
These algorithms depend on the _base_ and _cap_ parameters, both in milliseconds, which you can set using the `Redis::OPT_BACKOFF_BASE` and `Redis::OPT_BACKOFF_CAP` options, respectively.
-##### *Example*
+###### *Example*
~~~php
$redis->setOption(Redis::OPT_BACKOFF_ALGORITHM, Redis::BACKOFF_ALGORITHM_DECORRELATED_JITTER);
@@ -490,7 +561,7 @@ $redis->setOption(Redis::OPT_BACKOFF_BASE, 500); // base for backoff computation
$redis->setOption(Redis::OPT_BACKOFF_CAP, 750); // backoff time capped at 750ms
~~~
-## Server
+### Server
1. [acl](#acl) - Manage Redis ACLs
1. [bgRewriteAOF](#bgrewriteaof) - Asynchronously rewrite the append-only file
@@ -502,71 +573,73 @@ $redis->setOption(Redis::OPT_BACKOFF_CAP, 750); // backoff time capped at 750ms
1. [info](#info) - Get information and statistics about the server
1. [lastSave](#lastsave) - Get the timestamp of the last disk save
1. [save](#save) - Synchronously save the dataset to disk (wait to complete)
+1. [wait](#wait) - Block until write acknowledgements from replicas
+1. [waitaof](#waitaof) - Wait for local AOF fsync and replica acknowledgements
1. [slaveOf](#slaveof) - Make the server a slave of another instance, or promote it to master
1. [time](#time) - Return the current server time
1. [slowLog](#slowlog) - Access the Redis slowLog entries
-### acl
+#### acl
-----
_**Description**_: Execute the Redis ACL command.
-##### *Parameters*
-_variable_: Minumum of one argument for `Redis` and two for `RedisCluster`.
+###### *Parameters*
+_variable_: Minimum of one argument for `Redis` and two for `RedisCluster`.
-##### *Example*
+###### *Example*
~~~php
$redis->acl('USERS'); /* Get a list of users */
$redis->acl('LOG'); /* See log of Redis' ACL subsystem */
~~~
-*Note*: In order to user the `ACL` command you must be communicating with Redis >= 6.0 and be logged into an account that has access to administration commands such as ACL. Please reference [this tutorial](https://redis.io/topics/acl) for an overview of Redis 6 ACLs and [the redis command reference](https://redis.io/commands) for every ACL subcommand.
+*Note*: In order to use the `ACL` command you must be communicating with Redis >= 6.0 and be logged into an account that has access to administration commands such as ACL. Please reference [this tutorial](https://redis.io/topics/acl) for an overview of Redis 6 ACLs and [the redis command reference](https://redis.io/commands) for every ACL subcommand.
*Note*: If you are connecting to Redis server >= 4.0.0 you can remove a key with the `unlink` method in the exact same way you would use `del`. The Redis [unlink](https://redis.io/commands/unlink) command is non-blocking and will perform the actual deletion asynchronously.
-### bgRewriteAOF
+#### bgRewriteAOF
-----
_**Description**_: Start the background rewrite of AOF (Append-Only File)
-##### *Parameters*
+###### *Parameters*
None.
-##### *Return value*
+###### *Return value*
*BOOL*: `TRUE` in case of success, `FALSE` in case of failure.
-##### *Example*
+###### *Example*
~~~php
$redis->bgRewriteAOF();
~~~
-### bgSave
+#### bgSave
-----
_**Description**_: Asynchronously save the dataset to disk (in background)
-##### *Parameters*
+###### *Parameters*
None.
-##### *Return value*
+###### *Return value*
*BOOL*: `TRUE` in case of success, `FALSE` in case of failure. If a save is already running, this command will fail and return `FALSE`.
-##### *Example*
+###### *Example*
~~~php
$redis->bgSave();
~~~
-### config
+#### config
-----
_**Description**_: Get or Set the Redis server configuration parameters.
-##### *Prototype*
+###### *Prototype*
~~~php
$redis->config(string $operation, string|array|null $key = NULL, ?string $value = NULL): mixed;
~~~
-##### *Return value*
-*Associative array* for `GET`, key(s) -> value(s)
+###### *Return value*
+*Associative array* for `GET`, key(s) -> value(s)
*bool* for `SET`, `RESETSTAT`, and `REWRITE`
-##### *Examples*
+###### *Examples*
~~~php
$redis->config("GET", "*max-*-entries*");
$redis->config("SET", ['timeout', 'loglevel']);
@@ -575,55 +648,55 @@ $redis->config("SET", ['timeout' => 128, 'loglevel' => 'warning']);
$redis->config('RESETSTAT');
~~~
-### dbSize
+#### dbSize
-----
_**Description**_: Return the number of keys in selected database.
-##### *Parameters*
+###### *Parameters*
None.
-##### *Return value*
+###### *Return value*
*INTEGER*: DB size, in number of keys.
-##### *Example*
+###### *Example*
~~~php
$count = $redis->dbSize();
echo "Redis has $count keys\n";
~~~
-### flushAll
+#### flushAll
-----
_**Description**_: Remove all keys from all databases.
-##### *Parameters*
+###### *Parameters*
*async* (bool) requires server version 4.0.0 or greater
-##### *Return value*
+###### *Return value*
*BOOL*: Always `TRUE`.
-##### *Example*
+###### *Example*
~~~php
$redis->flushAll();
~~~
-### flushDb
+#### flushDb
-----
_**Description**_: Remove all keys from the current database.
-##### *Prototype*
+###### *Prototype*
~~~php
$redis->flushdb(?bool $sync = NULL): Redis|bool;
~~~
-##### *Return value*
+###### *Return value*
*BOOL*: This command returns true on success and false on failure.
-##### *Example*
+###### *Example*
~~~php
$redis->flushDb();
~~~
-### info
+#### info
-----
_**Description**_: Get information and statistics about the server
@@ -647,96 +720,138 @@ INFO will call the standard REDIS INFO command, which returns information such a
You can pass a variety of options to INFO ([per the Redis documentation](http://redis.io/commands/info)),
which will modify what is returned.
-##### *Parameters*
+###### *Parameters*
*option*: The option to provide redis (e.g. "COMMANDSTATS", "CPU")
-##### *Example*
+###### *Example*
~~~php
$redis->info(); /* standard redis INFO command */
$redis->info("COMMANDSTATS"); /* Information on the commands that have been run (>=2.6 only)
$redis->info("CPU"); /* just CPU information from Redis INFO */
~~~
-### lastSave
+#### lastSave
-----
_**Description**_: Returns the timestamp of the last disk save.
-##### *Parameters*
+###### *Parameters*
None.
-##### *Return value*
+###### *Return value*
*INT*: timestamp.
-##### *Example*
+###### *Example*
~~~php
$redis->lastSave();
~~~
-### save
+#### save
-----
_**Description**_: Synchronously save the dataset to disk (wait to complete)
-##### *Parameters*
+###### *Parameters*
None.
-##### *Return value*
+###### *Return value*
*BOOL*: `TRUE` in case of success, `FALSE` in case of failure. If a save is already running, this command will fail and return `FALSE`.
-##### *Example*
+###### *Example*
~~~php
$redis->save();
~~~
-### slaveOf
+#### wait
+-----
+_**Description**_: Block the client until a specified number of replicas acknowledge the most recent write or until the timeout elapses.
+
+###### *Parameters*
+*numreplicas* (int): The number of replicas that must confirm the write.
+*timeout* (int): Maximum time to wait in milliseconds (`0` to wait indefinitely).
+
+###### *Return value*
+*INT*: The number of replicas that acknowledged the write before timing out, or `FALSE` on error.
+
+###### *Example*
+~~~php
+$redis->set('user:1', 'marco');
+$confirmed = $redis->wait(1, 500);
+
+if ($confirmed < 1) {
+ // Handle the case where the write was not replicated in time.
+}
+~~~
+
+#### waitaof
+-----
+_**Description**_: Block until Redis has durably written recent changes to the local AOF file the requested number of times and received acknowledgements from the requested number of replicas (Redis >= 7.2).
+
+###### *Parameters*
+*numlocal* (int): Minimum number of local AOF fsync operations to wait for.
+*numreplicas* (int): Number of replicas that must acknowledge the write.
+*timeout* (int): Maximum time to wait in milliseconds (`0` to wait indefinitely).
+
+###### *Return value*
+*ARRAY*: Two integers, where element `0` is the number of local fsync operations performed and element `1` is the number of replica acknowledgements, or `FALSE` on error.
+
+###### *Example*
+~~~php
+[$local, $replicas] = $redis->waitaof(1, 1, 1000);
+
+if ($local < 1 || $replicas < 1) {
+ // The write was not persisted or replicated as requested.
+}
+~~~
+
+#### slaveOf
-----
_**Description**_: Changes the slave status
-##### *Parameters*
+###### *Parameters*
Either host (string) and port (int), or no parameter to stop being a slave.
-##### *Return value*
+###### *Return value*
*BOOL*: `TRUE` in case of success, `FALSE` in case of failure.
-##### *Example*
+###### *Example*
~~~php
$redis->slaveOf('10.0.1.7', 6379);
/* ... */
$redis->slaveOf();
~~~
-### time
+#### time
-----
_**Description**_: Return the current server time.
-##### *Parameters*
+###### *Parameters*
(none)
-##### *Return value*
+###### *Return value*
If successful, the time will come back as an associative array with element zero being
the unix timestamp, and element one being microseconds.
-##### *Examples*
+###### *Examples*
~~~php
$redis->time();
~~~
-### slowLog
+#### slowLog
-----
_**Description**_: Access the Redis slowLog
-##### *Parameters*
-*Operation* (string): This can be either `GET`, `LEN`, or `RESET`
+###### *Parameters*
+*Operation* (string): This can be either `GET`, `LEN`, or `RESET`
*Length* (integer), optional: If executing a `SLOWLOG GET` command, you can pass an optional length.
#####
-##### *Return value*
+###### *Return value*
The return value of SLOWLOG will depend on which operation was performed.
SLOWLOG GET: Array of slowLog entries, as provided by Redis
SLOGLOG LEN: Integer, the length of the slowLog
SLOWLOG RESET: Boolean, depending on success
#####
-##### *Examples*
+###### *Examples*
~~~php
// Get ten slowLog entries
$redis->slowLog('get', 10);
@@ -750,9 +865,9 @@ $redis->slowLog('reset');
$redis->slowLog('len');
~~~
-## Keys and Strings
+### Keys and Strings
-### Strings
+#### Strings
-----
* [append](#append) - Append a value to a key
@@ -760,12 +875,13 @@ $redis->slowLog('len');
* [bitOp](#bitop) - Perform bitwise operations between strings
* [decr, decrBy](#decr-decrby) - Decrement the value of a key
* [get](#get) - Get the value of a key
+* [getEx](#getex) - Get the value of a key and set its expiration
* [getBit](#getbit) - Returns the bit value at offset in the string value stored at key
* [getRange](#getrange) - Get a substring of the string stored at a key
* [getSet](#getset) - Set the string value of a key and return its old value
* [incr, incrBy](#incr-incrby) - Increment the value of a key
* [incrByFloat](#incrbyfloat) - Increment the float value of a key by the given amount
-* [mGet, getMultiple](#mget-getmultiple) - Get the values of all the given keys
+* [mGet](#mget) - Get the values of all the given keys
* [mSet, mSetNX](#mset-msetnx) - Set multiple keys to multiple values
* [set](#set) - Set the string value of a key
* [setBit](#setbit) - Sets or clears the bit at offset in the string value stored at key
@@ -774,22 +890,22 @@ $redis->slowLog('len');
* [setRange](#setrange) - Overwrite part of a string at key starting at the specified offset
* [strLen](#strlen) - Get the length of the value stored in a key
-### Keys
+#### Keys
-----
* [del, delete, unlink](#del-delete-unlink) - Delete a key
* [dump](#dump) - Return a serialized version of the value stored at the specified key.
* [exists](#exists) - Determine if a key exists
-* [expire, setTimeout, pexpire](#expire-settimeout-pexpire) - Set a key's time to live in seconds
+* [expire, pexpire](#expire-pexpire) - Set a key's time to live in seconds
* [expireAt, pexpireAt](#expireat-pexpireat) - Set the expiration for a key as a UNIX timestamp
-* [keys, getKeys](#keys-getkeys) - Find all keys matching the given pattern
+* [keys](#keys-1) - Find all keys matching the given pattern
* [scan](#scan) - Scan for keys in the keyspace (Redis >= 2.8.0)
* [migrate](#migrate) - Atomically transfer a key from a Redis instance to another one
* [move](#move) - Move a key to another database
* [object](#object) - Inspect the internals of Redis objects
* [persist](#persist) - Remove the expiration from a key
* [randomKey](#randomkey) - Return a random key from the keyspace
-* [rename, renameKey](#rename-renamekey) - Rename a key
+* [rename](#rename) - Rename a key
* [renameNx](#renamenx) - Rename a key, only if the new key does not exist
* [type](#type) - Determine the type stored at key
* [sort](#sort) - Sort the elements in a list, set or sorted set
@@ -798,35 +914,57 @@ $redis->slowLog('len');
-----
-### get
+#### get
-----
_**Description**_: Get the value related to the specified key
-##### *Parameters*
+###### *Parameters*
*key*
-##### *Return value*
-*String* or *Bool*: If key didn't exist, `FALSE` is returned. Otherwise, the value related to this key is returned.
+###### *Return value*
+*String* or *Bool*: If key doesn't exist, `FALSE` is returned. Otherwise, the value related to this key is returned.
-##### *Examples*
+###### *Examples*
~~~php
$redis->get('key');
~~~
-### set
+#### getEx
+-----
+_**Description**_: Get the value related to the specified key and set its expiration
+
+###### *Parameters*
+*key*
+*options array* (optional) with the following keys:
+ * `EX` - expire time in seconds
+ * `PX` - expire time in milliseconds
+ * `EXAT` - expire time in seconds since UNIX epoch
+ * `PXAT` - expire time in milliseconds since UNIX epoch
+ * `PERSIST` - remove the expiration from the key
+
+###### *Return value*
+*String* or *Bool*: If key doesn't exist, `FALSE` is returned. Otherwise, the value related to this key is returned.
+
+###### *Examples*
+
+~~~php
+$redis->getEx('key', ['EX' => 10]); // get key and set its expiration to 10 seconds
+~~~
+
+#### set
-----
-_**Description**_: Set the string value in argument as value of the key. If you're using Redis >= 2.6.12, you can pass extended options as explained below
+_**Description**_: Set the string value in argument as value of the key. If you're using Redis >= 2.6.12, you can pass extended options as explained below
-##### *Parameters*
-*Key*
-*Value*
+###### *Parameters*
+*Key*
+*Value*
*Timeout or Options Array* (optional). If you pass an integer, phpredis will redirect to SETEX, and will try to use Redis >= 2.6.12 extended options if you pass an array with valid values
-##### *Return value*
+###### *Return value*
*Bool* `TRUE` if the command is successful.
-##### *Examples*
+###### *Examples*
~~~php
// Simple key -> value set
$redis->set('key', 'value');
@@ -842,55 +980,55 @@ $redis->set('key', 'value', ['xx', 'px'=>1000]);
~~~
-### setEx, pSetEx
+#### setEx, pSetEx
-----
_**Description**_: Set the string value in argument as value of the key, with a time to live. PSETEX uses a TTL in milliseconds.
-##### *Parameters*
+###### *Parameters*
*Key*
*TTL*
*Value*
-##### *Return value*
-*Bool* `TRUE` if the command is successful.
+###### *Return value*
+*Bool* `TRUE` if the command is successful, `FALSE` in case of failure.
-##### *Examples*
+###### *Examples*
~~~php
$redis->setEx('key', 3600, 'value'); // sets key → value, with 1h TTL.
$redis->pSetEx('key', 100, 'value'); // sets key → value, with 0.1 sec TTL.
~~~
-### setNx
+#### setNx
-----
_**Description**_: Set the string value in argument as value of the key if the key doesn't already exist in the database.
-##### *Parameters*
-*key*
-*value*
+###### *Parameters*
+*Key*
+*Value*
-##### *Return value*
-*Bool* `TRUE` in case of success, `FALSE` in case of failure.
+###### *Return value*
+*Bool* `TRUE` if the command is successful, `FALSE` in case of failure.
-##### *Examples*
+###### *Examples*
~~~php
$redis->setNx('key', 'value'); /* return TRUE */
$redis->setNx('key', 'value'); /* return FALSE */
~~~
-### del, delete, unlink
+#### del, delete, unlink
-----
_**Description**_: Remove specified keys.
-##### *Parameters*
+###### *Parameters*
An array of keys, or an undefined number of parameters, each a key: *key1* *key2* *key3* ... *keyN*
*Note*: If you are connecting to Redis server >= 4.0.0 you can remove a key with the `unlink` method in the exact same way you would use `del`. The Redis [unlink](https://redis.io/commands/unlink) command is non-blocking and will perform the actual deletion asynchronously.
-##### *Return value*
-*Long* Number of keys deleted.
+###### *Return value*
+*Long* Number of keys deleted (`0` if none existed to start with), `FALSE` in case of unexpected failure (i.e. connection, etc.)
-##### *Examples*
+###### *Examples*
~~~php
$redis->set('key1', 'val1');
$redis->set('key2', 'val2');
@@ -907,17 +1045,17 @@ $redis->unlink(['key1', 'key2']);
**Note:** `delete` is an alias for `del` and will be removed in future versions of phpredis.
-### exists
+#### exists
-----
_**Description**_: Verify if the specified key exists.
-##### *Parameters*
+###### *Parameters*
*key*
-##### *Return value*
-*long*: The number of keys tested that do exist.
+###### *Return value*
+*Long* Number of keys tested that exist (`0` if none do), `FALSE` in case of failure.
-##### *Examples*
+###### *Examples*
~~~php
$redis->set('key', 'value');
$redis->exists('key'); /* 1 */
@@ -928,20 +1066,20 @@ $redis->exists(['foo', 'bar', 'baz']); /* 3 */
$redis->exists('foo', 'bar', 'baz'); /* 3 */
~~~
-**Note**: This function took a single argument and returned TRUE or FALSE in phpredis versions < 4.0.0.
+**Note**: This function took a single argument and returned TRUE or FALSE incr('key1'); /* key1 didn't exists, set to 0 before the increment */
/* and now has the value 1 */
@@ -956,18 +1094,18 @@ $redis->incr('key1', 10); /* 14 */
$redis->incrBy('key1', 10); /* 24 */
~~~
-### incrByFloat
+#### incrByFloat
-----
_**Description**_: Increment the key with floating point precision.
-##### *Parameters*
-*key*
+###### *Parameters*
+*key*
*value*: (float) value that will be added to the key
-##### *Return value*
+###### *Return value*
*FLOAT* the new value
-##### *Examples*
+###### *Examples*
~~~php
$redis->incrByFloat('key1', 1.5); /* key1 didn't exist, so it will now be 1.5 */
@@ -977,18 +1115,18 @@ $redis->incrByFloat('key1', -1.5); /* 1.5 */
$redis->incrByFloat('key1', 2.5); /* 4 */
~~~
-### decr, decrBy
+#### decr, decrBy
-----
_**Description**_: Decrement the number stored at key by one. If the second argument is filled, it will be used as the integer value of the decrement.
-##### *Parameters*
-*key*
+###### *Parameters*
+*key*
*value*: value that will be subtracted to key (only for decrBy)
-##### *Return value*
+###### *Return value*
*INT* the new value
-##### *Examples*
+###### *Examples*
~~~php
$redis->decr('key1'); /* key1 didn't exists, set to 0 before the increment */
/* and now has the value -1 */
@@ -1002,17 +1140,17 @@ $redis->decr('key1', 10); /* -13 */
$redis->decrBy('key1', 10); /* -23 */
~~~
-### mGet, getMultiple
+#### mGet
-----
_**Description**_: Get the values of all the specified keys. If one or more keys don't exist, the array will contain `FALSE` at the position of the key.
-##### *Parameters*
+###### *Parameters*
*Array*: Array containing the list of the keys
-##### *Return value*
+###### *Return value*
*Array*: Array containing the values related to keys in argument
-##### *Examples*
+###### *Examples*
~~~php
$redis->set('key1', 'value1');
$redis->set('key2', 'value2');
@@ -1021,52 +1159,50 @@ $redis->mGet(['key1', 'key2', 'key3']); /* ['value1', 'value2', 'value3'];
$redis->mGet(['key0', 'key1', 'key5']); /* [`FALSE`, 'value1', `FALSE`];
~~~
-**Note:** `getMultiple` is an alias for `mGet` and will be removed in future versions of phpredis.
-
-### getSet
+#### getSet
-----
_**Description**_: Sets a value and returns the previous entry at that key.
-##### *Parameters*
+###### *Parameters*
*Key*: key
*STRING*: value
-##### *Return value*
+###### *Return value*
A string, the previous value located at this key.
-##### *Example*
+###### *Example*
~~~php
$redis->set('x', '42');
$exValue = $redis->getSet('x', 'lol'); // return '42', replaces x by 'lol'
-$newValue = $redis->get('x')' // return 'lol'
+$newValue = $redis->get('x'); // return 'lol'
~~~
-### randomKey
+#### randomKey
-----
_**Description**_: Returns a random key.
-##### *Parameters*
+###### *Parameters*
None.
-##### *Return value*
+###### *Return value*
*STRING*: an existing key in redis.
-##### *Example*
+###### *Example*
~~~php
$key = $redis->randomKey();
$surprise = $redis->get($key); // who knows what's in there.
~~~
-### move
+#### move
-----
_**Description**_: Moves a key to a different database.
-##### *Parameters*
+###### *Parameters*
*Key*: key, the key to move.
*INTEGER*: dbindex, the database number to move the key to.
-##### *Return value*
+###### *Return value*
*BOOL*: `TRUE` in case of success, `FALSE` in case of failure.
-##### *Example*
+###### *Example*
~~~php
$redis->select(0); // switch to DB 0
@@ -1076,17 +1212,17 @@ $redis->select(1); // switch to DB 1
$redis->get('x'); // will return 42
~~~
-### rename, renameKey
+#### rename
-----
_**Description**_: Renames a key.
-##### *Parameters*
+###### *Parameters*
*STRING*: srckey, the key to rename.
*STRING*: dstkey, the new name for the key.
-##### *Return value*
+###### *Return value*
*BOOL*: `TRUE` in case of success, `FALSE` in case of failure.
-##### *Example*
+###### *Example*
~~~php
$redis->set('x', '42');
$redis->rename('x', 'y');
@@ -1094,25 +1230,23 @@ $redis->get('y'); // → 42
$redis->get('x'); // → `FALSE`
~~~
-**Note:** `renameKey` is an alias for `rename` and will be removed in future versions of phpredis.
-
-### renameNx
+#### renameNx
-----
_**Description**_: Same as rename, but will not replace a key if the destination already exists. This is the same behaviour as setNx.
-### expire, pexpire
+#### expire, pexpire
-----
_**Description**_: Sets an expiration on a key in either seconds or milliseconds.
-##### *Prototype*
+###### *Prototype*
~~~php
public function expire(string $key, int $seconds, ?string $mode = NULL): Redis|bool;
public function pexpire(string $key, int $milliseconds, ?string $mode = NULL): Redis|bool;
~~~
-##### *Return value*
+###### *Return value*
*BOOL*: `TRUE` if an expiration was set, and `FALSE` on failure or if one was not set. You can distinguish between an error and an expiration not being set by checking `getLastError()`.
-##### *Example*
+###### *Example*
~~~php
$redis->set('x', '42');
$redis->expire('x', 3); // x will disappear in 3 seconds.
@@ -1120,22 +1254,20 @@ sleep(5); // wait 5 seconds
$redis->get('x'); // will return `FALSE`, as 'x' has expired.
~~~
-**Note:** `setTimeout` is an alias for `expire` and will be removed in future versions of phpredis.
-
-### expireAt, pexpireAt
+#### expireAt, pexpireAt
-----
-_**Description**_: Seta specific timestamp for a key to expire in seconds or milliseconds.
+_**Description**_: Set a specific timestamp for a key to expire in seconds or milliseconds.
-##### *Prototype*
+###### *Prototype*
~~~php
public function expireat(string $key, int $unix_timestamp, ?string $mode = NULL): Redis|bool;
public function pexpireat(string $key, int $unix_timestamp_millis, ?string $mode = NULL): Redis|bool;
~~~
-##### *Return value*
-*BOOL*: `TRUE` if an expiration was set and `FALSE` if one was not set or in the event on an error. You can detect an actual error by checking `getLastError()`.
+###### *Return value*
+*BOOL*: `TRUE` if an expiration was set and `FALSE` if one was not set or in the event of an error. You can detect an actual error by checking `getLastError()`.
-##### *Example*
+###### *Example*
~~~php
$redis->set('x', '42');
$redis->expireAt('x', time(NULL) + 3); // x will disappear in 3 seconds.
@@ -1143,39 +1275,37 @@ sleep(5); // wait 5 seconds
$redis->get('x'); // will return `FALSE`, as 'x' has expired.
~~~
-### keys, getKeys
+#### keys
-----
_**Description**_: Returns the keys that match a certain pattern.
-##### *Parameters*
+###### *Parameters*
*STRING*: pattern, using '*' as a wildcard.
-##### *Return value*
+###### *Return value*
*Array of STRING*: The keys that match a certain pattern.
-##### *Example*
+###### *Example*
~~~php
$allKeys = $redis->keys('*'); // all keys will match this.
$keyWithUserPrefix = $redis->keys('user*');
~~~
-**Note:** `getKeys` is an alias for `keys` and will be removed in future versions of phpredis.
-
-### scan
+#### scan
-----
_**Description**_: Scan the keyspace for keys
-##### *Parameters*
+###### *Parameters*
*LONG (reference)*: Iterator, initialized to NULL
*STRING, Optional*: Pattern to match
*LONG, Optional*: Count of keys per iteration (only a suggestion to Redis)
-##### *Return value*
-*Array, boolean*: This function will return an array of keys or FALSE if Redis returned zero keys
+###### *Return value*
+*Array, boolean*: This function will return an array of keys or FALSE if Redis returns zero keys
*Note*: SCAN is a "directed node" command in [RedisCluster](cluster.md#directed-node-commands)
-##### *Example*
+###### *Example*
~~~php
/* Without enabling Redis::SCAN_RETRY (default condition) */
@@ -1207,154 +1337,152 @@ while ($arr_keys = $redis->scan($it)) {
echo "No more keys to scan!\n";
~~~
-### object
+#### object
-----
_**Description**_: Describes the object pointed to by a key.
-##### *Parameters*
+###### *Parameters*
The information to retrieve (string) and the key (string). Info can be one of the following:
* "encoding"
* "refcount"
* "idletime"
-##### *Return value*
+###### *Return value*
*STRING* for "encoding", *LONG* for "refcount" and "idletime", `FALSE` if the key doesn't exist.
-##### *Example*
+###### *Example*
~~~php
$redis->object("encoding", "l"); // → ziplist
$redis->object("refcount", "l"); // → 1
$redis->object("idletime", "l"); // → 400 (in seconds, with a precision of 10 seconds).
~~~
-### type
+#### type
-----
_**Description**_: Returns the type of data pointed by a given key.
-##### *Parameters*
+###### *Parameters*
*Key*: key
-##### *Return value*
+###### *Return value*
-Depending on the type of the data pointed by the key, this method will return the following value:
-string: Redis::REDIS_STRING
-set: Redis::REDIS_SET
-list: Redis::REDIS_LIST
-zset: Redis::REDIS_ZSET
-hash: Redis::REDIS_HASH
+Depending on the type of the data pointed by the key, this method will return the following value:
+string: Redis::REDIS_STRING
+set: Redis::REDIS_SET
+list: Redis::REDIS_LIST
+zset: Redis::REDIS_ZSET
+hash: Redis::REDIS_HASH
other: Redis::REDIS_NOT_FOUND
-##### *Example*
+###### *Example*
~~~php
$redis->type('key');
~~~
-### append
+#### append
-----
_**Description**_: Append specified string to the string stored in specified key.
-##### *Parameters*
+###### *Parameters*
*Key*
*Value*
-##### *Return value*
+###### *Return value*
*INTEGER*: Size of the value after the append
-##### *Example*
+###### *Example*
~~~php
$redis->set('key', 'value1');
$redis->append('key', 'value2'); /* 12 */
$redis->get('key'); /* 'value1value2' */
~~~
-### getRange
+#### getRange
-----
_**Description**_: Return a substring of a larger string
-##### *Parameters*
-*key*
-*start*
+###### *Parameters*
+*key*
+*start*
*end*
-##### *Return value*
+###### *Return value*
*STRING*: the substring
-##### *Example*
+###### *Example*
~~~php
$redis->set('key', 'string value');
$redis->getRange('key', 0, 5); /* 'string' */
$redis->getRange('key', -5, -1); /* 'value' */
~~~
-**Note**: `substr` is an alias for `getRange` and will be removed in future versions of phpredis.
-
-### setRange
+#### setRange
-----
_**Description**_: Changes a substring of a larger string.
-##### *Parameters*
+###### *Parameters*
*key*
*offset*
*value*
-##### *Return value*
+###### *Return value*
*STRING*: the length of the string after it was modified.
-##### *Example*
+###### *Example*
~~~php
$redis->set('key', 'Hello world');
$redis->setRange('key', 6, "redis"); /* returns 11 */
$redis->get('key'); /* "Hello redis" */
~~~
-### strLen
+#### strLen
-----
_**Description**_: Get the length of a string value.
-##### *Parameters*
+###### *Parameters*
*key*
-##### *Return value*
+###### *Return value*
*INTEGER*
-##### *Example*
+###### *Example*
~~~php
$redis->set('key', 'value');
$redis->strlen('key'); /* 5 */
~~~
-### getBit
+#### getBit
-----
_**Description**_: Return a single bit out of a larger string
-##### *Parameters*
-*key*
+###### *Parameters*
+*key*
*offset*
-##### *Return value*
+###### *Return value*
*LONG*: the bit value (0 or 1)
-##### *Example*
+###### *Example*
~~~php
$redis->set('key', "\x7f"); // this is 0111 1111
$redis->getBit('key', 0); /* 0 */
$redis->getBit('key', 1); /* 1 */
~~~
-### setBit
+#### setBit
-----
_**Description**_: Changes a single bit of a string.
-##### *Parameters*
-*key*
-*offset*
+###### *Parameters*
+*key*
+*offset*
*value*: bool or int (1 or 0)
-##### *Return value*
+###### *Return value*
*LONG*: 0 or 1, the value of the bit before it was set.
-##### *Example*
+###### *Example*
~~~php
$redis->set('key', "*"); // ord("*") = 42 = 0x2f = "0010 1010"
$redis->setBit('key', 5, 1); /* returns 0 */
@@ -1362,34 +1490,34 @@ $redis->setBit('key', 7, 1); /* returns 0 */
$redis->get('key'); /* chr(0x2f) = "/" = b("0010 1111") */
~~~
-### bitOp
+#### bitOp
-----
_**Description**_: Bitwise operation on multiple keys.
-##### *Parameters*
-*operation*: either "AND", "OR", "NOT", "XOR"
-*ret_key*: return key
-*key1*
+###### *Parameters*
+*operation*: either "AND", "OR", "NOT", "XOR"
+*ret_key*: return key
+*key1*
*key2...*
-##### *Return value*
+###### *Return value*
*LONG*: The size of the string stored in the destination key.
-### bitCount
+#### bitCount
-----
_**Description**_: Count bits in a string.
-##### *Parameters*
+###### *Parameters*
*key*
-##### *Return value*
+###### *Return value*
*LONG*: The number of bits set to 1 in the value behind the input key.
-### sort
+#### sort
-----
_**Description**_: Sort the elements in a list, set or sorted set.
-##### *Parameters*
+###### *Parameters*
*Key*: key
*Options*: [key => value, ...] - optional, with the following keys and values:
~~~
@@ -1400,10 +1528,10 @@ _**Description**_: Sort the elements in a list, set or sorted set.
'alpha' => TRUE,
'store' => 'external-key'
~~~
-##### *Return value*
+###### *Return value*
An array of values, or a number corresponding to the number of elements stored if that was used.
-##### *Example*
+###### *Example*
~~~php
$redis->del('s');
$redis->sAdd('s', 5);
@@ -1420,47 +1548,47 @@ var_dump($redis->sort('s', ['sort' => 'desc', 'store' => 'out'])); // (int)5
-### ttl, pttl
+#### ttl, pttl
-----
_**Description**_: Returns the time to live left for a given key in seconds (ttl), or milliseconds (pttl).
-##### *Parameters*
+###### *Parameters*
*Key*: key
-##### *Return value*
-*LONG*: The time to live in seconds. If the key has no ttl, `-1` will be returned, and `-2` if the key doesn't exist.
+###### *Return value*
+*LONG*: The time to live in seconds. If the key has no ttl, `-1` will be returned, and `-2` if the key doesn't exist.
-##### *Example*
+###### *Example*
~~~php
$redis->ttl('key');
~~~
-### persist
+#### persist
-----
_**Description**_: Remove the expiration timer from a key.
-##### *Parameters*
+###### *Parameters*
*Key*: key
-##### *Return value*
+###### *Return value*
*BOOL*: `TRUE` if a timeout was removed, `FALSE` if the key didn’t exist or didn’t have an expiration timer.
-##### *Example*
+###### *Example*
~~~php
$redis->persist('key');
~~~
-### mSet, mSetNx
+#### mSet, mSetNx
-----
_**Description**_: Sets multiple key-value pairs in one atomic command. MSETNX only returns TRUE if all the keys were set (see SETNX).
-##### *Parameters*
+###### *Parameters*
*Pairs*: [key => value, ...]
-##### *Return value*
+###### *Return value*
*Bool* `TRUE` in case of success, `FALSE` in case of failure.
-##### *Example*
+###### *Example*
~~~php
$redis->mSet(['key0' => 'value0', 'key1' => 'value1']);
@@ -1476,50 +1604,50 @@ string(6) "value1"
-### dump
+#### dump
-----
_**Description**_: Dump a key out of a redis database, the value of which can later be passed into redis using the RESTORE command. The data
that comes out of DUMP is a binary representation of the key as Redis stores it.
-##### *Parameters*
+###### *Parameters*
*key* string
-##### *Return value*
+###### *Return value*
The Redis encoded value of the key, or FALSE if the key doesn't exist
-##### *Examples*
+###### *Examples*
~~~php
$redis->set('foo', 'bar');
$val = $redis->dump('foo'); // $val will be the Redis encoded key value
~~~
-### restore
+#### restore
-----
_**Description**_: Restore a key from the result of a DUMP operation.
-##### *Parameters*
-*key* string. The key name
-*ttl* integer. How long the key should live (if zero, no expire will be set on the key)
+###### *Parameters*
+*key* string. The key name
+*ttl* integer. How long the key should live (if zero, no expire will be set on the key)
*value* string (binary). The Redis encoded key value (from DUMP)
-##### *Examples*
+###### *Examples*
~~~php
$redis->set('foo', 'bar');
$val = $redis->dump('foo');
$redis->restore('bar', 0, $val); // The key 'bar', will now be equal to the key 'foo'
~~~
-### migrate
+#### migrate
-----
_**Description**_: Migrates a key to a different Redis instance.
**Note:**: Redis introduced migrating multiple keys in 3.0.6, so you must have at least
-that version in order to call `migrate` with an array of keys.
-
-##### *Parameters*
-*host* string. The destination host
-*port* integer. The TCP port to connect to.
-*key(s)* string or array.
-*destination-db* integer. The target DB.
-*timeout* integer. The maximum amount of time given to this transfer.
-*copy* boolean, optional. Should we send the COPY flag to redis.
-*replace* boolean, optional. Should we send the REPLACE flag to redis
-##### *Examples*
+that version to call `migrate` with an array of keys.
+
+###### *Parameters*
+*host* string. The destination host
+*port* integer. The TCP port to connect to.
+*key(s)* string or array.
+*destination-db* integer. The target DB.
+*timeout* integer. The maximum amount of time given to this transfer.
+*copy* boolean, optional. Should we send the COPY flag to redis.
+*replace* boolean, optional. Should we send the REPLACE flag to redis
+###### *Examples*
~~~php
$redis->migrate('backup', 6379, 'foo', 0, 3600);
$redis->migrate('backup', 6379, 'foo', 0, 3600, true, true); /* copy and replace */
@@ -1531,7 +1659,7 @@ $redis->migrate('backup', 6379, ['key1', 'key2', 'key3'], 0, 3600);
-## Hashes
+### Hashes
* [hDel](#hdel) - Delete one or more hash fields
* [hExists](#hexists) - Determine if a hash field exists
@@ -1549,17 +1677,17 @@ $redis->migrate('backup', 6379, ['key1', 'key2', 'key3'], 0, 3600);
* [hScan](#hscan) - Scan a hash key for members
* [hStrLen](#hstrlen) - Get the string length of the value associated with field in the hash
-### hSet
+#### hSet
-----
_**Description**_: Adds a value to the hash stored at key.
-##### *Parameters*
-*key*
-*hashKey*
+###### *Parameters*
+*key*
+*hashKey*
*value*
-##### *Return value*
+###### *Return value*
*LONG* `1` if value didn't exist and was added successfully, `0` if the value was already present and was replaced, `FALSE` if there was an error.
-##### *Example*
+###### *Example*
~~~php
$redis->del('h')
$redis->hSet('h', 'key1', 'hello'); /* 1, 'key1' => 'hello' in the hash at "h" */
@@ -1569,14 +1697,14 @@ $redis->hSet('h', 'key1', 'plop'); /* 0, value was replaced. */
$redis->hGet('h', 'key1'); /* returns "plop" */
~~~
-### hSetNx
+#### hSetNx
-----
_**Description**_: Adds a value to the hash stored at key only if this field isn't already in the hash.
-##### *Return value*
+###### *Return value*
*BOOL* `TRUE` if the field was set, `FALSE` if it was already present.
-##### *Example*
+###### *Example*
~~~php
$redis->del('h')
$redis->hSetNx('h', 'key1', 'hello'); /* TRUE, 'key1' => 'hello' in the hash at "h" */
@@ -1584,27 +1712,27 @@ $redis->hSetNx('h', 'key1', 'world'); /* FALSE, 'key1' => 'hello' in the hash at
~~~
-### hGet
+#### hGet
-----
_**Description**_: Gets a value from the hash stored at key. If the hash table doesn't exist, or the key doesn't exist, `FALSE` is returned.
-##### *Parameters*
-*key*
+###### *Parameters*
+*key*
*hashKey*
-##### *Return value*
-*STRING* The value, if the command executed successfully
+###### *Return value*
+*STRING* The value, if the command executed successfully
*BOOL* `FALSE` in case of failure
-### hLen
+#### hLen
-----
_**Description**_: Returns the length of a hash, in number of items
-##### *Parameters*
+###### *Parameters*
*key*
-##### *Return value*
+###### *Return value*
*LONG* the number of items in a hash, `FALSE` if the key doesn't exist or isn't a hash.
-##### *Example*
+###### *Example*
~~~php
$redis->del('h')
$redis->hSet('h', 'key1', 'hello');
@@ -1612,30 +1740,30 @@ $redis->hSet('h', 'key2', 'plop');
$redis->hLen('h'); /* returns 2 */
~~~
-### hDel
+#### hDel
-----
_**Description**_: Removes a value from the hash stored at key. If the hash table doesn't exist, or the key doesn't exist, `FALSE` is returned.
-##### *Parameters*
-*key*
-*hashKey1*
-*hashKey2*
+###### *Parameters*
+*key*
+*hashKey1*
+*hashKey2*
...
-##### *Return value*
+###### *Return value*
*LONG* the number of deleted keys, 0 if the key doesn't exist, `FALSE` if the key isn't a hash.
-### hKeys
+#### hKeys
-----
_**Description**_: Returns the keys in a hash, as an array of strings.
-##### *Parameters*
+###### *Parameters*
*Key*: key
-##### *Return value*
+###### *Return value*
An array of elements, the keys of the hash. This works like PHP's array_keys().
-##### *Example*
+###### *Example*
~~~php
$redis->del('h');
$redis->hSet('h', 'a', 'x');
@@ -1660,17 +1788,17 @@ array(4) {
~~~
The order is random and corresponds to redis' own internal representation of the set structure.
-### hVals
+#### hVals
-----
_**Description**_: Returns the values in a hash, as an array of strings.
-##### *Parameters*
+###### *Parameters*
*Key*: key
-##### *Return value*
+###### *Return value*
An array of elements, the values of the hash. This works like PHP's array_values().
-##### *Example*
+###### *Example*
~~~php
$redis->del('h');
$redis->hSet('h', 'a', 'x');
@@ -1695,17 +1823,17 @@ array(4) {
~~~
The order is random and corresponds to redis' own internal representation of the set structure.
-### hGetAll
+#### hGetAll
-----
_**Description**_: Returns the whole hash, as an array of strings indexed by strings.
-##### *Parameters*
+###### *Parameters*
*Key*: key
-##### *Return value*
+###### *Return value*
An array of elements, the contents of the hash.
-##### *Example*
+###### *Example*
~~~php
$redis->del('h');
$redis->hSet('h', 'a', 'x');
@@ -1730,47 +1858,47 @@ array(4) {
~~~
The order is random and corresponds to redis' own internal representation of the set structure.
-### hExists
+#### hExists
-----
_**Description**_: Verify if the specified member exists in a key.
-##### *Parameters*
-*key*
+###### *Parameters*
+*key*
*memberKey*
-##### *Return value*
+###### *Return value*
*BOOL*: If the member exists in the hash table, return `TRUE`, otherwise return `FALSE`.
-##### *Examples*
+###### *Examples*
~~~php
$redis->hSet('h', 'a', 'x');
$redis->hExists('h', 'a'); /* TRUE */
$redis->hExists('h', 'NonExistingKey'); /* FALSE */
~~~
-### hIncrBy
+#### hIncrBy
-----
_**Description**_: Increments the value of a member from a hash by a given amount.
-##### *Parameters*
-*key*
-*member*
+###### *Parameters*
+*key*
+*member*
*value*: (integer) value that will be added to the member's value
-##### *Return value*
+###### *Return value*
*LONG* the new value
-##### *Examples*
+###### *Examples*
~~~php
$redis->del('h');
$redis->hIncrBy('h', 'x', 2); /* returns 2: h[x] = 2 now. */
$redis->hIncrBy('h', 'x', 1); /* h[x] ← 2 + 1. Returns 3 */
~~~
-### hIncrByFloat
+#### hIncrByFloat
-----
_**Description**_: Increments the value of a hash member by the provided float value
-##### *Parameters*
-*key*
-*member*
+###### *Parameters*
+*key*
+*member*
*value*: (float) value that will be added to the member's value
-##### *Return value*
+###### *Return value*
*FLOAT* the new value
-##### *Examples*
+###### *Examples*
~~~php
$redis->del('h');
$redis->hIncrByFloat('h','x', 1.5); /* returns 1.5: h[x] = 1.5 now */
@@ -1778,30 +1906,30 @@ $redis->hIncrByFloat('h', 'x', 1.5); /* returns 3.0: h[x] = 3.0 now */
$redis->hIncrByFloat('h', 'x', -3.0); /* returns 0.0: h[x] = 0.0 now */
~~~
-### hMSet
+#### hMSet
-----
_**Description**_: Fills in a whole hash. Non-string values are converted to string, using the standard `(string)` cast. NULL values are stored as empty strings.
-##### *Parameters*
-*key*
+###### *Parameters*
+*key*
*members*: key → value array
-##### *Return value*
+###### *Return value*
*BOOL*
-##### *Examples*
+###### *Examples*
~~~php
$redis->del('user:1');
$redis->hMSet('user:1', ['name' => 'Joe', 'salary' => 2000]);
$redis->hIncrBy('user:1', 'salary', 100); // Joe earns 100 more now.
~~~
-### hMGet
+#### hMGet
-----
_**Description**_: Retrieve the values associated to the specified fields in the hash.
-##### *Parameters*
-*key*
+###### *Parameters*
+*key*
*memberKeys* Array
-##### *Return value*
+###### *Return value*
*Array* An array of elements, the values of the specified fields in the hash, with the hash keys as array keys.
-##### *Examples*
+###### *Examples*
~~~php
$redis->del('h');
$redis->hSet('h', 'field1', 'value1');
@@ -1809,18 +1937,18 @@ $redis->hSet('h', 'field2', 'value2');
$redis->hMGet('h', ['field1', 'field2']); /* returns ['field1' => 'value1', 'field2' => 'value2'] */
~~~
-### hScan
+#### hScan
-----
_**Description**_: Scan a HASH value for members, with an optional pattern and count
-##### *Parameters*
-*key*: String
-*iterator*: Long (reference)
-*pattern*: Optional pattern to match against
+###### *Parameters*
+*key*: String
+*iterator*: Long (reference)
+*pattern*: Optional pattern to match against
*count*: How many keys to return in a go (only a suggestion to Redis)
-##### *Return value*
+###### *Return value*
*Array* An array of members that match our pattern
-##### *Examples*
+###### *Examples*
~~~php
$it = NULL;
/* Don't ever return an empty array until we're done iterating */
@@ -1832,54 +1960,54 @@ while($arr_keys = $redis->hScan('hash', $it)) {
}
~~~
-### hStrLen
+#### hStrLen
-----
_**Description**_: Get the string length of the value associated with field in the hash stored at key.
-##### *Parameters*
-*key*: String
+###### *Parameters*
+*key*: String
*field*: String
-##### *Return value*
+###### *Return value*
*LONG* the string length of the value associated with field, or zero when field is not present in the hash or key does not exist at all.
-## Lists
+### Lists
* [blPop, brPop](#blpop-brpop) - Remove and get the first/last element in a list
* [bRPopLPush](#brpoplpush) - Pop a value from a list, push it to another list and return it
-* [lIndex, lGet](#lindex-lget) - Get an element from a list by its index
+* [lIndex](#lindex) - Get an element from a list by its index
* [lInsert](#linsert) - Insert an element before or after another element in a list
-* [lLen, lSize](#llen-lsize) - Get the length/size of a list
+* [lLen](#llen) - Get the length/size of a list
* [lPop](#lpop) - Remove and get the first element in a list
* [lPush](#lpush) - Prepend one or multiple values to a list
* [lPushx](#lpushx) - Prepend a value to a list, only if the list exists
-* [lRange, lGetRange](#lrange-lgetrange) - Get a range of elements from a list
-* [lRem, lRemove](#lrem-lremove) - Remove elements from a list
+* [lRange](#lrange) - Get a range of elements from a list
+* [lRem](#lrem) - Remove elements from a list
* [lSet](#lset) - Set the value of an element in a list by its index
-* [lTrim, listTrim](#ltrim-listtrim) - Trim a list to the specified range
+* [lTrim](#ltrim) - Trim a list to the specified range
* [rPop](#rpop) - Remove and get the last element in a list
* [rPopLPush](#rpoplpush) - Remove the last element in a list, append it to another list and return it (redis >= 1.1)
* [rPush](#rpush) - Append one or multiple values to a list
* [rPushX](#rpushx) - Append a value to a list, only if the list exists
-### blPop, brPop
+#### blPop, brPop
-----
_**Description**_: Is a blocking lPop(rPop) primitive. If at least one of the lists contains at least one element, the element will be popped from the head of the list and returned to the caller.
If all the list identified by the keys passed in arguments are empty, blPop will block during the specified timeout until an element is pushed to one of those lists. This element will be popped.
-##### *Parameters*
-*ARRAY* Array containing the keys of the lists
-*INTEGER* Timeout
-Or
-*STRING* Key1
-*STRING* Key2
-*STRING* Key3
-...
-*STRING* Keyn
+###### *Parameters*
+*ARRAY* Array containing the keys of the lists
+*INTEGER* Timeout
+Or
+*STRING* Key1
+*STRING* Key2
+*STRING* Key3
+...
+*STRING* Keyn
*INTEGER* Timeout
-##### *Return value*
+###### *Return value*
*ARRAY* ['listName', 'element']
-##### *Example*
+###### *Example*
~~~php
/* Non blocking feature */
$redis->lPush('key1', 'A');
@@ -1907,36 +2035,36 @@ $redis->lPush('key1', 'A');
/* ['key1', 'A'] is returned*/
~~~
-### bRPopLPush
+#### bRPopLPush
-----
_**Description**_: A blocking version of `rPopLPush`, with an integral timeout in the third parameter.
-##### *Parameters*
-*Key*: srckey
-*Key*: dstkey
+###### *Parameters*
+*Key*: srckey
+*Key*: dstkey
*Long*: timeout
-##### *Return value*
+###### *Return value*
*STRING* The element that was moved in case of success, `FALSE` in case of timeout.
-### lIndex, lGet
+#### lIndex
-----
_**Description**_: Return the specified element of the list stored at the specified key.
-0 the first element, 1 the second ...
+0 the first element, 1 the second ...
-1 the last element, -2 the penultimate ...
Return `FALSE` in case of a bad index or a key that doesn't point to a list.
-##### *Parameters*
-*key*
+###### *Parameters*
+*key*
*index*
-##### *Return value*
-*String* the element at this index
+###### *Return value*
+*String* the element at this index
*Bool* `FALSE` if the key identifies a non-string data type, or no value corresponds to this index in the list `Key`.
-##### *Example*
+###### *Example*
~~~php
$redis->rPush('key1', 'A');
$redis->rPush('key1', 'B');
@@ -1946,25 +2074,23 @@ $redis->lindex('key1', -1); /* 'C' */
$redis->lindex('key1', 10); /* `FALSE` */
~~~
-**Note:** `lGet` is an alias for `lIndex` and will be removed in future versions of phpredis.
-
-### lInsert
+#### lInsert
-----
_**Description**_: Insert value in the list before or after the pivot value.
The parameter options specify the position of the insert (before or after).
If the list didn't exists, or the pivot didn't exists, the value is not inserted.
-##### *Parameters*
-*key*
-*position* Redis::BEFORE | Redis::AFTER
-*pivot*
+###### *Parameters*
+*key*
+*position* Redis::BEFORE | Redis::AFTER
+*pivot*
*value*
-##### *Return value*
+###### *Return value*
The number of the elements in the list, -1 if the pivot didn't exists.
-##### *Example*
+###### *Example*
~~~php
$redis->del('key1');
$redis->lInsert('key1', Redis::AFTER, 'A', 'X'); /* 0 */
@@ -1982,18 +2108,18 @@ $redis->lRange('key1', 0, -1); /* ['A', 'B', 'X', 'C', 'Y'] */
$redis->lInsert('key1', Redis::AFTER, 'W', 'value'); /* -1 */
~~~
-### lPop
+#### lPop
-----
_**Description**_: Return and remove the first element of the list.
-##### *Parameters*
+###### *Parameters*
*key*
-##### *Return value*
-*STRING* if command executed successfully
+###### *Return value*
+*STRING* if command executed successfully
*BOOL* `FALSE` in case of failure (empty list)
-##### *Example*
+###### *Example*
~~~php
$redis->rPush('key1', 'A');
$redis->rPush('key1', 'B');
@@ -2001,19 +2127,19 @@ $redis->rPush('key1', 'C'); /* key1 => [ 'A', 'B', 'C' ] */
$redis->lPop('key1'); /* key1 => [ 'B', 'C' ] */
~~~
-### lPush
+#### lPush
-----
_**Description**_: Adds one or more values to the head of a LIST. Creates the list if the key didn't exist. If the key exists and is not a list, `FALSE` is returned.
-##### *Prototype*
+###### *Prototype*
~~~php
$redis->lPush($key, $entry [, $entry, $entry]);
~~~
-##### *Return value*
+###### *Return value*
*LONG* The new length of the list in case of success, `FALSE` in case of Failure.
-##### *Examples*
+###### *Examples*
~~~php
$redis->del('key1');
$redis->lPush('key1', 'F'); // returns 1
@@ -2025,18 +2151,18 @@ $redis->lPush('key1', 'C', 'B', 'A'); // Returns 6
/* key1 now contains: [ 'A', 'B', 'C', 'D', 'E', 'F' ]
~~~
-### lPushx
+#### lPushx
-----
_**Description**_: Adds the string value to the head (left) of the list if the list exists.
-##### *Parameters*
-*key*
+###### *Parameters*
+*key*
*value* String, value to push in key
-##### *Return value*
+###### *Return value*
*LONG* The new length of the list in case of success, `FALSE` in case of Failure.
-##### *Examples*
+###### *Examples*
~~~php
$redis->del('key1');
$redis->lPushx('key1', 'A'); // returns 0
@@ -2046,21 +2172,21 @@ $redis->lPushx('key1', 'C'); // returns 3
/* key1 now points to the following list: [ 'A', 'B', 'C' ] */
~~~
-### lRange, lGetRange
+#### lRange
-----
-_**Description**_: Returns the specified elements of the list stored at the specified key in the range [start, end]. start and stop are interpreted as indices:
-0 the first element, 1 the second ...
+_**Description**_: Returns the specified elements of the list stored at the specified key in the range [start, end]. start and stop are interpreted as indices:
+0 the first element, 1 the second ...
-1 the last element, -2 the penultimate ...
-##### *Parameters*
-*key*
-*start*
+###### *Parameters*
+*key*
+*start*
*end*
-##### *Return value*
+###### *Return value*
*Array* containing the values in specified range.
-##### *Example*
+###### *Example*
~~~php
$redis->rPush('key1', 'A');
$redis->rPush('key1', 'B');
@@ -2068,24 +2194,22 @@ $redis->rPush('key1', 'C');
$redis->lRange('key1', 0, -1); /* ['A', 'B', 'C'] */
~~~
-**Note:** `lGetRange` is an alias for `lRange` and will be removed in future versions of phpredis.
-
-### lRem, lRemove
+#### lRem
-----
_**Description**_: Removes the first `count` occurrences of the value element from the list. If count is zero, all the matching elements are removed. If count is negative, elements are removed from tail to head.
**Note**: The argument order is not the same as in the Redis documentation. This difference is kept for compatibility reasons.
-##### *Parameters*
-*key*
-*value*
+###### *Parameters*
+*key*
+*value*
*count*
-##### *Return value*
-*LONG* the number of elements to remove
+###### *Return value*
+*LONG* the number of elements to remove
*BOOL* `FALSE` if the value identified by key is not a list.
-##### *Example*
+###### *Example*
~~~php
$redis->lPush('key1', 'A');
$redis->lPush('key1', 'B');
@@ -2098,21 +2222,19 @@ $redis->lRem('key1', 'A', 2); /* 2 */
$redis->lRange('key1', 0, -1); /* ['C', 'B', 'A'] */
~~~
-**Note:** `lRemove` is an alias for `lRem` and will be removed in future versions of phpredis.
-
-### lSet
+#### lSet
-----
_**Description**_: Set the list at index with the new value.
-##### *Parameters*
-*key*
-*index*
+###### *Parameters*
+*key*
+*index*
*value*
-##### *Return value*
+###### *Return value*
*BOOL* `TRUE` if the new value was set. `FALSE` if the index is out of range, or data type identified by key is not a list.
-##### *Example*
+###### *Example*
~~~php
$redis->rPush('key1', 'A');
$redis->rPush('key1', 'B');
@@ -2122,20 +2244,20 @@ $redis->lSet('key1', 0, 'X');
$redis->lindex('key1', 0); /* 'X' */
~~~
-### lTrim, listTrim
+#### lTrim
-----
_**Description**_: Trims an existing list so that it will contain only a specified range of elements.
-##### *Parameters*
-*key*
-*start*
+###### *Parameters*
+*key*
+*start*
*stop*
-##### *Return value*
-*Array*
+###### *Return value*
+*Array*
*Bool* return `FALSE` if the key identify a non-list value.
-##### *Example*
+###### *Example*
~~~php
$redis->rPush('key1', 'A');
$redis->rPush('key1', 'B');
@@ -2145,20 +2267,18 @@ $redis->lTrim('key1', 0, 1);
$redis->lRange('key1', 0, -1); /* ['A', 'B'] */
~~~
-**Note:** `listTrim` is an alias for `lTrim` and will be removed in future versions of phpredis.
-
-### rPop
+#### rPop
-----
_**Description**_: Returns and removes the last element of the list.
-##### *Parameters*
+###### *Parameters*
*key*
-##### *Return value*
-*STRING* if command executed successfully
+###### *Return value*
+*STRING* if command executed successfully
*BOOL* `FALSE` in case of failure (empty list)
-##### *Example*
+###### *Example*
~~~php
$redis->rPush('key1', 'A');
$redis->rPush('key1', 'B');
@@ -2166,18 +2286,18 @@ $redis->rPush('key1', 'C'); /* key1 => [ 'A', 'B', 'C' ] */
$redis->rPop('key1'); /* key1 => [ 'A', 'B' ] */
~~~
-### rPopLPush
+#### rPopLPush
-----
_**Description**_: Pops a value from the tail of a list, and pushes it to the front of another list. Also return this value. (redis >= 1.1)
-##### *Parameters*
-*Key*: srckey
+###### *Parameters*
+*Key*: srckey
*Key*: dstkey
-##### *Return value*
+###### *Return value*
*STRING* The element that was moved in case of success, `FALSE` in case of failure.
-##### *Example*
+###### *Example*
~~~php
$redis->del('x', 'y');
@@ -2209,19 +2329,19 @@ array(3) {
}
~~~
-### rPush
+#### rPush
-----
_**Description**_: Adds one or more entries to the tail of a LIST. Redis will create the list if it doesn't exist.
-##### *Prototype*
+###### *Prototype*
~~~php
$redis->rPush($key, $entry [, $entry, $entry]);
~~~
-##### *Return value*
+###### *Return value*
*LONG* The new length of the list in case of success, `FALSE` in case of Failure.
-##### *Examples*
+###### *Examples*
~~~php
$redis->del('key1');
$redis->rPush('key1', 'A'); // returns 1
@@ -2231,18 +2351,18 @@ $redis->rPush('key1', 'D', 'E', 'F'); // returns 6
/* key1 now contains: [ 'A', 'B', 'C', 'D', 'E', 'F' ] */
~~~
-### rPushX
+#### rPushX
-----
_**Description**_: Adds the string value to the tail (right) of the list if the list exists. `FALSE` in case of Failure.
-##### *Parameters*
-*key*
+###### *Parameters*
+*key*
*value* String, value to push in key
-##### *Return value*
+###### *Return value*
*LONG* The new length of the list in case of success, `FALSE` in case of Failure.
-##### *Examples*
+###### *Examples*
~~~php
$redis->del('key1');
$redis->rPushX('key1', 'A'); // returns 0
@@ -2252,20 +2372,20 @@ $redis->rPushX('key1', 'C'); // returns 3
/* key1 now points to the following list: [ 'A', 'B', 'C' ] */
~~~
-### lLen, lSize
+#### lLen
-----
_**Description**_: Returns the size of a list identified by Key.
If the list didn't exist or is empty, the command returns 0. If the data type identified by Key is not a list, the command return `FALSE`.
-##### *Parameters*
+###### *Parameters*
*Key*
-##### *Return value*
-*LONG* The size of the list identified by Key exists.
+###### *Return value*
+*LONG* The size of the list identified by Key exists.
*BOOL* `FALSE` if the data type identified by Key is not list
-##### *Example*
+###### *Example*
~~~php
$redis->rPush('key1', 'A');
$redis->rPush('key1', 'B');
@@ -2275,51 +2395,49 @@ $redis->rPop('key1');
$redis->lLen('key1');/* 2 */
~~~
-**Note:** `lSize` is an alias for `lLen` and will be removed in future versions of phpredis.
-
-## Sets
+### Sets
* [sAdd](#sadd) - Add one or more members to a set
-* [sCard, sSize](#scard-ssize) - Get the number of members in a set
+* [sCard](#scard) - Get the number of members in a set
* [sDiff](#sdiff) - Subtract multiple sets
* [sDiffStore](#sdiffstore) - Subtract multiple sets and store the resulting set in a key
* [sInter](#sinter) - Intersect multiple sets
* [sInterStore](#sinterstore) - Intersect multiple sets and store the resulting set in a key
-* [sIsMember, sContains](#sismember-scontains) - Determine if a given value is a member of a set
-* [sMembers, sGetMembers](#smembers-sgetmembers) - Get all the members in a set
+* [sIsMember](#sismember) - Determine if a given value is a member of a set
+* [sMembers](#smembers) - Get all the members in a set
* [sMove](#smove) - Move a member from one set to another
* [sPop](#spop) - Remove and return one or more members of a set at random
* [sRandMember](#srandmember) - Get one or multiple random members from a set
-* [sRem, sRemove](#srem-sremove) - Remove one or more members from a set
+* [sRem](#srem) - Remove one or more members from a set
* [sUnion](#sunion) - Add multiple sets
* [sUnionStore](#sunionstore) - Add multiple sets and store the resulting set in a key
* [sScan](#sscan) - Scan a set for members
-### sAdd
+#### sAdd
-----
_**Description**_: Adds a value to the set value stored at key.
-##### *Parameters*
-*key*
+###### *Parameters*
+*key*
*value*
-##### *Return value*
+###### *Return value*
*LONG* the number of elements added to the set.
-##### *Example*
+###### *Example*
~~~php
$redis->sAdd('key1' , 'member1'); /* 1, 'key1' => {'member1'} */
$redis->sAdd('key1' , 'member2', 'member3'); /* 2, 'key1' => {'member1', 'member2', 'member3'}*/
$redis->sAdd('key1' , 'member2'); /* 0, 'key1' => {'member1', 'member2', 'member3'}*/
~~~
-### sCard, sSize
+#### sCard
-----
_**Description**_: Returns the cardinality of the set identified by key.
-##### *Parameters*
+###### *Parameters*
*key*
-##### *Return value*
+###### *Return value*
*LONG* the cardinality of the set identified by key, 0 if the set doesn't exist.
-##### *Example*
+###### *Example*
~~~php
$redis->sAdd('key1' , 'member1');
$redis->sAdd('key1' , 'member2');
@@ -2328,19 +2446,17 @@ $redis->sCard('key1'); /* 3 */
$redis->sCard('keyX'); /* 0 */
~~~
-**Note:** `sSize` is an alias for `sCard` and will be removed in future versions of phpredis.
-
-### sDiff
+#### sDiff
-----
_**Description**_: Performs the difference between N sets and returns it.
-##### *Parameters*
+###### *Parameters*
*Keys*: key1, key2, ... , keyN: Any number of keys corresponding to sets in redis.
-##### *Return value*
+###### *Return value*
*Array of strings*: The difference of the first set will all the others.
-##### *Example*
+###### *Example*
~~~php
$redis->del('s0', 's1', 's2');
@@ -2364,17 +2480,17 @@ array(2) {
}
~~~
-### sDiffStore
+#### sDiffStore
-----
_**Description**_: Performs the same action as sDiff, but stores the result in the first key
-##### *Parameters*
+###### *Parameters*
*Key*: dstkey, the key to store the diff into.
*Keys*: key1, key2, ... , keyN: Any number of keys corresponding to sets in redis
-##### *Return value*
+###### *Return value*
*INTEGER*: The cardinality of the resulting set, or `FALSE` in case of a missing key.
-##### *Example*
+###### *Example*
~~~php
$redis->del('s0', 's1', 's2');
@@ -2400,22 +2516,22 @@ array(2) {
}
~~~
-### sInter
+#### sInter
-----
_**Description**_: Returns the members of a set resulting from the intersection of all the sets held at the specified keys.
If just a single key is specified, then this command produces the members of this set. If one of the keys
is missing, `FALSE` is returned.
-##### *Parameters*
+###### *Parameters*
key1, key2, keyN: keys identifying the different sets on which we will apply the intersection.
-##### *Return value*
+###### *Return value*
-Array, contain the result of the intersection between those keys. If the intersection between the different sets is empty, the return value will be empty array.
+Array, containing the result of the intersection between those keys. If the intersection between the different sets is empty, the return value will be an empty array.
-##### *Examples*
+###### *Examples*
~~~php
$redis->sAdd('key1', 'val1');
$redis->sAdd('key1', 'val2');
@@ -2442,18 +2558,18 @@ array(2) {
}
~~~
-### sInterStore
+#### sInterStore
-----
_**Description**_: Performs a sInter command and stores the result in a new set.
-##### *Parameters*
+###### *Parameters*
*Key*: dstkey, the key to store the diff into.
*Keys*: key1, key2... keyN. key1..keyN are intersected as in sInter.
-##### *Return value*
+###### *Return value*
*INTEGER*: The cardinality of the resulting set, or `FALSE` in case of a missing key.
-##### *Example*
+###### *Example*
~~~php
$redis->sAdd('key1', 'val1');
$redis->sAdd('key1', 'val2');
@@ -2483,16 +2599,16 @@ array(2) {
}
~~~
-### sIsMember, sContains
+#### sIsMember
-----
_**Description**_: Checks if `value` is a member of the set stored at the key `key`.
-##### *Parameters*
-*key*
+###### *Parameters*
+*key*
*value*
-##### *Return value*
+###### *Return value*
*BOOL* `TRUE` if `value` is a member of the set at key `key`, `FALSE` otherwise.
-##### *Example*
+###### *Example*
~~~php
$redis->sAdd('key1' , 'member1');
$redis->sAdd('key1' , 'member2');
@@ -2502,19 +2618,17 @@ $redis->sIsMember('key1', 'member1'); /* TRUE */
$redis->sIsMember('key1', 'memberX'); /* FALSE */
~~~
-**Note:** `sContains` is an alias for `sIsMember` and will be removed in future versions of phpredis.
-
-### sMembers, sGetMembers
+#### sMembers
-----
_**Description**_: Returns the contents of a set.
-##### *Parameters*
+###### *Parameters*
*Key*: key
-##### *Return value*
+###### *Return value*
An array of elements, the contents of the set.
-##### *Example*
+###### *Example*
~~~php
$redis->del('s');
$redis->sAdd('s', 'a');
@@ -2537,18 +2651,16 @@ array(3) {
~~~
The order is random and corresponds to redis' own internal representation of the set structure.
-**Note:** `sGetMembers` is an alias for `sMembers` and will be removed in future versions of phpredis.
-
-### sMove
+#### sMove
-----
_**Description**_: Moves the specified member from the set at srcKey to the set at dstKey.
-##### *Parameters*
-*srcKey*
-*dstKey*
+###### *Parameters*
+*srcKey*
+*dstKey*
*member*
-##### *Return value*
+###### *Return value*
*BOOL* If the operation is successful, return `TRUE`. If the srcKey and/or dstKey didn't exist, and/or the member didn't exist in srcKey, `FALSE` is returned.
-##### *Example*
+###### *Example*
~~~php
$redis->sAdd('key1' , 'member11');
$redis->sAdd('key1' , 'member12');
@@ -2560,19 +2672,19 @@ $redis->sMove('key1', 'key2', 'member13'); /* 'key1' => {'member11', 'member12'
~~~
-### sPop
+#### sPop
-----
_**Description**_: Removes and returns a random element from the set value at Key.
-##### *Parameters*
-*key*
+###### *Parameters*
+*key*
*count*: Integer, optional
-##### *Return value (without count argument)*
-*String* "popped" value
+###### *Return value (without count argument)*
+*String* "popped" value
*Bool* `FALSE` if set identified by key is empty or doesn't exist.
-##### *Return value (with count argument)*
-*Array*: Member(s) returned or an empty array if the set doesn't exist
+###### *Return value (with count argument)*
+*Array*: Member(s) returned or an empty array if the set doesn't exist
*Bool*: `FALSE` on error if the key is not a set
-##### *Example*
+###### *Example*
~~~php
$redis->sAdd('key1' , 'member1');
$redis->sAdd('key1' , 'member2');
@@ -2585,18 +2697,18 @@ $redis->sAdd('key2', 'member1', 'member2', 'member3');
$redis->sPop('key2', 3); /* Will return all members but in no particular order */
~~~
-### sRandMember
+#### sRandMember
-----
_**Description**_: Returns a random element from the set value at Key, without removing it.
-##### *Parameters*
-*key*
+###### *Parameters*
+*key*
*count* (Integer, optional)
-##### *Return value*
-If no count is provided, a random *String* value from the set will be returned. If a count
+###### *Return value*
+If no count is provided, a random *String* value from the set will be returned. If a count
is provided, an array of values from the set will be returned. Read about the different
ways to use the count here: [SRANDMEMBER](http://redis.io/commands/srandmember)
*Bool* `FALSE` if set identified by key is empty or doesn't exist.
-##### *Example*
+###### *Example*
~~~php
$redis->sAdd('key1' , 'member1');
$redis->sAdd('key1' , 'member2');
@@ -2614,15 +2726,15 @@ $redis->sRandMember('empty-set', 100); // Will return an empty array
$redis->sRandMember('not-a-set', 100); // Will return FALSE
~~~
-### sRem, sRemove
+#### sRem
-----
_**Description**_: Removes the specified member from the set value stored at key.
-##### *Parameters*
-*key*
+###### *Parameters*
+*key*
*member*
-##### *Return value*
+###### *Return value*
*LONG* The number of elements removed from the set.
-##### *Example*
+###### *Example*
~~~php
$redis->sAdd('key1' , 'member1');
$redis->sAdd('key1' , 'member2');
@@ -2630,21 +2742,19 @@ $redis->sAdd('key1' , 'member3'); /* 'key1' => {'member1', 'member2', 'member3'}
$redis->sRem('key1', 'member2', 'member3'); /*return 2. 'key1' => {'member1'} */
~~~
-**Note:** `sRemove` is an alias for `sRem` and will be removed in future versions of phpredis.
-
-### sUnion
+#### sUnion
-----
_**Description**_: Performs the union between N sets and returns it.
-##### *Parameters*
+###### *Parameters*
*Keys*: key1, key2, ... , keyN: Any number of keys corresponding to sets in redis.
-##### *Return value*
+###### *Return value*
*Array of strings*: The union of all these sets.
**Note:** `sUnion` can also take a single array with keys (see example below).
-##### *Example*
+###### *Example*
~~~php
$redis->del('s0', 's1', 's2');
@@ -2676,19 +2786,19 @@ array(4) {
}
~~~
-### sUnionStore
+#### sUnionStore
-----
_**Description**_: Performs the same action as sUnion, but stores the result in the first key
-##### *Parameters*
+###### *Parameters*
*Key*: dstkey, the key to store the diff into.
*Keys*: key1, key2, ... , keyN: Any number of keys corresponding to sets in redis.
-##### *Return value*
+###### *Return value*
*INTEGER*: The cardinality of the resulting set, or `FALSE` in case of a missing key.
-##### *Example*
+###### *Example*
~~~php
$redis->del('s0', 's1', 's2');
@@ -2717,20 +2827,20 @@ array(4) {
}
~~~
-### sScan
+#### sScan
-----
_**Description**_: Scan a set for members
-##### *Parameters*
-*Key*: The set to search
-*iterator*: LONG (reference) to the iterator as we go
-*pattern*: String, optional pattern to match against
+###### *Parameters*
+*Key*: The set to search
+*iterator*: LONG (reference) to the iterator as we go
+*pattern*: String, optional pattern to match against
*count*: How many members to return at a time (Redis might return a different amount)
-##### *Return value*
+###### *Return value*
*Array, boolean*: PHPRedis will return an array of keys or FALSE when we're done iterating
-##### *Example*
+###### *Example*
~~~php
$it = NULL;
$redis->setOption(Redis::OPT_SCAN, Redis::SCAN_RETRY); /* don't return empty results until we're done */
@@ -2753,32 +2863,37 @@ while(($arr_mems = $redis->sScan('set', $it, "*pattern*"))!==FALSE) {
}
~~~
-## Sorted sets
+### Sorted sets
* [bzPop](#bzpop) - Block until Redis can pop the highest or lowest scoring member from one or more ZSETs.
* [zAdd](#zadd) - Add one or more members to a sorted set or update its score if it already exists
-* [zCard, zSize](#zcard-zsize) - Get the number of members in a sorted set
+* [zCard](#zcard) - Get the number of members in a sorted set
* [zCount](#zcount) - Count the members in a sorted set with scores within the given values
+* [zDiff](#zdiff) - Computes the difference between the first and all successive input sorted sets and return the resulting sorted set
+* [zdiffstore](#zdiffstore) - Computes the difference between the first and all successive input sorted sets and stores the result in a new key
* [zIncrBy](#zincrby) - Increment the score of a member in a sorted set
-* [zinterstore, zInter](#zinterstore-zinter) - Intersect multiple sorted sets and store the resulting sorted set in a new key
+* [zInter](#zinter) - Intersect multiple sorted sets and return the resulting sorted set
+* [zinterstore](#zinterstore) - Intersect multiple sorted sets and store the resulting sorted set in a new key
+* [zMscore](#zmscore) - Get the scores associated with the given members in a sorted set
* [zPop](#zpop) - Redis can pop the highest or lowest scoring member from one a ZSET.
* [zRange](#zrange) - Return a range of members in a sorted set, by index
* [zRangeByScore, zRevRangeByScore](#zrangebyscore-zrevrangebyscore) - Return a range of members in a sorted set, by score
* [zRangeByLex](#zrangebylex) - Return a lexicographical range from members that share the same score
* [zRank, zRevRank](#zrank-zrevrank) - Determine the index of a member in a sorted set
-* [zRem, zDelete, zRemove](#zrem-zdelete-zremove) - Remove one or more members from a sorted set
-* [zRemRangeByRank, zDeleteRangeByRank](#zremrangebyrank-zdeleterangebyrank) - Remove all members in a sorted set within the given indexes
-* [zRemRangeByScore, zDeleteRangeByScore, zRemoveRangeByScore](#zremrangebyscore-zdeleterangebyscore-zremoverangebyscore) - Remove all members in a sorted set within the given scores
+* [zRem](#zrem) - Remove one or more members from a sorted set
+* [zRemRangeByRank](#zremrangebyrank) - Remove all members in a sorted set within the given indexes
+* [zRemRangeByScore](#zremrangebyscore) - Remove all members in a sorted set within the given scores
* [zRevRange](#zrevrange) - Return a range of members in a sorted set, by index, with scores ordered from high to low
* [zScore](#zscore) - Get the score associated with the given member in a sorted set
-* [zunionstore, zUnion](#zunionstore-zunion) - Add multiple sorted sets and store the resulting sorted set in a new key
+* [zUnion](#zunion) - Add multiple sorted sets and return the resulting sorted set
+* [zunionstore](#zunionstore) - Add multiple sorted sets and store the resulting sorted set in a new key
* [zScan](#zscan) - Scan a sorted set for members
-### bzPop
+#### bzPop
-----
_**Description**_: Block until Redis can pop the highest or lowest scoring members from one or more ZSETs. There are two commands (`BZPOPMIN` and `BZPOPMAX` for popping the lowest and highest scoring elements respectively.)
-##### *Prototype*
+###### *Prototype*
~~~php
$redis->bzPopMin(array $keys, int $timeout): array
$redis->bzPopMax(array $keys, int $timeout): array
@@ -2787,10 +2902,10 @@ $redis->bzPopMin(string $key1, string $key2, ... int $timeout): array
$redis->bzPopMax(string $key1, string $key2, ... int $timeout): array
~~~
-##### *Return value*
+###### *Return value*
*ARRAY:* Either an array with the key member and score of the highest or lowest element or an empty array if the timeout was reached without an element to pop.
-##### *Example*
+###### *Example*
~~~php
/* Wait up to 5 seconds to pop the *lowest* scoring member from sets `zs1` and `zs2`. */
$redis->bzPopMin(['zs1', 'zs2'], 5);
@@ -2803,28 +2918,28 @@ $redis->bzPopMax('zs1', 'zs2', 5);
**Note:** Calling these functions with an array of keys or with a variable number of arguments is functionally identical.
-### zAdd
+#### zAdd
-----
_**Description**_: Add one or more members to a sorted set or update its score if it already exists
-##### *Prototype*
+###### *Prototype*
~~~php
$redis->zAdd($key, [ $options ,] $score, $value [, $score1, $value1, ...]);
~~~
-##### *Parameters*
+###### *Parameters*
*key*: string
*options*: array (optional)
-*score*: double
+*score*: double
*value*: string
*score1*: double
*value1*: string
-##### *Return value*
+###### *Return value*
*Long* 1 if the element is added. 0 otherwise.
-##### *Example*
+###### *Example*
~~~php
$redis->zAdd('key', 1, 'val1');
$redis->zAdd('key', 0, 'val0');
@@ -2835,17 +2950,17 @@ $redis->zRange('key', 0, -1); // [val0, val1, val5]
$redis->zAdd('key', ['CH'], 5, 'val5', 10, 'val10', 15, 'val15');
~~~
-### zCard, zSize
+#### zCard
-----
_**Description**_: Returns the cardinality of an ordered set.
-##### *Parameters*
+###### *Parameters*
*key*
-##### *Return value*
+###### *Return value*
*Long*, the set's cardinality
-##### *Example*
+###### *Example*
~~~php
$redis->zAdd('key', 0, 'val0');
$redis->zAdd('key', 2, 'val2');
@@ -2853,21 +2968,19 @@ $redis->zAdd('key', 10, 'val10');
$redis->zCard('key'); /* 3 */
~~~
-**Note**: `zSize` is an alias for `zCard` and will be removed in future versions of phpredis.
-
-### zCount
+#### zCount
-----
_**Description**_: Returns the *number* of elements of the sorted set stored at the specified key which have scores in the range [start,end]. Adding a parenthesis before `start` or `end` excludes it from the range. +inf and -inf are also valid limits.
-##### *Parameters*
-*key*
-*start*: string
+###### *Parameters*
+*key*
+*start*: string
*end*: string
-##### *Return value*
+###### *Return value*
*LONG* the size of a corresponding zRangeByScore.
-##### *Example*
+###### *Example*
~~~php
$redis->zAdd('key', 0, 'val0');
$redis->zAdd('key', 2, 'val2');
@@ -2875,19 +2988,88 @@ $redis->zAdd('key', 10, 'val10');
$redis->zCount('key', 0, 3); /* 2, corresponding to ['val0', 'val2'] */
~~~
-### zIncrBy
+#### zDiff
+-----
+_**Description**_: Computes the difference between the first and all successive input sorted sets in the first argument. The result of the difference will be returned.
+
+The second argument is a set of options. It can define `WITHSCORES` so that the scores are returned as well.
+
+###### *Parameters*
+*arrayZSetKeys*
+*arrayOptions* One option is available: `withscores => TRUE`.
+
+###### *Return value*
+*ARRAY* The result of the difference of sets.
+
+###### *Example*
+~~~php
+$redis->del('k1');
+$redis->del('k2');
+$redis->del('k3');
+
+$redis->zAdd('k1', 0, 'val0');
+$redis->zAdd('k1', 1, 'val1');
+$redis->zAdd('k1', 3, 'val3');
+
+$redis->zAdd('k2', 5, 'val1');
+
+$redis->zAdd('k3', 5, 'val0');
+$redis->zAdd('k3', 3, 'val4');
+
+$redis->zDiff(['k1', 'k2']); /* ['val0', 'val3'] */
+$redis->zDiff(['k2', 'k1']); /* [] */
+$redis->zDiff(['k1', 'k2'], ['withscores' => true]); /* ['val0' => 0.0, 'val3' => 3.0] */
+
+$redis->zDiff(['k1', 'k2', 'k3']); /* ['val3'] */
+$redis->zDiff(['k3', 'k2', 'k1']); /* ['val4'] */
+~~~
+
+#### zdiffstore
+-----
+_**Description**_: Computes the difference between the first and all successive input sorted sets in the second argument. The result of the difference will be stored in the sorted set defined by the first argument.
+
+###### *Parameters*
+*keyOutput*
+*arrayZSetKeys*
+
+###### *Return value*
+*LONG* The number of values in the new sorted set.
+
+###### *Example*
+~~~php
+$redis->del('k1');
+$redis->del('k2');
+$redis->del('k3');
+
+$redis->zAdd('k1', 0, 'val0');
+$redis->zAdd('k1', 1, 'val1');
+$redis->zAdd('k1', 3, 'val3');
+
+$redis->zAdd('k2', 5, 'val1');
+
+$redis->zAdd('k3', 5, 'val0');
+$redis->zAdd('k3', 3, 'val4');
+
+$redis->zdiffstore('ko1', ['k1', 'k2']); /* 2, 'ko1' => ['val0', 'val3'] */
+$redis->zdiffstore('ko2', ['k2', 'k1']); /* 0, 'ko2' => [] */
+
+$redis->zdiffstore('ko3', ['k1', 'k2', 'k3']); /* 1, 'ko3' => ['val3'] */
+$redis->zdiffstore('ko4', ['k3', 'k2', 'k1']); /* 1, 'k04' => ['val4'] */
+~~~
+
+#### zIncrBy
-----
_**Description**_: Increments the score of a member from a sorted set by a given amount.
-##### *Parameters*
-*key*
-*value*: (double) value that will be added to the member's score
+###### *Parameters*
+*key*
+*value*: (double) value that will be added to the member's score
*member*
-##### *Return value*
+###### *Return value*
*DOUBLE* the new value
-##### *Examples*
+###### *Examples*
~~~php
$redis->del('key');
$redis->zIncrBy('key', 2.5, 'member1'); /* key or member1 didn't exist, so member1's score is to 0 before the increment */
@@ -2895,23 +3077,59 @@ $redis->zIncrBy('key', 2.5, 'member1'); /* key or member1 didn't exist, so membe
$redis->zIncrBy('key', 1, 'member1'); /* 3.5 */
~~~
-### zinterstore, zInter
+#### zInter
-----
-_**Description**_: Creates an intersection of sorted sets given in second argument. The result of the union will be stored in the sorted set defined by the first argument.
+_**Description**_: Creates an intersection of sorted sets given in first argument. The result of the intersection will be returned.
+
+The second optional argument defines `weights` to apply to the sorted sets in input. In this case, the `weights` will be multiplied by the score of each element in the sorted set before applying the aggregation.
+The third argument is a set of options. It can define the `AGGREGATE` option which specify how the results of the intersection are aggregated. It can also define `WITHSCORES` so that the scores are returned as well.
+
+###### *Parameters*
+*arrayZSetKeys*
+*arrayWeights*
+*arrayOptions* Two options are available: `withscores => TRUE`, and `aggregate => $behaviour`. Either "SUM", "MIN", or "MAX" defines the behaviour to use on duplicate entries during the zinter.
+
+###### *Return value*
+*ARRAY* The result of the intersection of sets.
+
+###### *Example*
+~~~php
+$redis->del('k1');
+$redis->del('k2');
+$redis->del('k3');
+
+$redis->zAdd('k1', 0, 'val0');
+$redis->zAdd('k1', 1, 'val1');
+$redis->zAdd('k1', 3, 'val3');
+
+$redis->zAdd('k2', 5, 'val1');
+$redis->zAdd('k2', 3, 'val3');
+
+$redis->zinter(['k1', 'k2']); /* ['val1', 'val3'] */
+$redis->zinter(['k1', 'k2'], [1, 1]); /* ['val1', 'val3'] */
+
+/* Weighted zinter */
+$redis->zinter(['k1', 'k2'], [1, 5], 'min'); /* ['val1', 'val3'] */
+$redis->zinter(['k1', 'k2'], [1, 5], 'max'); /* ['val3', 'val1'] */
+~~~
+
+#### zinterstore
+-----
+_**Description**_: Creates an intersection of sorted sets given in second argument. The result of the intersection will be stored in the sorted set defined by the first argument.
The third optional argument defines `weights` to apply to the sorted sets in input. In this case, the `weights` will be multiplied by the score of each element in the sorted set before applying the aggregation.
-The forth argument defines the `AGGREGATE` option which specify how the results of the union are aggregated.
+The forth argument defines the `AGGREGATE` option which specify how the results of the intersection are aggregated.
-##### *Parameters*
-*keyOutput*
-*arrayZSetKeys*
-*arrayWeights*
+###### *Parameters*
+*keyOutput*
+*arrayZSetKeys*
+*arrayWeights*
*aggregateFunction* Either "SUM", "MIN", or "MAX": defines the behaviour to use on duplicate entries during the zinterstore.
-##### *Return value*
+###### *Return value*
*LONG* The number of values in the new sorted set.
-##### *Example*
+###### *Example*
~~~php
$redis->del('k1');
$redis->del('k2');
@@ -2926,24 +3144,41 @@ $redis->zAdd('k1', 0, 'val0');
$redis->zAdd('k1', 1, 'val1');
$redis->zAdd('k1', 3, 'val3');
-$redis->zAdd('k2', 2, 'val1');
+$redis->zAdd('k2', 5, 'val1');
$redis->zAdd('k2', 3, 'val3');
$redis->zinterstore('ko1', ['k1', 'k2']); /* 2, 'ko1' => ['val1', 'val3'] */
-$redis->zinterstore('ko2', ['k1', 'k2'], [1, 1]); /* 2, 'ko2' => ['val1', 'val3'] */
+$redis->zinterstore('ko2', ['k1', 'k2'], [1, 1]); /* 2, 'ko2' => ['val1', 'val3'] */
/* Weighted zinterstore */
$redis->zinterstore('ko3', ['k1', 'k2'], [1, 5], 'min'); /* 2, 'ko3' => ['val1', 'val3'] */
$redis->zinterstore('ko4', ['k1', 'k2'], [1, 5], 'max'); /* 2, 'ko4' => ['val3', 'val1'] */
~~~
-**Note:** `zInter` is an alias for `zinterstore` and will be removed in future versions of phpredis.
+#### zMscore
+-----
+_**Description**_: Returns the scores of the given members in the specified sorted set.
+
+###### *Parameters*
+*key*
+*members*: member1, member2, ... , memberN: Any number of members in the specified sorted set.
+
+###### *Return value*
+*ARRAY* or *FALSE* when the key is not found. Array entries corresponding to members that do not exist will be `false`.
+
+###### *Example*
+~~~php
+$redis->zAdd('key', 2.5, 'val2');
+$redis->zAdd('key', 4.5, 'val4');
+
+$redis->zMscore('key', 'val2', 'val3', 'val4'); /* [2.5, false, 4.5] */
+~~~
-### zPop
+#### zPop
-----
_**Description**_: Can pop the highest or lowest scoring members from one ZSETs. There are two commands (`ZPOPMIN` and `ZPOPMAX` for popping the lowest and highest scoring elements respectively.)
-##### *Prototype*
+###### *Prototype*
~~~php
$redis->zPopMin(string $key, int $count): array
$redis->zPopMax(string $key, int $count): array
@@ -2952,10 +3187,10 @@ $redis->zPopMin(string $key, int $count): array
$redis->zPopMax(string $key, int $count): array
~~~
-##### *Return value*
+###### *Return value*
*ARRAY:* Either an array with the key member and score of the highest or lowest element or an empty array if there is no element available.
-##### *Example*
+###### *Example*
~~~php
/* Pop the *lowest* scoring member from set `zs1`. */
$redis->zPopMin('zs1', 5);
@@ -2964,24 +3199,24 @@ $redis->zPopMin('zs1', 5);
$redis->zPopMax('zs1', 5);
~~~
-### zRange
+#### zRange
-----
_**Description**_: Returns a range of elements from the ordered set stored at the specified key, with values in the range [start, end].
-Start and stop are interpreted as zero-based indices:
-`0` the first element, `1` the second ...
-`-1` the last element, `-2` the penultimate ...
+Start and stop are interpreted as zero-based indices:
+`0` the first element, `1` the second ...
+`-1` the last element, `-2` the penultimate ...
-##### *Parameters*
+###### *Parameters*
*key*
-*start*: long
-*end*: long
+*start*: long
+*end*: long
*withscores*: bool = false
-##### *Return value*
+###### *Return value*
*Array* containing the values in specified range.
-##### *Example*
+###### *Example*
~~~php
$redis->zAdd('key1', 0, 'val0');
$redis->zAdd('key1', 2, 'val2');
@@ -2992,22 +3227,22 @@ $redis->zRange('key1', 0, -1); /* ['val0', 'val2', 'val10'] */
$redis->zRange('key1', 0, -1, true); /* ['val0' => 0, 'val2' => 2, 'val10' => 10] */
~~~
-### zRangeByScore, zRevRangeByScore
+#### zRangeByScore, zRevRangeByScore
-----
_**Description**_: Returns the elements of the sorted set stored at the specified key which have scores in the range [start,end]. Adding a parenthesis before `start` or `end` excludes it from the range. +inf and -inf are also valid limits. zRevRangeByScore returns the same items in reverse order, when the `start` and `end` parameters are swapped.
-##### *Parameters*
-*key*
-*start*: string
-*end*: string
+###### *Parameters*
+*key*
+*start*: string
+*end*: string
*options*: array
Two options are available: `withscores => TRUE`, and `limit => [$offset, $count]`
-##### *Return value*
+###### *Return value*
*Array* containing the values in specified range.
-##### *Example*
+###### *Example*
~~~php
$redis->zAdd('key', 0, 'val0');
$redis->zAdd('key', 2, 'val2');
@@ -3019,21 +3254,21 @@ $redis->zRangeByScore('key', 0, 3, ['withscores' => TRUE, 'limit' => [1, 1]]); /
$redis->zRangeByScore('key', '-inf', '+inf', ['withscores' => TRUE]); /* ['val0' => 0, 'val2' => 2, 'val10' => 10] */
~~~
-### zRangeByLex
+#### zRangeByLex
-----
_**Description**_: Returns a lexicographical range of members in a sorted set, assuming the members have the same score. The min and max values are required to start with '(' (exclusive), '[' (inclusive), or be exactly the values '-' (negative inf) or '+' (positive inf). The command must be called with either three *or* five arguments or will return FALSE.
-##### *Parameters*
-*key*: The ZSET you wish to run against
-*min*: The minimum alphanumeric value you wish to get
-*max*: The maximum alphanumeric value you wish to get
-*offset*: Optional argument if you wish to start somewhere other than the first element.
+###### *Parameters*
+*key*: The ZSET you wish to run against
+*min*: The minimum alphanumeric value you wish to get
+*max*: The maximum alphanumeric value you wish to get
+*offset*: Optional argument if you wish to start somewhere other than the first element.
*limit*: Optional argument if you wish to limit the number of elements returned.
-##### *Return value*
+###### *Return value*
*Array* containing the values in the specified range.
-##### *Example*
+###### *Example*
~~~php
foreach(['a','b','c','d','e','f','g'] as $c)
$redis->zAdd('key',0,$c);
@@ -3043,18 +3278,18 @@ $redis->zRangeByLex('key','-','(c') /* ['a','b'] */
$redis->zRangeByLex('key','-','[c',1,2) /* ['b','c'] */
~~~
-### zRank, zRevRank
+#### zRank, zRevRank
-----
_**Description**_: Returns the rank of a given member in the specified sorted set, starting at 0 for the item with the smallest score. zRevRank starts at 0 for the item with the *largest* score.
-##### *Parameters*
-*key*
+###### *Parameters*
+*key*
*member*
-##### *Return value*
+###### *Return value*
*Long*, the item's rank.
-##### *Example*
+###### *Example*
~~~php
$redis->del('z');
$redis->zAdd('key', 1, 'one');
@@ -3065,39 +3300,37 @@ $redis->zRevRank('key', 'one'); /* 1 */
$redis->zRevRank('key', 'two'); /* 0 */
~~~
-### zRem, zDelete, zRemove
+#### zRem
-----
_**Description**_: Delete one or more members from a sorted set.
-##### *Prototype*
+###### *Prototype*
~~~php
$redis->zRem($key, $member [, $member ...]);
~~~
-##### *Return value*
+###### *Return value*
*LONG:* The number of members deleted.
-##### *Example*
+###### *Example*
~~~php
$redis->zAdd('key', 0, 'val0', 1, 'val1', 2, 'val2');
$redis->zRem('key', 'val0', 'val1', 'val2'); // Returns: 3
~~~
-**Note:** `zDelete` and `zRemove` are an alias for `zRem` and will be removed in future versions of phpredis.
-
-### zRemRangeByRank, zDeleteRangeByRank
+#### zRemRangeByRank
-----
_**Description**_: Deletes the elements of the sorted set stored at the specified key which have rank in the range [start,end].
-##### *Parameters*
-*key*
-*start*: LONG
+###### *Parameters*
+*key*
+*start*: LONG
*end*: LONG
-##### *Return value*
+###### *Return value*
*LONG* The number of values deleted from the sorted set
-##### *Example*
+###### *Example*
~~~php
$redis->zAdd('key', 1, 'one');
$redis->zAdd('key', 2, 'two');
@@ -3106,21 +3339,19 @@ $redis->zRemRangeByRank('key', 0, 1); /* 2 */
$redis->zRange('key', 0, -1, ['withscores' => TRUE]); /* ['three' => 3] */
~~~
-**Note:** `zDeleteRangeByRank` is an alias for `zRemRangeByRank` and will be removed in future versions of phpredis.
-
-### zRemRangeByScore, zDeleteRangeByScore, zRemoveRangeByScore
+#### zRemRangeByScore
-----
_**Description**_: Deletes the elements of the sorted set stored at the specified key which have scores in the range [start,end].
-##### *Parameters*
-*key*
-*start*: double or "+inf" or "-inf" string
+###### *Parameters*
+*key*
+*start*: double or "+inf" or "-inf" string
*end*: double or "+inf" or "-inf" string
-##### *Return value*
+###### *Return value*
*LONG* The number of values deleted from the sorted set
-##### *Example*
+###### *Example*
~~~php
$redis->zAdd('key', 0, 'val0');
$redis->zAdd('key', 2, 'val2');
@@ -3128,24 +3359,22 @@ $redis->zAdd('key', 10, 'val10');
$redis->zRemRangeByScore('key', 0, 3); /* 2 */
~~~
-**Note:** `zDeleteRangeByScore` and `zRemoveRangeByScore` are an alias for `zRemRangeByScore` and will be removed in future versions of phpredis.
-
-### zRevRange
+#### zRevRange
-----
-_**Description**_: Returns the elements of the sorted set stored at the specified key in the range [start, end] in reverse order. start and stop are interpreted as zero-based indices:
-`0` the first element, `1` the second ...
+_**Description**_: Returns the elements of the sorted set stored at the specified key in the range [start, end] in reverse order. start and stop are interpreted as zero-based indices:
+`0` the first element, `1` the second ...
`-1` the last element, `-2` the penultimate ...
-##### *Parameters*
-*key*
-*start*: long
-*end*: long
+###### *Parameters*
+*key*
+*start*: long
+*end*: long
*withscores*: bool = false
-##### *Return value*
+###### *Return value*
*Array* containing the values in specified range.
-##### *Example*
+###### *Example*
~~~php
$redis->zAdd('key', 0, 'val0');
$redis->zAdd('key', 2, 'val2');
@@ -3156,40 +3385,74 @@ $redis->zRevRange('key', 0, -1); /* ['val10', 'val2', 'val0'] */
$redis->zRevRange('key', 0, -1, true); /* ['val10' => 10, 'val2' => 2, 'val0' => 0] */
~~~
-### zScore
+#### zScore
-----
_**Description**_: Returns the score of a given member in the specified sorted set.
-##### *Parameters*
-*key*
+###### *Parameters*
+*key*
*member*
-##### *Return value*
+###### *Return value*
*Double* or *FALSE* when the value is not found
-##### *Example*
+###### *Example*
~~~php
$redis->zAdd('key', 2.5, 'val2');
$redis->zScore('key', 'val2'); /* 2.5 */
~~~
-### zunionstore, zUnion
+#### zUnion
+-----
+_**Description**_: Creates an union of sorted sets given in first argument. The result of the union will be returned.
+
+The second optional argument defines `weights` to apply to the sorted sets in input. In this case, the `weights` will be multiplied by the score of each element in the sorted set before applying the aggregation.
+The third argument is a set of options. It can define the `AGGREGATE` option which specify how the results of the intersection are aggregated. It can also define `WITHSCORES` so that the scores are returned as well.
+
+###### *Parameters*
+*arrayZSetKeys*
+*arrayWeights*
+*arrayOptions* Two options are available: `withscores => TRUE`, and `aggregate => $behaviour`. Either "SUM", "MIN", or "MAX" defines the behaviour to use on duplicate entries during the zunion.
+
+###### *Return value*
+*ARRAY* The result of the union of sets.
+
+###### *Example*
+~~~php
+$redis->del('k1');
+$redis->del('k2');
+$redis->del('k3');
+
+$redis->zAdd('k1', 0, 'val0');
+$redis->zAdd('k1', 1, 'val1');
+
+$redis->zAdd('k2', 2, 'val2');
+$redis->zAdd('k2', 3, 'val3');
+
+$redis->zunion(['k1', 'k2']); /* ['val0', 'val1', 'val2', 'val3'] */
+
+/* Weighted zunion */
+$redis->zunion(['k1', 'k2'], [1, 1]); /* ['val0', 'val1', 'val2', 'val3'] */
+$redis->zunion(['k1', 'k2'], [5, 1]); /* ['val0', 'val2', 'val3', 'val1'] */
+~~~
+
+#### zunionstore
-----
_**Description**_: Creates an union of sorted sets given in second argument. The result of the union will be stored in the sorted set defined by the first argument.
The third optional argument defines `weights` to apply to the sorted sets in input. In this case, the `weights` will be multiplied by the score of each element in the sorted set before applying the aggregation.
The forth argument defines the `AGGREGATE` option which specify how the results of the union are aggregated.
-##### *Parameters*
-*keyOutput*
-*arrayZSetKeys*
-*arrayWeights*
+###### *Parameters*
+*keyOutput*
+*arrayZSetKeys*
+*arrayWeights*
*aggregateFunction* Either "SUM", "MIN", or "MAX": defines the behaviour to use on duplicate entries during the zunionstore.
-##### *Return value*
+###### *Return value*
*LONG* The number of values in the new sorted set.
-##### *Example*
+###### *Example*
~~~php
$redis->del('k1');
$redis->del('k2');
@@ -3211,22 +3474,20 @@ $redis->zunionstore('ko2', ['k1', 'k2'], [1, 1]); /* 4, 'ko2' => ['val0', 'val1'
$redis->zunionstore('ko3', ['k1', 'k2'], [5, 1]); /* 4, 'ko3' => ['val0', 'val2', 'val3', 'val1'] */
~~~
-**Note:** `zUnion` is an alias for `zunionstore` and will be removed in future versions of phpredis.
-
-### zScan
+#### zScan
-----
_**Description**_: Scan a sorted set for members, with optional pattern and count
-##### *Parameters*
-*key*: String, the set to scan
-*iterator*: Long (reference), initialized to NULL
-*pattern*: String (optional), the pattern to match
+###### *Parameters*
+*key*: String, the set to scan
+*iterator*: Long (reference), initialized to NULL
+*pattern*: String (optional), the pattern to match
*count*: How many keys to return per iteration (Redis might return a different number)
-##### *Return value*
+###### *Return value*
*Array, boolean* PHPRedis will return matching keys from Redis, or FALSE when iteration is complete
-##### *Example*
+###### *Example*
~~~php
$it = NULL;
$redis->setOption(Redis::OPT_SCAN, Redis::SCAN_RETRY);
@@ -3237,49 +3498,49 @@ while($arr_matches = $redis->zScan('zset', $it, '*pattern*')) {
}
~~~
-## HyperLogLogs
+### HyperLogLogs
-### pfAdd
+#### pfAdd
-----
_**Description**_: Adds the specified elements to the specified HyperLogLog.
-##### *Prototype*
+###### *Prototype*
~~~php
$redis->pfAdd($key, Array $elements);
~~~
-##### *Parameters*
-_Key_
-_Array of values_
+###### *Parameters*
+_Key_
+_Array of values_
-##### *Return value*
+###### *Return value*
*Integer*: 1 if at least 1 HyperLogLog internal register was altered. 0 otherwise.
-##### *Example*
+###### *Example*
~~~php
$redis->pfAdd('hll', ['a', 'b', 'c']); // (int) 1
$redis->pfAdd('hll', ['a', 'b']); // (int) 0
~~~
-### pfCount
+#### pfCount
-----
_**Description**_: Return the approximated cardinality of the set(s) observed by the HyperLogLog at key(s).
-##### *Prototype*
+###### *Prototype*
~~~php
$redis->pfCount($key);
$redis->pfCount(Array $keys);
~~~
-##### *Parameters*
-_Key_ or _Array of keys_
+###### *Parameters*
+_Key_ or _Array of keys_
-##### *Return value*
+###### *Return value*
*Integer*: The approximated number of unique elements observed via [pfAdd](#pfAdd).
-##### *Example*
+###### *Example*
~~~php
$redis->pfAdd('hll1', ['a', 'b', 'c']); // (int) 1
$redis->pfCount('hll1'); // (int) 3
@@ -3290,24 +3551,24 @@ $redis->pfCount('hll2'); // (int) 3
$redis->pfCount(['hll1', 'hll2']); // (int) 5
~~~
-### pfMerge
+#### pfMerge
-----
_**Description**_: Merge N different HyperLogLogs into a single one.
-##### *Prototype*
+###### *Prototype*
~~~php
$redis->pfMerge($destkey, Array $sourceKeys);
~~~
-##### *Parameters*
-_Destination Key_
-_Array of Source Keys_
+###### *Parameters*
+_Destination Key_
+_Array of Source Keys_
-##### *Return value*
+###### *Return value*
*BOOL*: `TRUE` on success, `FALSE` on error.
-##### *Example*
+###### *Example*
~~~php
$redis->pfAdd('hll1', ['a', 'b', 'c']); // (int) 1
$redis->pfAdd('hll2', ['d', 'e', 'a']); // (int) 1
@@ -3317,22 +3578,22 @@ $redis->pfMerge('hll3', ['hll1', 'hll2']); // true
$redis->pfCount('hll3'); // (int) 5
~~~
-## Geocoding
+### Geocoding
-### geoAdd
+#### geoAdd
-----
-##### *Prototype*
+###### *Prototype*
~~~php
$redis->geoAdd($key, $longitude, $latitude, $member [, $longitude, $latitude, $member, ...]);
~~~
_**Description**_: Add one or more geospatial items to the specified key. This function must be called with at least one _longitude, latitude, member_ triplet.
-##### *Return value*
+###### *Return value*
*Integer*: The number of elements added to the geospatial key.
-##### *Example*
+###### *Example*
~~~php
$redis->del("myplaces");
@@ -3342,29 +3603,29 @@ $result = $redis->geoAdd(
-122.431, 37.773, "San Francisco",
-157.858, 21.315, "Honolulu"
);
-~~~
+~~~
-### geoHash
+#### geoHash
-----
-##### *Prototype*
+###### *Prototype*
~~~php
$redis->geoHash($key, $member [, $member, $member, ...]);
~~~
-_**Description**_: Retrieve Geohash strings for one or more elements of a geospatial index.
+_**Description**_: Retrieve Geohash strings for one or more elements of a geospatial index.
-##### *Return value*
-*Array*: One or more Redis Geohash encoded strings.
+###### *Return value*
+*Array*: One or more Redis Geohash encoded strings.
-##### *Example*
+###### *Example*
~~~php
$redis->geoAdd("hawaii", -157.858, 21.306, "Honolulu", -156.331, 20.798, "Maui");
$hashes = $redis->geoHash("hawaii", "Honolulu", "Maui");
var_dump($hashes);
~~~
-##### *Output*
+###### *Output*
~~~
array(2) {
[0]=>
@@ -3374,27 +3635,27 @@ array(2) {
}
~~~
-### geoPos
+#### geoPos
-----
-##### *Prototype*
+###### *Prototype*
~~~php
$redis->geoPos($key, $member [, $member, $member, ...]);
~~~
_**Description**_: Return longitude, latitude positions for each requested member.
-##### *Return value*
+###### *Return value*
*Array*: One or more longitude/latitude positions
-##### *Example*
+###### *Example*
~~~php
$redis->geoAdd("hawaii", -157.858, 21.306, "Honolulu", -156.331, 20.798, "Maui");
$positions = $redis->geoPos("hawaii", "Honolulu", "Maui");
var_dump($positions);
~~~
-##### *Output*
+###### *Output*
~~~
array(2) {
[0]=>
@@ -3414,10 +3675,10 @@ array(2) {
}
~~~
-### GeoDist
+#### GeoDist
-----
-##### *Prototype*
+###### *Prototype*
~~~php
$redis->geoDist($key, $member1, $member2 [, $unit]);
~~~
@@ -3430,10 +3691,10 @@ _**Description**_: Return the distance between two members in a geospatial set.
* 'mi' => Miles
* 'ft' => Feet
-##### *Return value*
-*Double*: The distance between the two passed members in the units requested (meters by default).
+###### *Return value*
+*Double*: The distance between the two passed members in the units requested (meters by default).
-##### *Example*
+###### *Example*
~~~php
$redis->geoAdd("hawaii", -157.858, 21.306, "Honolulu", -156.331, 20.798, "Maui");
@@ -3452,9 +3713,9 @@ echo " feet : $feet\n";
$inches = $redis->geoDist("hawaii", "Honolulu", "Maui", 'in');
echo "Invalid unit returned:\n";
var_dump($inches);
-~~~
+~~~
-##### *Output*
+###### *Output*
~~~
Distance between Honolulu and Maui:
meters : 168275.204
@@ -3465,18 +3726,18 @@ Invalid unit returned:
bool(false)
~~~
-### geoRadius
+#### geoRadius
-----
-##### *Prototype*
+###### *Prototype*
~~~php
$redis->geoRadius($key, $longitude, $latitude, $radius, $unit [, Array $options]);
~~~
-_**Description**_: Return members of a set with geospatial information that are within the radius specified by the caller.
+_**Description**_: Return members of a set with geospatial information that are within the radius specified by the caller.
-##### *Options Array*
-The georadius command can be called with various options that control how Redis returns results. The following table describes the options phpredis supports. All options are case insensitive.
+###### *Options Array*
+The georadius command can be called with various options that control how Redis returns results. The following table describes the options phpredis supports. All options are case insensitive.
| Key | Value | Description
| :--- | :--- | :---- |
@@ -3489,13 +3750,13 @@ The georadius command can be called with various options that control how Redis
| STORE | _key_ | Store results in _key_
| STOREDIST | _key_ | Store the results as distances in _key_
- *Note*: It doesn't make sense to pass both `ASC` and `DESC` options but if both are passed the last one passed will be used.
+ *Note*: It doesn't make sense to pass both `ASC` and `DESC` options but if both are passed the last one passed will be used.
*Note*: When using `STORE[DIST]` in Redis Cluster, the store key must has to the same slot as the query key or you will get a `CROSSLOT` error.
-##### *Return value*
+###### *Return value*
*Mixed*: When no `STORE` option is passed, this function returns an array of results. If it is passed this function returns the number of stored entries.
-
-##### *Example*
+
+###### *Example*
~~~php
/* Add some cities */
$redis->geoAdd("hawaii", -157.858, 21.306, "Honolulu", -156.331, 20.798, "Maui");
@@ -3516,7 +3777,7 @@ $options[] = 'DESC';
var_dump($redis->geoRadius("hawaii", -157.858, 21.306, 300, 'mi', $options));
~~~
-##### *Output*
+###### *Output*
~~~
Within 300 miles of Honolulu:
array(2) {
@@ -3567,22 +3828,22 @@ array(1) {
}
~~~
-### geoRadiusByMember
+#### geoRadiusByMember
-##### *Prototype*
+###### *Prototype*
~~~php
$redis->geoRadiusByMember($key, $member, $radius, $units [, Array $options]);
~~~
_**Description**_: This method is identical to [geoRadius](#georadius) except that instead of passing a longitude and latitude as the "source" you pass an existing member in the geospatial set.
-##### *Options Array*
+###### *Options Array*
See [geoRadius](#georadius) command for options array.
-##### *Return value*
-*Array*: The zero or more entries that are close enough to the member given the distance and radius specified.
+###### *Return value*
+*Array*: The zero or more entries that are close enough to the member given the distance and radius specified.
-##### *Example*
+###### *Example*
~~~php
$redis->geoAdd("hawaii", -157.858, 21.306, "Honolulu", -156.331, 20.798, "Maui");
@@ -3593,7 +3854,7 @@ echo "\nFirst match within 300 miles of Honolulu:\n";
var_dump($redis->geoRadiusByMember("hawaii", "Honolulu", 300, 'mi', ['count' => 1]));
~~~
-##### *Output*
+###### *Output*
~~~
Within 300 miles of Honolulu:
array(2) {
@@ -3610,7 +3871,7 @@ array(1) {
}
~~~
-## Streams
+### Streams
* [xAck](#xack) - Acknowledge one or more pending messages
* [xAdd](#xadd) - Add a message to a stream
@@ -3626,55 +3887,55 @@ array(1) {
* [xRevRange](#xrevrange) - Query one or more messages from end to start
* [xTrim](#xtrim) - Trim a stream's size
-### xAck
+#### xAck
-----
-##### *Prototype*
+###### *Prototype*
~~~php
$obj_redis->xAck($stream, $group, $arr_messages);
~~~
_**Description**_: Acknowledge one or more messages on behalf of a consumer group.
-##### *Return value*
+###### *Return value*
*long*: The number of messages Redis reports as acknowledged.
-##### *Example*
+###### *Example*
~~~php
$obj_redis->xAck('stream', 'group1', ['1530063064286-0', '1530063064286-1']);
~~~
-### xAdd
+#### xAdd
-----
-##### *Prototype*
+###### *Prototype*
~~~php
$obj_redis->xAdd($str_key, $str_id, $arr_message[, $i_maxlen, $boo_approximate]);
~~~
_**Description**_: Add a message to a stream
-##### *Return value*
+###### *Return value*
*String*: The added message ID
-##### *Example*
+###### *Example*
~~~php
$obj_redis->xAdd('mystream', "*", ['field' => 'value']);
$obj_redis->xAdd('mystream', "*", ['field' => 'value'], 1000); // set max length of stream to 1000
$obj_redis->xAdd('mystream', "*", ['field' => 'value'], 1000, true); // set max length of stream to ~1000
~~~
-### xClaim
+#### xClaim
-----
-##### *Prototype*
+###### *Prototype*
~~~php
$obj_redis->xClaim($str_key, $str_group, $str_consumer, $min_idle_time, $arr_ids, [$arr_options]);
~~~
_**Description**_: Claim ownership of one or more pending messages.
-#### *Options Array*
+##### *Options Array*
~~~php
$options = [
/* Note: 'TIME', and 'IDLE' are mutually exclusive */
@@ -3686,10 +3947,10 @@ $options = [
];
~~~
-##### *Return value*
+###### *Return value*
*Array*: Either an array of message IDs along with corresponding data, or just an array of IDs (if the 'JUSTID' option was passed).
-##### *Example*
+###### *Example*
~~~php
$ids = ['1530113681011-0', '1530113681011-1', '1530113681011-2'];
@@ -3710,28 +3971,28 @@ $obj_redis->xClaim(
);
~~~
-### xDel
+#### xDel
-----
-##### *Prototype*
+###### *Prototype*
~~~php
$obj_redis->xDel($str_key, $arr_ids);
~~~
_**Description**_: Delete one or more messages from a stream.
-##### *Return value*
+###### *Return value*
*long*: The number of messages removed
-##### *Example*
+###### *Example*
~~~php
$obj_redis->xDel('mystream', ['1530115304877-0', '1530115305731-0']);
~~~
-### xGroup
+#### xGroup
-----
-##### *Prototype*
+###### *Prototype*
~~~php
$obj_redis->xGroup('HELP');
$obj_redis->xGroup('CREATE', $str_key, $str_group, $str_msg_id, [$boo_mkstream]);
@@ -3740,22 +4001,22 @@ $obj_redis->xGroup('DESTROY', $str_key, $str_group);
$obj_redis->xGroup('DELCONSUMER', $str_key, $str_group, $str_consumer_name);
~~~
-_**Description**_: This command is used in order to create, destroy, or manage consumer groups.
+_**Description**_: This command is used to create, destroy, or manage consumer groups.
-##### *Return value*
+###### *Return value*
*Mixed*: This command returns different types depending on the specific XGROUP command executed.
-##### *Example*
+###### *Example*
~~~php
$obj_redis->xGroup('CREATE', 'mystream', 'mygroup', '0');
$obj_redis->xGroup('CREATE', 'mystream', 'mygroup2', '0', true); /* Create stream if non-existent. */
$obj_redis->xGroup('DESTROY', 'mystream', 'mygroup');
~~~
-### xInfo
+#### xInfo
-----
-##### *Prototype*
+###### *Prototype*
~~~php
$obj_redis->xInfo('CONSUMERS', $str_stream, $str_group);
$obj_redis->xInfo('GROUPS', $str_stream);
@@ -3765,66 +4026,66 @@ $obj_redis->xInfo('HELP');
_**Description**_: Get information about a stream or consumer groups.
-##### *Return value*
+###### *Return value*
*Mixed*: This command returns different types depending on which subcommand is used.
-##### *Example*
+###### *Example*
~~~php
$obj_redis->xInfo('STREAM', 'mystream');
$obj_redis->xInfo('STREAM', 'mystream', 'FULL', 10);
~~~
-### xLen
+#### xLen
-----
-##### *Prototype*
+###### *Prototype*
~~~php
$obj_redis->xLen($str_stream);
~~~
_**Description**_: Get the length of a given stream
-##### *Return value*
+###### *Return value*
*Long*: The number of messages in the stream.
-##### *Example*
+###### *Example*
~~~php
$obj_redis->xLen('mystream');
~~~
-### xPending
+#### xPending
-----
-##### *Prototype*
+###### *Prototype*
~~~php
$obj_redis->xPending($str_stream, $str_group [, $str_start, $str_end, $i_count, $str_consumer]);
~~~
_**Description**_: Get information about pending messages in a given stream.
-##### *Return value*
+###### *Return value*
*Array*: Information about the pending messages, in various forms depending on the specific invocation of XPENDING.
-##### *Examples*
+###### *Examples*
~~~php
$obj_redis->xPending('mystream', 'mygroup');
$obj_redis->xPending('mystream', 'mygroup', '-', '+', 1, 'consumer-1');
~~~
-### xRange
+#### xRange
-----
-##### *Prototype*
+###### *Prototype*
~~~php
$obj_redis->xRange($str_stream, $str_start, $str_end [, $i_count]);
~~~
_**Description**_: Get a range of messages from a given stream.
-##### *Return value*
+###### *Return value*
*Array*: The messages in the stream within the requested range.
-##### *Example*
+###### *Example*
~~~php
/* Get everything in this stream */
$obj_redis->xRange('mystream', '-', '+');
@@ -3833,20 +4094,20 @@ $obj_redis->xRange('mystream', '-', '+');
$obj_redis->xRange('mystream', '-', '+', 2);
~~~
-### xRead
+#### xRead
-----
-##### *Prototype*
+###### *Prototype*
~~~php
$obj_redis->xRead($arr_streams [, $i_count, $i_block]);
~~~
_**Description**_: Read data from one or more streams and only return IDs greater than sent in the command.
-##### *Return value*
+###### *Return value*
*Array*: The messages in the stream newer than the IDs passed to Redis (if any).
-##### *Example*
+###### *Example*
~~~php
$obj_redis->xRead(['stream1' => '1535222584555-0', 'stream2' => '1535222584555-0']);
@@ -3878,20 +4139,20 @@ Array
$obj_redis->xRead(['stream1' => '$'], 1, 0);
~~~
-### xReadGroup
+#### xReadGroup
-----
-##### *Prototype*
+###### *Prototype*
~~~php
$obj_redis->xReadGroup($str_group, $str_consumer, $arr_streams [, $i_count, $i_block]);
~~~
_**Description**_: This method is similar to xRead except that it supports reading messages for a specific consumer group.
-##### *Return value*
+###### *Return value*
*Array*: The messages delivered to this consumer group (if any).
-##### *Examples*
+###### *Examples*
~~~php
/* Consume messages for 'mygroup', 'consumer1' */
$obj_redis->xReadGroup('mygroup', 'consumer1', ['s1' => 0, 's2' => 0]);
@@ -3903,38 +4164,38 @@ $obj_redis->xReadGroup('mygroup', 'consumer1', ['s1' => '>', 's2' => '>']);
$obj_redis->xReadGroup('mygroup', 'consumer2', ['s1' => 0, 's2' => 0], 1, 1000);
~~~
-### xRevRange
+#### xRevRange
-----
-##### *Prototype*
+###### *Prototype*
~~~php
$obj_redis->xRevRange($str_stream, $str_end, $str_start [, $i_count]);
~~~
_**Description**_: This is identical to xRange except the results come back in reverse order. Also note that Redis reverses the order of "start" and "end".
-##### *Return value*
+###### *Return value*
*Array*: The messages in the range specified.
-##### *Example*
+###### *Example*
~~~php
$obj_redis->xRevRange('mystream', '+', '-');
~~~
-### xTrim
+#### xTrim
-----
-##### *Prototype*
+###### *Prototype*
~~~php
$obj_redis->xTrim($str_stream, $i_max_len [, $boo_approximate]);
~~~
-_**Description**_: Trim the stream length to a given maximum. If the "approximate" flag is pasesed, Redis will use your size as a hint but only trim trees in whole nodes (this is more efficient).
+_**Description**_: Trim the stream length to a given maximum. If the "approximate" flag is passed, Redis will use your size as a hint but only trim trees in whole nodes (this is more efficient).
-##### *Return value*
+###### *Return value*
*long*: The number of messages trimmed from the stream.
-##### *Example*
+###### *Example*
~~~php
/* Trim to exactly 100 messages */
$obj_redis->xTrim('mystream', 100);
@@ -3943,86 +4204,124 @@ $obj_redis->xTrim('mystream', 100);
$obj_redis->xTrim('mystream', 100, true);
~~~
-## Pub/sub
+### Pub/sub
+* [subscribe](#subscribe) - Subscribe to channels
+* [unsubscribe](#unsubscribe) - Stop listening to channels
* [pSubscribe](#psubscribe) - Subscribe to channels by pattern
+* [punsubscribe](#punsubscribe) - Stop listening to pattern subscriptions
* [publish](#publish) - Post a message to a channel
-* [subscribe](#subscribe) - Subscribe to channels
* [pubSub](#pubsub) - Introspection into the pub/sub subsystem
-### pSubscribe
+#### subscribe
-----
-_**Description**_: Subscribe to channels by pattern
+_**Description**_: Subscribe to channels. Warning: this function will probably change in the future.
+
+###### *Parameters*
+*channels*: an array of channels to subscribe to
+*callback*: either a string or [$instance, 'method_name']. The callback function receives 3 parameters: the redis instance, the channel name, and the message.
+*return value*: Mixed. Any non-null return value in the callback will be returned to the caller.
+
+Calling `$redis->unsubscribe()` inside the callback removes the provided channels. Once all channel subscriptions have been removed (for example by omitting the parameter so every channel is removed) PhpRedis leaves pub/sub mode and returns control to your script, which is the safest way to exit a `subscribe()` loop from within the callback.
-##### *Parameters*
-*patterns*: An array of patterns to match
-*callback*: Either a string or an array with an object and method. The callback will get four arguments ($redis, $pattern, $channel, $message)
-*return value*: Mixed. Any non-null return value in the callback will be returned to the caller.
-##### *Example*
+###### *Example*
~~~php
-function pSubscribe($redis, $pattern, $chan, $msg) {
- echo "Pattern: $pattern\n";
- echo "Channel: $chan\n";
- echo "Payload: $msg\n";
-}
+$r = new Redis;
+$r->connect('localhost', 6379);
+
+$r->subscribe(['channel'], function ($redis, $chan, $message) {
+ echo "Received {$chan}: {$message}\n";
+ $redis->unsubscribe(['channel']);
+});
+
+echo "Done\n";
~~~
-### publish
+#### unsubscribe
-----
-_**Description**_: Publish messages to channels. Warning: this function will probably change in the future.
+_**Description**_: Remove one or more channel subscriptions. When all active channel subscriptions are removed PhpRedis exits pub/sub mode.
-##### *Parameters*
-*channel*: a channel to publish to
-*message*: string
+###### *Parameters*
+*channels*: an array of channels to unsubscribe from. Passing an empty array, or omitting the parameter while inside an active subscription loop, unsubscribes from every channel.
-##### *Example*
+###### *Return value*
+*Redis|array|bool*: Outside of a subscription loop the method returns `true` on success. When invoked from within a subscription callback the method returns the server response array (`['unsubscribe', $channel, $remaining]`) until all subscriptions have been removed.
+
+###### *Example*
~~~php
-$redis->publish('chan-1', 'hello, world!'); // send message.
+$redis->unsubscribe(['first', 'second']);
~~~
-### subscribe
+#### pSubscribe
-----
-_**Description**_: Subscribe to channels. Warning: this function will probably change in the future.
+_**Description**_: Subscribe to channels by pattern. Warning: this function will probably change in the future.
-##### *Parameters*
-*channels*: an array of channels to subscribe to
-*callback*: either a string or an Array($instance, 'method_name'). The callback function receives 3 parameters: the redis instance, the channel name, and the message.
-*return value*: Mixed. Any non-null return value in the callback will be returned to the caller.
-##### *Example*
-~~~php
-function f($redis, $chan, $msg) {
- switch($chan) {
- case 'chan-1':
- ...
- break;
-
- case 'chan-2':
- ...
- break;
-
- case 'chan-2':
- ...
- break;
- }
-}
+###### *Parameters*
+*patterns*: An array of patterns to match
+*callback*: Either a string or an array with an object and method. The callback will get four arguments ($redis, $pattern, $channel, $message)
+*return value*: Mixed. Any non-null return value in the callback will be returned to the caller.
+
+When you no longer need a pattern subscription call `$redis->punsubscribe()` from inside the callback. PhpRedis tracks the exact patterns you subscribed to and exits pub/sub mode once no patterns remain (including when the parameter is omitted to remove every pattern).
-$redis->subscribe(['chan-1', 'chan-2', 'chan-3'], 'f'); // subscribe to 3 chans
+###### *Example*
+~~~php
+$r = new Redis;
+$r->connect('localhost', 6379);
+
+$r->psubscribe(['*foo*', '*bar*'], function ($redis, $pattern, $channel, $message) {
+ echo "Pattern {$pattern} matched {$channel}: {$message}\n";
+ $redis->punsubscribe(['*foo*', '*bar*']);
+});
+
+echo "Done\n";
~~~
-### pubSub
+#### punsubscribe
+-----
+_**Description**_: Remove one or more pattern subscriptions that were registered with `pSubscribe()`.
+
+###### *Parameters*
+*patterns*: An array of patterns to unsubscribe from.
+
+###### *Return value*
+*Redis|array|bool*: The channels that were removed.
+
+###### *Example*
+~~~php
+$redis->punsubscribe(['orders.*']);
+$redis->punsubscribe(['foo', 'bar']);
+$redis->punsubscribe(['*']);
+~~~
+
+_**Note**_: PhpRedis does not interpret glob-style requests that differ from the patterns you originally supplied to `pSubscribe()`. For example, subscribing with `['foo']` and later calling `$redis->punsubscribe(['*'])` will send the command to Redis, but PhpRedis will still think `foo` is active and will keep invoking the callback. Always pass the same concrete patterns that were used to subscribe.
+
+#### publish
+-----
+_**Description**_: Publish messages to channels. Warning: this function will probably change in the future.
+
+###### *Parameters*
+*channel*: a channel to publish to
+*message*: string
+
+###### *Example*
+~~~php
+$redis->publish('chan-1', 'hello, world!'); // send message.
+~~~
+
+#### pubSub
-----
_**Description**_: A command allowing you to get information on the Redis pub/sub system.
-##### *Parameters*
-*keyword*: String, which can be: "channels", "numsub", or "numpat"
+###### *Parameters*
+*keyword*: String, which can be: "channels", "numsub", or "numpat"
*argument*: Optional, variant. For the "channels" subcommand, you can pass a string pattern. For "numsub" an array of channel names.
-##### *Return value*
-*CHANNELS*: Returns an array where the members are the matching channels.
-*NUMSUB*: Returns a key/value array where the keys are channel names and values are their counts.
+###### *Return value*
+*CHANNELS*: Returns an array where the members are the matching channels.
+*NUMSUB*: Returns a key/value array where the keys are channel names and values are their counts.
*NUMPAT*: Integer return containing the number active pattern subscriptions
-##### *Example*
+###### *Example*
~~~php
$redis->pubSub("channels"); /*All channels */
$redis->pubSub("channels", "*pattern*"); /* Just channels matching your pattern */
@@ -4032,20 +4331,20 @@ $redis->pubSub("numpat"); /* Get the number of pattern subscribers */
~~~
-## Generic
+### Generic
1. [rawCommand](#rawcommand) - Execute any generic command against the server.
-### rawCommand
+#### rawCommand
-----
_**Description**_: A method to execute any arbitrary command against the a Redis server
-##### *Parameters*
+###### *Parameters*
This method is variadic and takes a dynamic number of arguments of various types (string, long, double), but must be passed at least one argument (the command keyword itself).
-##### *Return value*
-The return value can be various types depending on what the server itself returns. No post processing is done to the returned value and must be handled by the client code.
+###### *Return value*
+The return value can be various types depending on what the server itself returns. No post processing is done to the returned value and it must be handled by the client code.
-##### *Example*
+###### *Example*
```php
/* Returns: true */
$redis->rawCommand("set", "foo", "bar");
@@ -4060,22 +4359,22 @@ $redis->rawCommand("rpush", "mylist", "one", 2, 3.5);
$redis->rawCommand("lrange", "mylist", 0, -1);
```
-## Transactions
+### Transactions
1. [multi, exec, discard](#multi-exec-discard) - Enter and exit transactional mode
2. [watch, unwatch](#watch-unwatch) - Watches a key for modifications by another client.
-### multi, exec, discard.
+#### multi, exec, discard.
-----
_**Description**_: Enter and exit transactional mode.
-##### *Parameters*
+###### *Parameters*
(optional) `Redis::MULTI` or `Redis::PIPELINE`. Defaults to `Redis::MULTI`. A `Redis::MULTI` block of commands runs as a single transaction; a `Redis::PIPELINE` block is simply transmitted faster to the server, but without any guarantee of atomicity. `discard` cancels a transaction.
-##### *Return value*
+###### *Return value*
`multi()` returns the Redis instance and enters multi-mode. Once in multi-mode, all subsequent method calls return the same object until `exec()` is called.
-##### *Example*
+###### *Example*
~~~php
$ret = $redis->multi()
->set('key1', 'val1')
@@ -4085,20 +4384,20 @@ $ret = $redis->multi()
->exec();
/*
-$ret == Array(0 => TRUE, 1 => 'val1', 2 => TRUE, 3 => 'val2');
+$ret == [0 => TRUE, 1 => 'val1', 2 => TRUE, 3 => 'val2'];
*/
~~~
-### watch, unwatch
+#### watch, unwatch
-----
_**Description**_: Watches a key for modifications by another client.
If the key is modified between `WATCH` and `EXEC`, the MULTI/EXEC transaction will fail (return `FALSE`). `unwatch` cancels all the watching of all keys by this client.
-##### *Parameters*
+###### *Parameters*
*keys*: string for one key or array for a list of keys
-##### *Example*
+###### *Example*
~~~php
$redis->watch('x'); // or for a list of keys: $redis->watch(['x','another key']);
/* long code here during the execution of which other clients could well modify `x` */
@@ -4112,32 +4411,29 @@ $ret = FALSE if x has been modified between the call to WATCH and the call to EX
-## Scripting
+### Scripting
* [eval](#eval) - Evaluate a LUA script serverside
* [evalSha](#evalsha) - Evaluate a LUA script serverside, from the SHA1 hash of the script instead of the script itself
* [script](#script) - Execute the Redis SCRIPT command to perform various operations on the scripting subsystem
* [getLastError](#getlasterror) - The last error message (if any)
* [clearLastError](#clearlasterror) - Clear the last error message
-* [_prefix](#_prefix) - A utility method to prefix the value with the prefix setting for phpredis
-* [_unserialize](#_unserialize) - A utility method to unserialize data with whatever serializer is set up
-* [_serialize](#_serialize) - A utility method to serialize data with whatever serializer is set up
-### eval
+#### eval
-----
_**Description**_: Evaluate a LUA script serverside
-##### *Parameters*
-*script* string.
-*args* array, optional.
+###### *Parameters*
+*script* string.
+*args* array, optional.
*num_keys* int, optional.
-##### *Return value*
+###### *Return value*
Mixed. What is returned depends on what the LUA script itself returns, which could be a scalar value (int/string), or an array.
Arrays that are returned can also contain other arrays, if that's how it was set up in your LUA script. If there is an error
executing the LUA script, the getLastError() function can tell you the message that came back from Redis (e.g. compile error).
-##### *Examples*
+###### *Examples*
~~~php
$redis->eval("return 1"); // Returns an integer: 1
$redis->eval("return {1,2,3}"); // Returns [1,2,3]
@@ -4149,33 +4445,33 @@ $redis->rpush('mylist','c');
$redis->eval("return {1,2,3,redis.call('lrange','mylist',0,-1)}");
~~~
-### evalSha
+#### evalSha
-----
_**Description**_: Evaluate a LUA script serverside, from the SHA1 hash of the script instead of the script itself.
In order to run this command Redis will have to have already loaded the script,
either by running it or via the SCRIPT LOAD command.
-##### *Parameters*
-*script_sha* string. The sha1 encoded hash of the script you want to run.
-*args* array, optional. Arguments to pass to the LUA script.
+###### *Parameters*
+*script_sha* string. The sha1 encoded hash of the script you want to run.
+*args* array, optional. Arguments to pass to the LUA script.
*num_keys* int, optional. The number of arguments that should go into the KEYS array, vs. the ARGV array when Redis spins the script
-##### *Return value*
+###### *Return value*
Mixed. See EVAL
-##### *Examples*
+###### *Examples*
~~~php
$script = 'return 1';
$sha = $redis->script('load', $script);
$redis->evalSha($sha); // Returns 1
~~~
-### script
+#### script
-----
_**Description**_: Execute the Redis SCRIPT command to perform various operations on the scripting subsystem.
-##### *Usage*
+###### *Usage*
~~~php
$redis->script('load', $script);
$redis->script('flush');
@@ -4183,13 +4479,13 @@ $redis->script('kill');
$redis->script('exists', $script1, [$script2, $script3, ...]);
~~~
-##### *Return value*
+###### *Return value*
* SCRIPT LOAD will return the SHA1 hash of the passed script on success, and FALSE on failure.
* SCRIPT FLUSH should always return TRUE
-* SCRIPT KILL will return true if a script was able to be killed and false if not
+* SCRIPT KILL will return true if a script was killed and false if not
* SCRIPT EXISTS will return an array with TRUE or FALSE for each passed script
-### client
+#### client
-----
_**Description**_: Issue the CLIENT command with various arguments.
@@ -4199,7 +4495,7 @@ The Redis CLIENT command can be used in four ways.
* CLIENT SETNAME [name]
* CLIENT KILL [ip:port]
-##### *Usage*
+###### *Usage*
~~~php
$redis->client('list'); // Get a list of clients
$redis->client('getname'); // Get the name of the current connection
@@ -4207,7 +4503,7 @@ $redis->client('setname', 'somename'); // Set the name of the current connection
$redis->client('kill', ); // Kill the process at ip:port
~~~
-##### *Return value*
+###### *Return value*
This will vary depending on which client command was executed.
* CLIENT LIST will return an array of arrays with client information.
@@ -4217,34 +4513,34 @@ This will vary depending on which client command was executed.
Note: phpredis will attempt to reconnect so you can actually kill your own connection
but may not notice losing it!
-### getLastError
+#### getLastError
-----
_**Description**_: The last error message (if any)
-##### *Parameters*
+###### *Parameters*
*none*
-##### *Return value*
+###### *Return value*
A string with the last returned script based error message, or NULL if there is no error
-##### *Examples*
+###### *Examples*
~~~php
$redis->eval('this-is-not-lua');
$err = $redis->getLastError();
// "ERR Error compiling script (new function): user_script:1: '=' expected near '-'"
~~~
-### clearLastError
+#### clearLastError
-----
_**Description**_: Clear the last error message
-##### *Parameters*
+###### *Parameters*
*none*
-##### *Return value*
+###### *Return value*
*BOOL* TRUE
-##### *Examples*
+###### *Examples*
~~~php
$redis->set('x', 'a');
$redis->incr('x');
@@ -4255,35 +4551,66 @@ $err = $redis->getLastError();
// NULL
~~~
-### _prefix
+### Local Helper Methods
+
+These helpers expose the exact logic PhpRedis uses locally for serialization, compression, and prefixing.
+
+* [_compress](#_compress) - Compress a string with the configured compression option
+* [_uncompress](#_uncompress) - Uncompress a string with the configured compression option
+* [_serialize](#_serialize) - Serialize a value with the configured serializer
+* [_unserialize](#_unserialize) - Unserialize a string with the configured serializer
+* [_pack](#_pack) - Serialize and compress a value exactly as PhpRedis would before sending it to Redis
+* [_unpack](#_unpack) - Reverse `_pack` to retrieve the original PHP value
+* [_prefix](#_prefix) - Apply the configured key prefix locally
+* [_digest](#_digest) - Compute the XXH3 digest of a packed value just like Redis' DIGEST command
+
+#### _compress
-----
-_**Description**_: A utility method to prefix the value with the prefix setting for phpredis.
+_**Description**_: Compress a string using whatever `Redis::OPT_COMPRESSION` is currently set to. This is useful when you need to mimic PhpRedis' compression logic without sending data to Redis.
-##### *Parameters*
-*value* string. The value you wish to prefix
+###### *Parameters*
+*value* string. The string to compress.
-##### *Return value*
-If a prefix is set up, the value now prefixed. If there is no prefix, the value will be returned unchanged.
+###### *Return value*
+*string* Returns the compressed string, or the original value if compression is disabled.
-##### *Examples*
+###### *Examples*
~~~php
-$redis->setOption(Redis::OPT_PREFIX, 'my-prefix:');
-$redis->_prefix('my-value'); // Will return 'my-prefix:my-value'
+$redis->setOption(Redis::OPT_COMPRESSION, Redis::COMPRESSION_LZF);
+$payload = $redis->_compress('large-payload');
+~~~
+
+#### _uncompress
+-----
+_**Description**_: Reverse `_compress` by uncompressing a string with the compression option currently in use.
+
+###### *Parameters*
+*value* string. The raw compressed value to uncompress.
+
+###### *Return value*
+*string* Returns the uncompressed value. Throws an exception if the payload is invalid for the configured compressor.
+
+###### *Examples*
+~~~php
+$redis->setOption(Redis::OPT_COMPRESSION, Redis::COMPRESSION_LZ4);
+$original = $redis->_uncompress($compressedPayload);
~~~
-### _serialize
+#### _serialize
-----
-_**Description**_: A utility method to serialize values manually.
+_**Description**_: Serialize a value manually using whatever serializer is configured.
-This method allows you to serialize a value with whatever serializer is configured, manually.
This can be useful for serialization/unserialization of data going in and out of EVAL commands
-as phpredis can't automatically do this itself. Note that if no serializer is set, phpredis
+as phpredis can't automatically do this itself. Note that if no serializer is set, phpredis
will change Array values to 'Array', and Objects to 'Object'.
-##### *Parameters*
-*value*: Mixed. The value to be serialized
+###### *Parameters*
+*value* mixed. The value to be serialized.
-##### *Examples*
+###### *Return value*
+*string* The serialized representation of the value.
+
+###### *Examples*
~~~php
$redis->setOption(Redis::OPT_SERIALIZER, Redis::SERIALIZER_NONE);
$redis->_serialize("foo"); // returns "foo"
@@ -4294,104 +4621,167 @@ $redis->setOption(Redis::OPT_SERIALIZER, Redis::SERIALIZER_PHP);
$redis->_serialize("foo"); // Returns 's:3:"foo";'
~~~
-### _unserialize
+#### _unserialize
-----
-_**Description**_: A utility method to unserialize data with whatever serializer is set up.
+_**Description**_: Unserialize a string using whatever serializer is configured.
+
+If there is no serializer set, the value will be returned unchanged. If there is a serializer set up,
+and the data passed in is malformed, an exception will be thrown.
-If there is no serializer set, the value will be returned unchanged. If there is a serializer set up,
-and the data passed in is malformed, an exception will be thrown. This can be useful if phpredis is
-serializing values, and you return something from redis in a LUA script that is serialized.
+###### *Parameters*
+*value* string. The value to be unserialized.
-##### *Parameters*
-*value* string. The value to be unserialized
+###### *Return value*
+*mixed* The PHP value represented by the serialized string.
-##### *Examples*
+###### *Examples*
~~~php
$redis->setOption(Redis::OPT_SERIALIZER, Redis::SERIALIZER_PHP);
$redis->_unserialize('a:3:{i:0;i:1;i:1;i:2;i:2;i:3;}'); // Will return [1,2,3]
~~~
+#### _pack
+-----
+_**Description**_: Pack a value the same way PhpRedis does internally by first serializing (if configured) and then compressing (if configured). This mirrors the exact bytes Redis receives.
+
+###### *Parameters*
+*value* mixed. The PHP value to pack.
+
+###### *Return value*
+*string* The packed payload that would be sent to Redis.
+
+###### *Examples*
+~~~php
+$redis->setOption(Redis::OPT_SERIALIZER, Redis::SERIALIZER_PHP);
+$redis->setOption(Redis::OPT_COMPRESSION, Redis::COMPRESSION_LZF);
+$payload = $redis->_pack(['a' => 1]);
+~~~
+
+#### _unpack
+-----
+_**Description**_: Reverse `_pack` by uncompressing and then unserializing a payload using the current PhpRedis options.
+
+###### *Parameters*
+*value* string. The packed payload to unpack.
+###### *Return value*
+*mixed* The unpacked PHP value.
+
+###### *Examples*
+~~~php
+$value = $redis->_unpack($payload);
+~~~
+
+#### _prefix
+-----
+_**Description**_: A utility method to prefix the value with the prefix setting for PhpRedis.
+
+###### *Parameters*
+*value* string. The value you wish to prefix.
+
+###### *Return value*
+*string* Returns the prefixed value when a prefix is configured, or the original string otherwise.
+
+###### *Examples*
+~~~php
+$redis->setOption(Redis::OPT_PREFIX, 'my-prefix:');
+$redis->_prefix('my-value'); // Will return 'my-prefix:my-value'
+~~~
+
+#### _digest
+-----
+_**Description**_: Compute the XXH3 digest of a PHP value after it has been `_pack`ed. This produces the same output as Redis' `DIGEST` command, making it easy to verify values locally.
+
+###### *Parameters*
+*value* mixed. The PHP value to digest.
+
+###### *Return value*
+*string* A 16 character hex string containing the XXH3 digest.
+
+###### *Examples*
+~~~php
+$digest = $redis->_digest(['foo' => 'bar']);
+~~~
-## Introspection
+### Introspection
-### isConnected
+#### isConnected
-----
_**Description**_: A method to determine if a phpredis object thinks it's connected to a server
-##### *Parameters*
+###### *Parameters*
None
-##### *Return value*
+###### *Return value*
*Boolean* Returns TRUE if phpredis thinks it's connected and FALSE if not
-### getHost
+#### getHost
-----
_**Description**_: Retrieve our host or unix socket that we're connected to
-##### *Parameters*
+###### *Parameters*
None
-##### *Return value*
+###### *Return value*
*Mixed* The host or unix socket we're connected to or FALSE if we're not connected
-### getPort
+#### getPort
-----
_**Description**_: Get the port we're connected to
-##### *Parameters*
+###### *Parameters*
None
-##### *Return value*
+###### *Return value*
*Mixed* Returns the port we're connected to or FALSE if we're not connected
-### getDbNum
+#### getDbNum
-----
_**Description**_: Get the database number phpredis is pointed to
-##### *Parameters*
+###### *Parameters*
None
-##### *Return value*
+###### *Return value*
*Mixed* Returns the database number (LONG) phpredis thinks it's pointing to or FALSE if we're not connected
-### getTimeout
+#### getTimeout
-----
_**Description**_: Get the (write) timeout in use for phpredis
-##### *Parameters*
+###### *Parameters*
None
-##### *Return value*
+###### *Return value*
*Mixed* The timeout (DOUBLE) specified in our connect call or FALSE if we're not connected
-### getReadTimeout
+#### getReadTimeout
_**Description**_: Get the read timeout specified to phpredis or FALSE if we're not connected
-##### *Parameters*
+###### *Parameters*
None
-##### *Return value*
+###### *Return value*
*Mixed* Returns the read timeout (which can be set using setOption and Redis::OPT_READ_TIMEOUT) or FALSE if we're not connected
-### getPersistentID
+#### getPersistentID
-----
_**Description**_: Gets the persistent ID that phpredis is using
-##### *Parameters*
+###### *Parameters*
None
-##### *Return value*
+###### *Return value*
*Mixed* Returns the persistent id phpredis is using (which will only be set if connected with pconnect), NULL if we're not
using a persistent ID, and FALSE if we're not connected
-### getAuth
+#### getAuth
-----
_**Description**_: Get the password (or username and password if using Redis 6 ACLs) used to authenticate the connection.
-### *Parameters*
+#### *Parameters*
None
-### *Return value*
+#### *Return value*
*Mixed* Returns NULL if no username/password are set, the password string if a password is set, and a `[username, password]` array if authenticated with a username and password.
diff --git a/array.md b/arrays.md
similarity index 97%
rename from array.md
rename to arrays.md
index c084f70f29..b5ba3738cf 100644
--- a/array.md
+++ b/arrays.md
@@ -40,7 +40,7 @@ $ra = new RedisArray(array("host1", "host2", "host3"), array("previous" => array
#### Specifying the "retry_interval" parameter
The retry_interval is used to specify a delay in milliseconds between reconnection attempts in case the client loses connection with a server
-$ra = new RedisArray(array("host1", "host2:63792", "host2:6380"), array("retry_timeout" => 100));
+$ra = new RedisArray(array("host1", "host2:63792", "host2:6380"), array("retry_interval" => 100));
#### Specifying the "lazy_connect" parameter
@@ -121,7 +121,7 @@ For instance, the keys “{user:1}:name” and “{user:1}:email” will be stor
## Custom key distribution function
In order to control the distribution of keys by hand, you can provide a custom function or closure that returns the server number, which is the index in the array of servers that you created the RedisArray object with.
-For instance, instantiate a RedisArray object with `new RedisArray(array("us-host", "uk-host", "de-host"), array("distributor" => "dist"));` and write a function called "dist" that will return `2` for all the keys that should end up on the "de-host" server.
+For instance, instantiate a RedisArray object with `new RedisArray(["us-host", "uk-host", "de-host"], ["distributor" => "dist"]);` and write a function called "dist" that will return `2` for all the keys that should end up on the "de-host" server.
### Example
diff --git a/backoff.c b/backoff.c
index d0961fcfaf..e795cb9405 100644
--- a/backoff.c
+++ b/backoff.c
@@ -1,15 +1,9 @@
#include "common.h"
+#if PHP_VERSION_ID < 80400
#include
-
-#if PHP_VERSION_ID >= 70100
-#include
#else
-static zend_long php_mt_rand_range(zend_long min, zend_long max) {
- zend_long number = php_rand();
- RAND_RANGE(number, min, max, PHP_RAND_MAX);
- return number;
-}
+#include
#endif
#include "backoff.h"
diff --git a/cluster.md b/cluster.md
index 484bc76a84..3949f88fae 100644
--- a/cluster.md
+++ b/cluster.md
@@ -10,21 +10,23 @@ To maintain consistency with the RedisArray class, one can create and connect to
#### Declaring a cluster with an array of seeds
```php
// Create a cluster setting three nodes as seeds
-$obj_cluster = new RedisCluster(NULL, Array('host:7000', 'host:7001', 'host:7003'));
+$obj_cluster = new RedisCluster(NULL, ['host:7000', 'host:7001', 'host:7003']);
// Connect and specify timeout and read_timeout
-$obj_cluster = new RedisCluster(NULL, Array("host:7000", "host:7001"), 1.5, 1.5);
+$obj_cluster = new RedisCluster(NULL, ["host:7000", "host:7001"], 1.5, 1.5);
// Connect with read/write timeout as well as specify that phpredis should use
// persistent connections to each node.
-$obj_cluster = new RedisCluster(NULL, Array("host:7000", "host:7001"), 1.5, 1.5, true);
+$obj_cluster = new RedisCluster(NULL, ["host:7000", "host:7001"], 1.5, 1.5, true);
// Connect with cluster using password.
-$obj_cluster = new RedisCluster(NULL, Array("host:7000", "host:7001"), 1.5, 1.5, true, "password");
+$obj_cluster = new RedisCluster(NULL, ["host:7000", "host:7001"], 1.5, 1.5, true, "password");
-// Connect with cluster using SSL/TLS
-// last argument is an array with [SSL context](https://www.php.net/manual/en/context.ssl.php) options
-$obj_cluster = new RedisCluster(NULL, Array("host:7000", "host:7001"), 1.5, 1.5, true, NULL, Array("verify_peer" => false));
+// Connect with cluster using TLS
+// last argument is an optional array with [SSL context options](https://www.php.net/manual/en/context.ssl.php) (TLS options)
+// If value is array (even empty), it will connect via TLS. If not, it will connect without TLS.
+// Note: If the seeds start with "ssl:// or tls://", it will connect to the seeds via TLS, but the subsequent connections will connect without TLS if this value is null. So, if your nodes require TLS, this value must be an array, even if empty.
+$obj_cluster = new RedisCluster(NULL, ["host:7000", "host:7001"], 1.5, 1.5, true, NULL, ["verify_peer" => false]);
```
#### Loading a cluster configuration by name
@@ -206,3 +208,13 @@ To enable, set the following INI variable:
redis.session.early_refresh = 1
```
Note: This is disabled by default since it may significantly reduce the session lifetime for long-running scripts. Redis server version 6.2+ required.
+
+### Session compression
+
+Following INI variables can be used to configure session compression:
+~~~
+; Should session compression be enabled? Possible values are zstd, lzf, lz4, none. Defaults to: none
+redis.session.compression = zstd
+; What compression level should be used? Compression level depends on used library. For most deployments range 1-9 should be fine. Defaults to: 3
+redis.session.compression_level = 3
+~~~
diff --git a/cluster_library.c b/cluster_library.c
index 24c8a9142c..b342bfe3e8 100644
--- a/cluster_library.c
+++ b/cluster_library.c
@@ -87,6 +87,22 @@ static void dump_reply(clusterReply *reply, int indent) {
}
*/
+/* MULTI BULK processing callbacks */
+static int mbulk_resp_loop(RedisSock *redis_sock, zval *z_result,
+ long long count, void *ctx);
+static int mbulk_resp_loop_raw(RedisSock *redis_sock, zval *z_result,
+ long long count, void *ctx);
+static int mbulk_resp_loop_zipstr(RedisSock *redis_sock, zval *z_result,
+ long long count, void *ctx);
+static int mbulk_resp_loop_dbl(RedisSock *redis_sock, zval *z_result,
+ long long count, void *ctx);
+static int mbulk_resp_loop_zipdbl(RedisSock *redis_sock, zval *z_result,
+ long long count, void *ctx);
+static int mbulk_resp_loop_assoc(RedisSock *redis_sock, zval *z_result,
+ long long count, void *ctx);
+
+
+
/* Recursively free our reply object. If free_data is non-zero we'll also free
* the payload data (strings) themselves. If not, we just free the structs */
@@ -450,7 +466,7 @@ void cluster_dist_add_val(redisCluster *c, clusterKeyVal *kv, zval *z_val
// Serialize our value
val_free = redis_pack(c->flags, z_val, &val, &val_len);
- // Attach it to the provied keyval entry
+ // Attach it to the provided keyval entry
kv->val = val;
kv->val_len = val_len;
kv->val_free = val_free;
@@ -468,7 +484,7 @@ void cluster_multi_add(clusterMultiCmd *mc, char *data, int data_len) {
redis_cmd_append_sstr(&(mc->args), data, data_len);
}
-/* Finalize a clusterMutliCmd by constructing the whole thing */
+/* Finalize a clusterMultiCmd by constructing the whole thing */
void cluster_multi_fini(clusterMultiCmd *mc) {
mc->cmd.len = 0;
redis_cmd_init_sstr(&(mc->cmd), mc->argc, mc->kw, mc->kw_len);
@@ -640,8 +656,7 @@ cluster_node_create(redisCluster *c, char *host, size_t host_len,
c->flags->timeout, c->flags->read_timeout,
c->flags->persistent, NULL, 0);
- /* Stream context */
- node->sock->stream_ctx = c->flags->stream_ctx;
+ redis_sock_set_context(node->sock, c->flags->context);
redis_sock_set_auth(node->sock, c->flags->user, c->flags->pass);
@@ -709,7 +724,7 @@ static int cluster_map_slots(redisCluster *c, clusterReply *r) {
master = cluster_node_create(c, host, hlen, port, low, 0);
zend_hash_str_update_ptr(c->nodes, key, klen, master);
- // Attach slaves first time we encounter a given master in order to avoid regitering the slaves multiple times
+ // Attach slaves first time we encounter a given master in order to avoid registering the slaves multiple times
for (j = 3; j< r2->elements; j++) {
r3 = r2->element[j];
if (!VALIDATE_SLOTS_INNER(r3)) {
@@ -833,7 +848,7 @@ PHP_REDIS_API redisCluster *cluster_create(double timeout, double read_timeout,
c->err = NULL;
/* Set up our waitms based on timeout */
- c->waitms = (long)(1000 * timeout);
+ c->waitms = (long)(1000 * (timeout + read_timeout));
/* Allocate our seeds hash table */
ALLOC_HASHTABLE(c->seeds);
@@ -856,6 +871,8 @@ cluster_free(redisCluster *c, int free_ctx)
if (c->flags->prefix) zend_string_release(c->flags->prefix);
redis_sock_free_auth(c->flags);
+ redis_sock_free_context(c->flags);
+
efree(c->flags);
/* Call hash table destructors */
@@ -1003,7 +1020,7 @@ void cluster_init_cache(redisCluster *c, redisCachedCluster *cc) {
NULL, 0);
/* Stream context */
- sock->stream_ctx = c->flags->stream_ctx;
+ redis_sock_set_context(sock, c->flags->context);
/* Add to seed nodes */
zend_hash_str_update_ptr(c->seeds, key, keylen, sock);
@@ -1058,11 +1075,9 @@ cluster_init_seeds(redisCluster *c, zend_string **seeds, uint32_t nseeds)
c->flags->timeout, c->flags->read_timeout,
c->flags->persistent, NULL, 0);
- /* Stream context */
- sock->stream_ctx = c->flags->stream_ctx;
-
- /* Credentials */
+ /* Credentials and context */
redis_sock_set_auth(sock, c->flags->user, c->flags->pass);
+ redis_sock_set_context(sock, c->flags->context);
// Index this seed by host/port
key_len = snprintf(key, sizeof(key), "%s:%u", ZSTR_VAL(sock->host),
@@ -1097,7 +1112,7 @@ PHP_REDIS_API int cluster_map_keyspace(redisCluster *c) {
memset(c->master, 0, sizeof(redisClusterNode*)*REDIS_CLUSTER_SLOTS);
}
}
- redis_sock_disconnect(seed, 0);
+ redis_sock_disconnect(seed, 0, 1);
if (mapped) break;
} ZEND_HASH_FOREACH_END();
@@ -1151,7 +1166,7 @@ static int cluster_set_redirection(redisCluster* c, char *msg, int moved)
* redirection, parsing out slot host and port so the caller can take
* appropriate action.
*
- * In the case of a non MOVED/ASK error, we wlll set our cluster error
+ * In the case of a non MOVED/ASK error, we will set our cluster error
* condition so GetLastError can be queried by the client.
*
* This function will return -1 on a critical error (e.g. parse/communication
@@ -1218,13 +1233,13 @@ PHP_REDIS_API void cluster_disconnect(redisCluster *c, int force) {
if (node == NULL) continue;
/* Disconnect from the master */
- redis_sock_disconnect(node->sock, force);
+ redis_sock_disconnect(node->sock, force, 1);
/* We also want to disconnect any slave connections so they will be pooled
* in the event we are using persistent connections and connection pooling. */
if (node->slaves) {
ZEND_HASH_FOREACH_PTR(node->slaves, slave) {
- redis_sock_disconnect(slave->sock, force);
+ redis_sock_disconnect(slave->sock, force, 1);
} ZEND_HASH_FOREACH_END();
}
} ZEND_HASH_FOREACH_END();
@@ -1381,7 +1396,7 @@ static redisClusterNode *cluster_find_node(redisCluster *c, const char *host,
/* Provided a redisCluster object, the slot where we thought data was and
* the slot where data was moved, update our node mapping */
-static void cluster_update_slot(redisCluster *c) {
+static int cluster_update_slot(redisCluster *c) {
redisClusterNode *node;
char key[1024];
size_t klen;
@@ -1390,7 +1405,7 @@ static void cluster_update_slot(redisCluster *c) {
if (c->master[c->redir_slot]) {
/* No need to do anything if it's the same node */
if (!CLUSTER_REDIR_CMP(c, SLOT_SOCK(c,c->redir_slot))) {
- return;
+ return SUCCESS;
}
/* Check to see if we have this new node mapped */
@@ -1403,6 +1418,10 @@ static void cluster_update_slot(redisCluster *c) {
/* If the redirected node is a replica of the previous slot owner, a failover has taken place.
We must then remap the cluster's keyspace in order to update the cluster's topology. */
redisClusterNode *prev_master = SLOT(c,c->redir_slot);
+ if (NULL == prev_master->slaves) {
+ CLUSTER_THROW_EXCEPTION("Redis Cluster's master data is incomplete. Cluster is in invalid state.", 0);
+ return FAILURE;
+ }
redisClusterNode *slave;
ZEND_HASH_FOREACH_PTR(prev_master->slaves, slave) {
if (slave == NULL) {
@@ -1411,8 +1430,11 @@ static void cluster_update_slot(redisCluster *c) {
if (!CLUSTER_REDIR_CMP(c, slave->sock)) {
// Detected a failover, the redirected node was a replica
// Remap the cluster's keyspace
- cluster_map_keyspace(c);
- return;
+ if (cluster_map_keyspace(c) == FAILURE) {
+ CLUSTER_THROW_EXCEPTION("Failed to remap cluster keyspace after failover", 0);
+ return FAILURE;
+ }
+ return SUCCESS;
}
} ZEND_HASH_FOREACH_END();
@@ -1445,6 +1467,7 @@ static void cluster_update_slot(redisCluster *c) {
/* Make sure we unflag this node as a slave, as Redis Cluster will only ever
* direct us to master nodes. */
node->slave = 0;
+ return SUCCESS;
}
/* Abort any transaction in process, by sending DISCARD to any nodes that
@@ -1565,6 +1588,7 @@ PHP_REDIS_API short cluster_send_command(redisCluster *c, short slot, const char
* node until we find one that is available. */
if (cluster_sock_write(c, cmd, cmd_len, 0) == -1) {
/* We have to abort, as no nodes are reachable */
+ cluster_cache_clear(c);
CLUSTER_THROW_EXCEPTION("Can't communicate with any node in the cluster", 0);
return -1;
}
@@ -1585,11 +1609,23 @@ PHP_REDIS_API short cluster_send_command(redisCluster *c, short slot, const char
if (c->redir_type == REDIR_MOVED) {
/* For MOVED redirection we want to update our cached mapping */
- cluster_update_slot(c);
+ if (FAILURE == cluster_update_slot(c)) {
+ return -1;
+ }
c->cmd_sock = SLOT_SOCK(c, slot);
+ /* Verify slot is valid after update */
+ if (!c->cmd_sock) {
+ CLUSTER_THROW_EXCEPTION("Socket for slot is NULL after MOVED redirection", 0);
+ return -1;
+ }
} else if (c->redir_type == REDIR_ASK) {
/* For ASK redirection we want to redirect but not update slot mapping */
c->cmd_sock = cluster_get_asking_sock(c);
+ /* Verify socket from ASK redirection */
+ if (!c->cmd_sock) {
+ CLUSTER_THROW_EXCEPTION("Socket is NULL after ASK redirection", 0);
+ return -1;
+ }
}
}
@@ -1599,11 +1635,13 @@ PHP_REDIS_API short cluster_send_command(redisCluster *c, short slot, const char
// If we've detected the cluster is down, throw an exception
if (c->clusterdown) {
+ cluster_cache_clear(c);
CLUSTER_THROW_EXCEPTION("The Redis Cluster is down (CLUSTERDOWN)", 0);
return -1;
} else if (timedout || resp == -1) {
// Make sure the socket is reconnected, it such that it is in a clean state
- redis_sock_disconnect(c->cmd_sock, 1);
+ redis_sock_disconnect(c->cmd_sock, 1, 1);
+ cluster_cache_clear(c);
if (timedout) {
CLUSTER_THROW_EXCEPTION("Timed out attempting to find data in the correct node!", 0);
@@ -1670,32 +1708,55 @@ cluster_single_line_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *c, void *ct
}
}
-/* BULK response handler */
-PHP_REDIS_API void cluster_bulk_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *c,
- void *ctx)
-{
+static int cluster_bulk_resp_to_zval(redisCluster *c, zval *zdst) {
char *resp;
- // Make sure we can read the response
if (c->reply_type != TYPE_BULK ||
- (resp = redis_sock_read_bulk_reply(c->cmd_sock, c->reply_len)) == NULL)
+ (resp = redis_sock_read_bulk_reply(c->cmd_sock, c->reply_len)) == NULL)
{
- CLUSTER_RETURN_FALSE(c);
+ if (c->reply_type != TYPE_BULK)
+ c->reply_len = 0;
+ ZVAL_FALSE(zdst);
+ return FAILURE;
}
+ redis_unpack(c->flags, resp, c->reply_len, zdst);
+
+ efree(resp);
+
+ return SUCCESS;
+}
+
+/* BULK response handler */
+PHP_REDIS_API void cluster_bulk_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *c,
+ void *ctx)
+{
+ zval zret;
+
+ cluster_bulk_resp_to_zval(c, &zret);
+
if (CLUSTER_IS_ATOMIC(c)) {
- if (!redis_unpack(c->flags, resp, c->reply_len, return_value)) {
- CLUSTER_RETURN_STRING(c, resp, c->reply_len);
- }
+ RETVAL_ZVAL(&zret, 0, 1);
} else {
- zval z_unpacked;
- if (redis_unpack(c->flags, resp, c->reply_len, &z_unpacked)) {
- add_next_index_zval(&c->multi_resp, &z_unpacked);
- } else {
- add_next_index_stringl(&c->multi_resp, resp, c->reply_len);
- }
+ add_next_index_zval(&c->multi_resp, &zret);
+ }
+}
+
+PHP_REDIS_API void
+cluster_bulk_withmeta_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *c,
+ void *ctx)
+{
+ zval zbulk, zmeta;
+
+ cluster_bulk_resp_to_zval(c, &zbulk);
+
+ redis_with_metadata(&zmeta, &zbulk, c->reply_len);
+
+ if (CLUSTER_IS_ATOMIC(c)) {
+ RETVAL_ZVAL(&zmeta, 0, 1);
+ } else {
+ add_next_index_zval(&c->multi_resp, &zmeta);
}
- efree(resp);
}
/* Bulk response where we expect a double */
@@ -1845,7 +1906,7 @@ cluster_zrandmember_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *c, void *ct
}
PHP_REDIS_API void
-cluster_srandmember_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *c, void *ctx) {
+cluster_randmember_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *c, void *ctx) {
if (ctx == NULL) {
cluster_bulk_resp(INTERNAL_FUNCTION_PARAM_PASSTHRU, c, NULL);
} else if (ctx == PHPREDIS_CTX_PTR) {
@@ -1900,7 +1961,7 @@ PHP_REDIS_API void cluster_long_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster
/* TYPE response handler */
PHP_REDIS_API void cluster_type_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *c,
- void *ctx)
+ void *ctx)
{
// Make sure we got the right kind of response
if (c->reply_type != TYPE_LINE) {
@@ -1908,19 +1969,22 @@ PHP_REDIS_API void cluster_type_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster
}
// Switch on the type
- if (strncmp (c->line_reply, "string", 6) == 0) {
+ if (redis_strncmp(c->line_reply, ZEND_STRL("string")) == 0) {
CLUSTER_RETURN_LONG(c, REDIS_STRING);
- } else if (strncmp(c->line_reply, "set", 3) == 0) {
+ } else if (redis_strncmp(c->line_reply, ZEND_STRL("set")) == 0) {
CLUSTER_RETURN_LONG(c, REDIS_SET);
- } else if (strncmp(c->line_reply, "list", 4) == 0) {
+ } else if (redis_strncmp(c->line_reply, ZEND_STRL("list")) == 0) {
CLUSTER_RETURN_LONG(c, REDIS_LIST);
- } else if (strncmp(c->line_reply, "hash", 4) == 0) {
+ } else if (redis_strncmp(c->line_reply, ZEND_STRL("hash")) == 0) {
CLUSTER_RETURN_LONG(c, REDIS_HASH);
- } else if (strncmp(c->line_reply, "zset", 4) == 0) {
+ } else if (redis_strncmp(c->line_reply, ZEND_STRL("zset")) == 0) {
CLUSTER_RETURN_LONG(c, REDIS_ZSET);
- } else if (strncmp(c->line_reply, "stream", 6) == 0) {
+ } else if (redis_strncmp(c->line_reply, ZEND_STRL("stream")) == 0) {
CLUSTER_RETURN_LONG(c, REDIS_STREAM);
+ } else if (redis_strncmp(c->line_reply, ZEND_STRL("vectorset")) == 0) {
+ CLUSTER_RETURN_LONG(c, REDIS_VECTORSET);
} else {
+
CLUSTER_RETURN_LONG(c, REDIS_NOT_FOUND);
}
}
@@ -1929,7 +1993,7 @@ PHP_REDIS_API void cluster_type_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster
PHP_REDIS_API void cluster_sub_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *c,
void *ctx)
{
- subscribeContext *sctx = (subscribeContext*)ctx;
+ subscribeContext *sctx = ctx;
zval z_tab, *z_tmp;
int pull = 0;
@@ -1946,12 +2010,12 @@ PHP_REDIS_API void cluster_sub_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *
if ((z_tmp = zend_hash_index_find(Z_ARRVAL(z_tab), 0)) == NULL ||
strcasecmp(Z_STRVAL_P(z_tmp), sctx->kw) != 0
) {
- zval_dtor(&z_tab);
+ zval_ptr_dtor_nogc(&z_tab);
efree(sctx);
RETURN_FALSE;
}
- zval_dtor(&z_tab);
+ zval_ptr_dtor_nogc(&z_tab);
pull = 1;
}
@@ -1977,12 +2041,12 @@ PHP_REDIS_API void cluster_sub_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *
}
// Make sure we have a message or pmessage
- if (!strncmp(Z_STRVAL_P(z_type), "message", 7) ||
- !strncmp(Z_STRVAL_P(z_type), "pmessage", 8)
- ) {
+ if (zend_string_equals_literal(Z_STR_P(z_type), "message") ||
+ zend_string_equals_literal(Z_STR_P(z_type), "pmessage"))
+ {
is_pmsg = *Z_STRVAL_P(z_type) == 'p';
} else {
- zval_dtor(&z_tab);
+ zval_ptr_dtor_nogc(&z_tab);
continue;
}
@@ -2021,14 +2085,14 @@ PHP_REDIS_API void cluster_sub_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *
// If we have a return value, free it
zval_ptr_dtor(&z_ret);
- zval_dtor(&z_tab);
+ zval_ptr_dtor_nogc(&z_tab);
}
// We're no longer subscribing, due to an error
c->subscribed_slot = -1;
// Cleanup
- zval_dtor(&z_tab);
+ zval_ptr_dtor_nogc(&z_tab);
efree(sctx);
// Failure
@@ -2039,8 +2103,8 @@ PHP_REDIS_API void cluster_sub_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *
PHP_REDIS_API void cluster_unsub_resp(INTERNAL_FUNCTION_PARAMETERS,
redisCluster *c, void *ctx)
{
- subscribeContext *sctx = (subscribeContext*)ctx;
- zval z_tab, *z_chan, *z_flag;
+ subscribeContext *sctx = ctx;
+ zval z_tab = {0}, *z_chan, *z_flag;
int pull = 0, argc = sctx->argc;
efree(sctx);
@@ -2052,8 +2116,8 @@ PHP_REDIS_API void cluster_unsub_resp(INTERNAL_FUNCTION_PARAMETERS,
if (!cluster_zval_mbulk_resp(INTERNAL_FUNCTION_PARAM_PASSTHRU, c, pull, mbulk_resp_loop_raw, &z_tab) ||
(z_chan = zend_hash_index_find(Z_ARRVAL(z_tab), 1)) == NULL
) {
- zval_dtor(&z_tab);
- zval_dtor(return_value);
+ zval_ptr_dtor_nogc(&z_tab);
+ zval_ptr_dtor_nogc(return_value);
RETURN_FALSE;
}
@@ -2061,8 +2125,8 @@ PHP_REDIS_API void cluster_unsub_resp(INTERNAL_FUNCTION_PARAMETERS,
if ((z_flag = zend_hash_index_find(Z_ARRVAL(z_tab), 2)) == NULL ||
Z_STRLEN_P(z_flag) != 2
) {
- zval_dtor(&z_tab);
- zval_dtor(return_value);
+ zval_ptr_dtor_nogc(&z_tab);
+ zval_ptr_dtor_nogc(return_value);
RETURN_FALSE;
}
@@ -2072,7 +2136,7 @@ PHP_REDIS_API void cluster_unsub_resp(INTERNAL_FUNCTION_PARAMETERS,
// Add result
add_assoc_bool(return_value, Z_STRVAL_P(z_chan), flag[1] == '1');
- zval_dtor(&z_tab);
+ zval_ptr_dtor_nogc(&z_tab);
pull = 1;
}
}
@@ -2242,10 +2306,11 @@ PHP_REDIS_API void cluster_variant_resp_strings(INTERNAL_FUNCTION_PARAMETERS, re
}
/* Generic MULTI BULK response processor */
-PHP_REDIS_API void cluster_gen_mbulk_resp(INTERNAL_FUNCTION_PARAMETERS,
- redisCluster *c, mbulk_cb cb, void *ctx)
+static void
+cluster_gen_mbulk_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *c,
+ zend_bool init_array, mbulk_cb cb, void *ctx)
{
- zval z_result;
+ zval z_result = {0};
/* Abort if the reply isn't MULTIBULK or has an invalid length */
if (c->reply_type != TYPE_MULTIBULK || c->reply_len < -1) {
@@ -2254,19 +2319,20 @@ PHP_REDIS_API void cluster_gen_mbulk_resp(INTERNAL_FUNCTION_PARAMETERS,
if (c->reply_len == -1 && c->flags->null_mbulk_as_null) {
ZVAL_NULL(&z_result);
- } else {
+ } else if (c->reply_len <= 0) {
array_init(&z_result);
+ } else {
+ if (init_array)
+ array_init(&z_result);
- if (c->reply_len > 0) {
- /* Push serialization settings from the cluster into our socket */
- c->cmd_sock->serializer = c->flags->serializer;
- c->cmd_sock->compression = c->flags->compression;
+ /* Push serialization settings from the cluster into our socket */
+ c->cmd_sock->serializer = c->flags->serializer;
+ c->cmd_sock->compression = c->flags->compression;
- /* Call our specified callback */
- if (cb(c->cmd_sock, &z_result, c->reply_len, ctx) == FAILURE) {
- zval_dtor(&z_result);
- CLUSTER_RETURN_FALSE(c);
- }
+ /* Call our specified callback */
+ if (cb(c->cmd_sock, &z_result, c->reply_len, ctx) == FAILURE) {
+ zval_ptr_dtor_nogc(&z_result);
+ CLUSTER_RETURN_FALSE(c);
}
}
@@ -2279,8 +2345,9 @@ PHP_REDIS_API void cluster_gen_mbulk_resp(INTERNAL_FUNCTION_PARAMETERS,
}
/* HSCAN, SSCAN, ZSCAN */
-PHP_REDIS_API int cluster_scan_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *c,
- REDIS_SCAN_TYPE type, long *it)
+PHP_REDIS_API int
+cluster_scan_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *c,
+ REDIS_SCAN_TYPE type, uint64_t *cursor)
{
char *pit;
@@ -2304,12 +2371,11 @@ PHP_REDIS_API int cluster_scan_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *
}
// Push the new iterator value to our caller
- *it = atol(pit);
+ *cursor = strtoull(pit, NULL, 10);
efree(pit);
// We'll need another MULTIBULK response for the payload
- if (cluster_check_response(c, &c->reply_type) < 0)
- {
+ if (cluster_check_response(c, &c->reply_type) < 0) {
return FAILURE;
}
@@ -2395,7 +2461,7 @@ cluster_xrange_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *c, void *ctx) {
c->cmd_sock->compression = c->flags->compression;
if (redis_read_stream_messages(c->cmd_sock, c->reply_len, &z_messages) < 0) {
- zval_dtor(&z_messages);
+ zval_ptr_dtor_nogc(&z_messages);
CLUSTER_RETURN_FALSE(c);
}
@@ -2419,7 +2485,7 @@ cluster_xread_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *c, void *ctx) {
} else {
array_init(&z_streams);
if (redis_read_stream_messages_multi(c->cmd_sock, c->reply_len, &z_streams) < 0) {
- zval_dtor(&z_streams);
+ zval_ptr_dtor_nogc(&z_streams);
CLUSTER_RETURN_FALSE(c);
}
}
@@ -2441,7 +2507,7 @@ cluster_xclaim_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *c, void *ctx) {
ZEND_ASSERT(ctx == NULL || ctx == PHPREDIS_CTX_PTR);
if (redis_read_xclaim_reply(c->cmd_sock, c->reply_len, ctx == PHPREDIS_CTX_PTR, &z_msg) < 0) {
- zval_dtor(&z_msg);
+ zval_ptr_dtor_nogc(&z_msg);
CLUSTER_RETURN_FALSE(c);
}
@@ -2453,6 +2519,102 @@ cluster_xclaim_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *c, void *ctx) {
}
+PHP_REDIS_API void
+cluster_vemb_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *c, void *ctx) {
+ zval z_ret;
+
+ ZVAL_FALSE(&z_ret);
+
+ if (c->reply_type != TYPE_MULTIBULK || c->reply_len < 0)
+ goto fail;
+
+ array_init(&z_ret);
+
+ if (redis_read_vemb_response(c->cmd_sock, &z_ret, c->reply_len) != SUCCESS)
+ goto fail;
+
+ if (CLUSTER_IS_ATOMIC(c)) {
+ RETURN_ZVAL(&z_ret, 0, 1);
+ } else {
+ add_next_index_zval(&c->multi_resp, &z_ret);
+ }
+
+ return;
+
+fail:
+ zval_ptr_dtor_nogc(&z_ret);
+ CLUSTER_RETURN_FALSE(c);
+}
+
+PHP_REDIS_API void
+cluster_vinfo_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *c, void *ctx) {
+ zval z_ret;
+
+ if (c->reply_len < 2 || c->reply_len % 2 != 0) {
+ CLUSTER_RETURN_FALSE(c);
+ }
+
+ array_init_size(&z_ret, c->reply_len / 2);
+ if (redis_read_vinfo_response(c->cmd_sock, &z_ret, c->reply_len) != SUCCESS) {
+ zval_ptr_dtor_nogc(&z_ret);
+ CLUSTER_RETURN_FALSE(c);
+ }
+
+ if (CLUSTER_IS_ATOMIC(c)) {
+ RETURN_ZVAL(&z_ret, 0, 1);
+ }
+
+ add_next_index_zval(&c->multi_resp, &z_ret);
+}
+
+PHP_REDIS_API void
+cluster_vgetattr_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *c, void *ctx)
+{
+ zval z_ret;
+ char *str;
+
+ if (c->reply_type != TYPE_BULK || c->reply_len <= 0 ||
+ (str = redis_sock_read_bulk_reply(c->cmd_sock, c->reply_len)) == NULL)
+ {
+ CLUSTER_RETURN_FALSE(c);
+ }
+
+ if (ctx != PHPREDIS_CTX_PTR ||
+ redis_deserialize_vgetattr_reply(&z_ret, str, c->reply_len) != SUCCESS)
+ {
+ ZVAL_STRINGL(&z_ret, str, c->reply_len);
+ }
+
+ efree(str);
+
+ if (CLUSTER_IS_ATOMIC(c)) {
+ RETURN_ZVAL(&z_ret, 0, 1);
+ } else {
+ add_next_index_zval(&c->multi_resp, &z_ret);
+ }
+}
+
+PHP_REDIS_API void
+cluster_vlinks_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *c, void *ctx) {
+ zval z_ret;
+
+ if (c->reply_len < 0) {
+ CLUSTER_RETURN_FALSE(c);
+ }
+
+ if (redis_read_vlinks_response(c->cmd_sock, &z_ret, c->reply_len, ctx)
+ != SUCCESS)
+ {
+ CLUSTER_RETURN_FALSE(c);
+ }
+
+ if (CLUSTER_IS_ATOMIC(c)) {
+ RETURN_ZVAL(&z_ret, 0, 1);
+ } else {
+ add_next_index_zval(&c->multi_resp, &z_ret);
+ }
+}
+
/* XINFO */
PHP_REDIS_API void
cluster_xinfo_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *c, void *ctx)
@@ -2461,7 +2623,7 @@ cluster_xinfo_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *c, void *ctx)
array_init(&z_ret);
if (redis_read_xinfo_response(c->cmd_sock, &z_ret, c->reply_len) != SUCCESS) {
- zval_dtor(&z_ret);
+ zval_ptr_dtor_nogc(&z_ret);
CLUSTER_RETURN_FALSE(c);
}
@@ -2496,7 +2658,7 @@ cluster_acl_custom_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *c, void *ctx
array_init(&z_ret);
if (cb(c->cmd_sock, &z_ret, c->reply_len) != SUCCESS) {
- zval_dtor(&z_ret);
+ zval_ptr_dtor_nogc(&z_ret);
CLUSTER_RETURN_FALSE(c);
}
@@ -2539,7 +2701,7 @@ PHP_REDIS_API zval *cluster_zval_mbulk_resp(INTERNAL_FUNCTION_PARAMETERS,
// Call our callback
if (cb(c->cmd_sock, z_ret, c->reply_len, NULL) == FAILURE) {
- zval_dtor(z_ret);
+ zval_ptr_dtor_nogc(z_ret);
return NULL;
}
@@ -2551,8 +2713,9 @@ PHP_REDIS_API void cluster_multi_mbulk_resp(INTERNAL_FUNCTION_PARAMETERS,
redisCluster *c, void *ctx)
{
zval *multi_resp = &c->multi_resp;
- array_init(multi_resp);
+ uint8_t flags = c->flags->flags;
+ array_init(multi_resp);
clusterFoldItem *fi = c->multi_head;
while (fi) {
/* Make sure our transaction didn't fail here */
@@ -2564,11 +2727,13 @@ PHP_REDIS_API void cluster_multi_mbulk_resp(INTERNAL_FUNCTION_PARAMETERS,
c->cmd_sock = SLOT_SOCK(c, fi->slot);
if (cluster_check_response(c, &c->reply_type) < 0) {
- zval_dtor(multi_resp);
+ zval_ptr_dtor_nogc(multi_resp);
RETURN_FALSE;
}
+ c->flags->flags = fi->flags;
fi->callback(INTERNAL_FUNCTION_PARAM_PASSTHRU, c, fi->ctx);
+ c->flags->flags = flags;
} else {
/* Just add false */
add_next_index_bool(multi_resp, 0);
@@ -2577,7 +2742,7 @@ PHP_REDIS_API void cluster_multi_mbulk_resp(INTERNAL_FUNCTION_PARAMETERS,
}
// Set our return array
- zval_dtor(return_value);
+ zval_ptr_dtor_nogc(return_value);
RETVAL_ZVAL(multi_resp, 0, 1);
}
@@ -2585,7 +2750,7 @@ PHP_REDIS_API void cluster_multi_mbulk_resp(INTERNAL_FUNCTION_PARAMETERS,
PHP_REDIS_API void cluster_mbulk_mget_resp(INTERNAL_FUNCTION_PARAMETERS,
redisCluster *c, void *ctx)
{
- clusterMultiCtx *mctx = (clusterMultiCtx*)ctx;
+ clusterMultiCtx *mctx = ctx;
/* Protect against an invalid response type, -1 response length, and failure
* to consume the responses. */
@@ -2621,7 +2786,7 @@ PHP_REDIS_API void cluster_mbulk_mget_resp(INTERNAL_FUNCTION_PARAMETERS,
PHP_REDIS_API void cluster_msetnx_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *c,
void *ctx)
{
- clusterMultiCtx *mctx = (clusterMultiCtx*)ctx;
+ clusterMultiCtx *mctx = ctx;
int real_argc = mctx->count/2;
// Protect against an invalid response type
@@ -2657,7 +2822,7 @@ PHP_REDIS_API void cluster_msetnx_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluste
PHP_REDIS_API void cluster_del_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *c,
void *ctx)
{
- clusterMultiCtx *mctx = (clusterMultiCtx*)ctx;
+ clusterMultiCtx *mctx = ctx;
// If we get an invalid reply, inform the client
if (c->reply_type != TYPE_INT) {
@@ -2686,14 +2851,14 @@ PHP_REDIS_API void cluster_del_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *
PHP_REDIS_API void cluster_mset_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *c,
void *ctx)
{
- clusterMultiCtx *mctx = (clusterMultiCtx*)ctx;
+ clusterMultiCtx *mctx = ctx;
// If we get an invalid reply type something very wrong has happened,
// and we have to abort.
if (c->reply_type != TYPE_LINE) {
php_error_docref(0, E_ERROR,
"Invalid reply type returned for MSET command");
- zval_dtor(mctx->z_multi);
+ zval_ptr_dtor_nogc(mctx->z_multi);
efree(mctx->z_multi);
efree(mctx);
RETURN_FALSE;
@@ -2702,9 +2867,9 @@ PHP_REDIS_API void cluster_mset_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster
// Set our return if it's the last call
if (mctx->last) {
if (CLUSTER_IS_ATOMIC(c)) {
- ZVAL_BOOL(return_value, zval_is_true(mctx->z_multi));
+ ZVAL_BOOL(return_value, zend_is_true(mctx->z_multi));
} else {
- add_next_index_bool(&c->multi_resp, zval_is_true(mctx->z_multi));
+ add_next_index_bool(&c->multi_resp, zend_is_true(mctx->z_multi));
}
efree(mctx->z_multi);
}
@@ -2717,7 +2882,7 @@ PHP_REDIS_API void
cluster_mbulk_raw_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *c, void *ctx)
{
cluster_gen_mbulk_resp(INTERNAL_FUNCTION_PARAM_PASSTHRU, c,
- mbulk_resp_loop_raw, NULL);
+ 1, mbulk_resp_loop_raw, NULL);
}
/* Unserialize all the things */
@@ -2725,7 +2890,7 @@ PHP_REDIS_API void
cluster_mbulk_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *c, void *ctx)
{
cluster_gen_mbulk_resp(INTERNAL_FUNCTION_PARAM_PASSTHRU, c,
- mbulk_resp_loop, NULL);
+ 1, mbulk_resp_loop, NULL);
}
/* For handling responses where we get key, value, key, value that
@@ -2735,7 +2900,7 @@ cluster_mbulk_zipstr_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *c,
void *ctx)
{
cluster_gen_mbulk_resp(INTERNAL_FUNCTION_PARAM_PASSTHRU, c,
- mbulk_resp_loop_zipstr, NULL);
+ 1, mbulk_resp_loop_zipstr, NULL);
}
/* Handling key,value to key=>value where the values are doubles */
@@ -2744,7 +2909,7 @@ cluster_mbulk_zipdbl_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *c,
void *ctx)
{
cluster_gen_mbulk_resp(INTERNAL_FUNCTION_PARAM_PASSTHRU, c,
- mbulk_resp_loop_zipdbl, NULL);
+ 1, mbulk_resp_loop_zipdbl, NULL);
}
PHP_REDIS_API void
@@ -2752,7 +2917,7 @@ cluster_mbulk_dbl_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *c,
void *ctx)
{
cluster_gen_mbulk_resp(INTERNAL_FUNCTION_PARAM_PASSTHRU, c,
- mbulk_resp_loop_dbl, ctx);
+ 1, mbulk_resp_loop_dbl, ctx);
}
/* Associate multi bulk response (for HMGET really) */
@@ -2761,15 +2926,15 @@ cluster_mbulk_assoc_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *c,
void *ctx)
{
cluster_gen_mbulk_resp(INTERNAL_FUNCTION_PARAM_PASSTHRU, c,
- mbulk_resp_loop_assoc, ctx);
+ 0, mbulk_resp_loop_assoc, ctx);
}
/*
* Various MULTI BULK reply callback functions
*/
-int mbulk_resp_loop_dbl(RedisSock *redis_sock, zval *z_result,
- long long count, void *ctx)
+static int mbulk_resp_loop_dbl(RedisSock *redis_sock, zval *z_result,
+ long long count, void *ctx)
{
char *line;
int line_len;
@@ -2788,8 +2953,8 @@ int mbulk_resp_loop_dbl(RedisSock *redis_sock, zval *z_result,
}
/* MULTI BULK response where we don't touch the values (e.g. KEYS) */
-int mbulk_resp_loop_raw(RedisSock *redis_sock, zval *z_result,
- long long count, void *ctx)
+static int mbulk_resp_loop_raw(RedisSock *redis_sock, zval *z_result,
+ long long count, void *ctx)
{
char *line;
int line_len;
@@ -2810,8 +2975,8 @@ int mbulk_resp_loop_raw(RedisSock *redis_sock, zval *z_result,
}
/* MULTI BULK response where we unserialize everything */
-int mbulk_resp_loop(RedisSock *redis_sock, zval *z_result,
- long long count, void *ctx)
+static int mbulk_resp_loop(RedisSock *redis_sock, zval *z_result,
+ long long count, void *ctx)
{
char *line;
int line_len;
@@ -2823,11 +2988,8 @@ int mbulk_resp_loop(RedisSock *redis_sock, zval *z_result,
if (line != NULL) {
zval z_unpacked;
- if (redis_unpack(redis_sock, line, line_len, &z_unpacked)) {
- add_next_index_zval(z_result, &z_unpacked);
- } else {
- add_next_index_stringl(z_result, line, line_len);
- }
+ redis_unpack(redis_sock, line, line_len, &z_unpacked);
+ add_next_index_zval(z_result, &z_unpacked);
efree(line);
} else {
add_next_index_bool(z_result, 0);
@@ -2838,12 +3000,12 @@ int mbulk_resp_loop(RedisSock *redis_sock, zval *z_result,
}
/* MULTI BULK response where we turn key1,value1 into key1=>value1 */
-int mbulk_resp_loop_zipstr(RedisSock *redis_sock, zval *z_result,
- long long count, void *ctx)
+static int mbulk_resp_loop_zipstr(RedisSock *redis_sock, zval *z_result,
+ long long count, void *ctx)
{
char *line, *key = NULL;
- int line_len, key_len = 0;
long long idx = 0;
+ int line_len;
// Our count will need to be divisible by 2
if (count % 2 != 0) {
@@ -2859,15 +3021,11 @@ int mbulk_resp_loop_zipstr(RedisSock *redis_sock, zval *z_result,
if (idx++ % 2 == 0) {
// Save our key and length
key = line;
- key_len = line_len;
} else {
/* Attempt unpacking */
zval z_unpacked;
- if (redis_unpack(redis_sock, line, line_len, &z_unpacked)) {
- add_assoc_zval(z_result, key, &z_unpacked);
- } else {
- add_assoc_stringl_ex(z_result, key, key_len, line, line_len);
- }
+ redis_unpack(redis_sock, line, line_len, &z_unpacked);
+ add_assoc_zval(z_result, key, &z_unpacked);
efree(line);
efree(key);
@@ -2878,8 +3036,8 @@ int mbulk_resp_loop_zipstr(RedisSock *redis_sock, zval *z_result,
}
/* MULTI BULK loop processor where we expect key,score key, score */
-int mbulk_resp_loop_zipdbl(RedisSock *redis_sock, zval *z_result,
- long long count, void *ctx)
+static int mbulk_resp_loop_zipdbl(RedisSock *redis_sock, zval *z_result,
+ long long count, void *ctx)
{
char *line, *key = NULL;
int line_len, key_len = 0;
@@ -2899,14 +3057,11 @@ int mbulk_resp_loop_zipdbl(RedisSock *redis_sock, zval *z_result,
key_len = line_len;
} else {
zval zv, *z = &zv;
- if (redis_unpack(redis_sock,key,key_len, z)) {
- zend_string *zstr = zval_get_string(z);
- add_assoc_double_ex(z_result, ZSTR_VAL(zstr), ZSTR_LEN(zstr), atof(line));
- zend_string_release(zstr);
- zval_dtor(z);
- } else {
- add_assoc_double_ex(z_result, key, key_len, atof(line));
- }
+ redis_unpack(redis_sock,key,key_len, z);
+ zend_string *tmp, *zstr = zval_get_tmp_string(z, &tmp);
+ add_assoc_double_ex(z_result, ZSTR_VAL(zstr), ZSTR_LEN(zstr), atof(line));
+ zend_tmp_string_release(tmp);
+ zval_ptr_dtor_nogc(z);
/* Free our key and line */
efree(key);
@@ -2919,39 +3074,28 @@ int mbulk_resp_loop_zipdbl(RedisSock *redis_sock, zval *z_result,
}
/* MULTI BULK where we're passed the keys, and we attach vals */
-int mbulk_resp_loop_assoc(RedisSock *redis_sock, zval *z_result,
- long long count, void *ctx)
+static int mbulk_resp_loop_assoc(RedisSock *redis_sock, zval *z_result,
+ long long count, void *ctx)
{
+ zval *zfield, z_unpacked;
+ HashTable *htctx = ctx;
+ int line_len;
char *line;
- int line_len, i;
- zval *z_keys = ctx;
- // Loop while we've got replies
- for (i = 0; i < count; ++i) {
- zend_string *zstr = zval_get_string(&z_keys[i]);
+ ZEND_HASH_FOREACH_VAL(htctx, zfield) {
line = redis_sock_read(redis_sock, &line_len);
-
if (line != NULL) {
- zval z_unpacked;
- if (redis_unpack(redis_sock, line, line_len, &z_unpacked)) {
- add_assoc_zval_ex(z_result, ZSTR_VAL(zstr), ZSTR_LEN(zstr), &z_unpacked);
- } else {
- add_assoc_stringl_ex(z_result, ZSTR_VAL(zstr), ZSTR_LEN(zstr), line, line_len);
- }
+ redis_unpack(redis_sock, line, line_len, &z_unpacked);
efree(line);
} else {
- add_assoc_bool_ex(z_result, ZSTR_VAL(zstr), ZSTR_LEN(zstr), 0);
+ ZVAL_FALSE(&z_unpacked);
}
- // Clean up key context
- zend_string_release(zstr);
- zval_dtor(&z_keys[i]);
- }
+ ZVAL_COPY_VALUE(zfield, &z_unpacked);
+ } ZEND_HASH_FOREACH_END();
- // Clean up our keys overall
- efree(z_keys);
+ ZVAL_ARR(z_result, htctx);
- // Success!
return SUCCESS;
}
@@ -2974,7 +3118,7 @@ static zend_string **get_valid_seeds(HashTable *input, uint32_t *nseeds) {
zval *z_seed;
zend_string *zkey, **seeds = NULL;
- /* Short circuit if we don't have any sees */
+ /* Short circuit if we don't have any seeds */
count = zend_hash_num_elements(input);
if (count == 0)
return NULL;
@@ -2995,7 +3139,7 @@ static zend_string **get_valid_seeds(HashTable *input, uint32_t *nseeds) {
}
/* Add as a key to avoid duplicates */
- zend_hash_str_update_ptr(valid, Z_STRVAL_P(z_seed), Z_STRLEN_P(z_seed), NULL);
+ zend_hash_str_add_empty_element(valid, Z_STRVAL_P(z_seed), Z_STRLEN_P(z_seed));
} ZEND_HASH_FOREACH_END();
/* We need at least one valid seed */
@@ -3006,6 +3150,10 @@ static zend_string **get_valid_seeds(HashTable *input, uint32_t *nseeds) {
/* Populate our return array */
seeds = ecalloc(count, sizeof(*seeds));
ZEND_HASH_FOREACH_STR_KEY(valid, zkey) {
+ /* Should not actually be possible but satisfy static analyzer */
+ if (zkey == NULL) {
+ zend_error_noreturn(E_ERROR, "Invalid seed key in valid seeds hash");
+ }
seeds[idx++] = zend_string_copy(zkey);
} ZEND_HASH_FOREACH_END();
@@ -3112,7 +3260,14 @@ PHP_REDIS_API redisCachedCluster *cluster_cache_load(zend_string *hash) {
PHP_REDIS_API void cluster_cache_store(zend_string *hash, HashTable *nodes) {
redisCachedCluster *cc = cluster_cache_create(hash, nodes);
- redis_register_persistent_resource(cc->hash, cc, le_cluster_slot_cache);
+ zend_register_persistent_resource_ex(cc->hash, cc, le_cluster_slot_cache);
+}
+
+void cluster_cache_clear(redisCluster *c)
+{
+ if (c->cache_key) {
+ zend_hash_del(&EG(persistent_list), c->cache_key);
+ }
}
diff --git a/cluster_library.h b/cluster_library.h
index eb2b1531b8..361a1e5dad 100644
--- a/cluster_library.h
+++ b/cluster_library.h
@@ -116,7 +116,7 @@
mc->args.len = 0; \
mc->argc = 0; \
-/* Initialzie a clusterMultiCmd with a keyword and length */
+/* Initialize a clusterMultiCmd with a keyword and length */
#define CLUSTER_MULTI_INIT(mc, keyword, keyword_len) \
mc.kw = keyword; \
mc.kw_len = keyword_len; \
@@ -264,6 +264,8 @@ struct clusterFoldItem {
/* Next item in our list */
struct clusterFoldItem *next;
+
+ uint8_t flags;
};
/* Key and value container, with info if they need freeing */
@@ -376,7 +378,7 @@ PHP_REDIS_API redisCluster *cluster_create(double timeout, double read_timeout,
int failover, int persistent);
PHP_REDIS_API void cluster_free(redisCluster *c, int free_ctx);
PHP_REDIS_API void cluster_init_seeds(redisCluster *c, zend_string **seeds, uint32_t nseeds);
-PHP_REDIS_API int cluster_map_keyspace(redisCluster *c);
+REDIS_NODISCARD PHP_REDIS_API int cluster_map_keyspace(redisCluster *c);
PHP_REDIS_API void cluster_free_node(redisClusterNode *node);
/* Functions for interacting with cached slots maps */
@@ -390,6 +392,7 @@ PHP_REDIS_API char **cluster_sock_read_multibulk_reply(RedisSock *redis_sock, in
PHP_REDIS_API void cluster_cache_store(zend_string *hash, HashTable *nodes);
PHP_REDIS_API redisCachedCluster *cluster_cache_load(zend_string *hash);
+void cluster_cache_clear(redisCluster *c);
/*
* Redis Cluster response handlers. Our response handlers generally take the
@@ -419,7 +422,7 @@ PHP_REDIS_API void cluster_zadd_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster
void *ctx);
PHP_REDIS_API void cluster_zrandmember_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *c,
void *ctx);
-PHP_REDIS_API void cluster_srandmember_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *c,
+PHP_REDIS_API void cluster_randmember_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *c,
void *ctx);
PHP_REDIS_API void cluster_set_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *c,
void *ctx);
@@ -429,6 +432,8 @@ PHP_REDIS_API void cluster_single_line_resp(INTERNAL_FUNCTION_PARAMETERS, redisC
void *ctx);
PHP_REDIS_API void cluster_bulk_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *c,
void *ctx);
+PHP_REDIS_API void cluster_bulk_withmeta_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *c,
+ void *ctx);
PHP_REDIS_API void cluster_bulk_raw_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *c,
void *ctx);
PHP_REDIS_API void cluster_dbl_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *c,
@@ -443,6 +448,14 @@ PHP_REDIS_API void cluster_sub_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *
void *ctx);
PHP_REDIS_API void cluster_unsub_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *c,
void *ctx);
+PHP_REDIS_API void cluster_vemb_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *c,
+ void *ctx);
+PHP_REDIS_API void cluster_vinfo_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *c,
+ void *ctx);
+PHP_REDIS_API void cluster_vlinks_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *c,
+ void *ctx);
+PHP_REDIS_API void cluster_vgetattr_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *c,
+ void *ctx);
PHP_REDIS_API void cluster_zrange_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *c,
void *ctx);
@@ -457,8 +470,6 @@ PHP_REDIS_API void cluster_variant_resp_strings(INTERNAL_FUNCTION_PARAMETERS,
redisCluster *c, void *ctx);
/* MULTI BULK response functions */
-PHP_REDIS_API void cluster_gen_mbulk_resp(INTERNAL_FUNCTION_PARAMETERS,
- redisCluster *c, mbulk_cb func, void *ctx);
PHP_REDIS_API void cluster_mbulk_raw_resp(INTERNAL_FUNCTION_PARAMETERS,
redisCluster *c, void *ctx);
PHP_REDIS_API void cluster_mbulk_resp(INTERNAL_FUNCTION_PARAMETERS,
@@ -488,7 +499,7 @@ PHP_REDIS_API void cluster_msetnx_resp(INTERNAL_FUNCTION_PARAMETERS,
/* Response handler for ZSCAN, SSCAN, and HSCAN */
PHP_REDIS_API int cluster_scan_resp(INTERNAL_FUNCTION_PARAMETERS,
- redisCluster *c, REDIS_SCAN_TYPE type, long *it);
+ redisCluster *c, REDIS_SCAN_TYPE type, uint64_t *cursor);
/* INFO response handler */
PHP_REDIS_API void cluster_info_resp(INTERNAL_FUNCTION_PARAMETERS,
@@ -515,20 +526,6 @@ PHP_REDIS_API void cluster_mpop_resp(INTERNAL_FUNCTION_PARAMETERS,
PHP_REDIS_API void cluster_acl_getuser_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *c, void *ctx);
PHP_REDIS_API void cluster_acl_log_resp(INTERNAL_FUNCTION_PARAMETERS, redisCluster *c, void *ctx);
-/* MULTI BULK processing callbacks */
-int mbulk_resp_loop(RedisSock *redis_sock, zval *z_result,
- long long count, void *ctx);
-int mbulk_resp_loop_raw(RedisSock *redis_sock, zval *z_result,
- long long count, void *ctx);
-int mbulk_resp_loop_zipstr(RedisSock *redis_sock, zval *z_result,
- long long count, void *ctx);
-int mbulk_resp_loop_dbl(RedisSock *redis_sock, zval *z_result,
- long long count, void *ctx);
-int mbulk_resp_loop_zipdbl(RedisSock *redis_sock, zval *z_result,
- long long count, void *ctx);
-int mbulk_resp_loop_assoc(RedisSock *redis_sock, zval *z_result,
- long long count, void *ctx);
-
#endif
/* vim: set tabstop=4 softtabstop=4 expandtab shiftwidth=4: */
diff --git a/common.h b/common.h
index 8e2ec57ab8..27e79d600d 100644
--- a/common.h
+++ b/common.h
@@ -11,7 +11,7 @@
#include
#include
#include
-#include
+#include
#define PHPREDIS_GET_OBJECT(class_entry, o) (class_entry *)((char *)o - XtOffsetOf(class_entry, std))
#define PHPREDIS_ZVAL_GET_OBJECT(class_entry, z) PHPREDIS_GET_OBJECT(class_entry, Z_OBJ_P(z))
@@ -31,6 +31,43 @@
#define NULL ((void *) 0)
#endif
+#if defined(_WIN32) || defined(_WIN64)
+# define PHPREDIS_LITTLE_ENDIAN
+#elif defined(__BYTE_ORDER__) && (__BYTE_ORDER__ == __ORDER_BIG_ENDIAN__)
+# define PHPREDIS_BIG_ENDIAN
+#elif defined(__BYTE_ORDER__) && (__BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__)
+# define PHPREDIS_LITTLE_ENDIAN
+#else
+# error "Unknown endianness"
+#endif
+
+#if defined(_MSC_VER) && !defined(__clang__)
+# define REDIS_MSVC 1
+#endif
+
+#ifndef REDIS_MSVC
+# ifndef REDIS_NODISCARD
+# if defined(__has_c_attribute)
+# if __has_c_attribute(nodiscard)
+# define REDIS_NODISCARD [[nodiscard]]
+# endif
+# endif
+# endif
+# ifndef REDIS_NODISCARD
+# if defined(__has_attribute)
+# if __has_attribute(warn_unused_result)
+# define REDIS_NODISCARD __attribute__((warn_unused_result))
+# endif
+# elif defined(__GNUC__) || defined(__clang__)
+# define REDIS_NODISCARD __attribute__((warn_unused_result))
+# endif
+# endif
+#endif /* ifndef REDIS_MSVC */
+
+#ifndef REDIS_NODISCARD
+# define REDIS_NODISCARD
+#endif
+
#include "backoff.h"
typedef enum {
@@ -51,6 +88,7 @@ typedef enum {
#define REDIS_ZSET 4
#define REDIS_HASH 5
#define REDIS_STREAM 6
+#define REDIS_VECTORSET 7
#ifdef PHP_WIN32
#define PHP_REDIS_API __declspec(dllexport)
@@ -91,20 +129,21 @@ typedef enum _PUBSUB_TYPE {
#define REDIS_SUBS_BUCKETS 3
/* options */
-#define REDIS_OPT_SERIALIZER 1
-#define REDIS_OPT_PREFIX 2
-#define REDIS_OPT_READ_TIMEOUT 3
-#define REDIS_OPT_SCAN 4
-#define REDIS_OPT_FAILOVER 5
-#define REDIS_OPT_TCP_KEEPALIVE 6
-#define REDIS_OPT_COMPRESSION 7
-#define REDIS_OPT_REPLY_LITERAL 8
-#define REDIS_OPT_COMPRESSION_LEVEL 9
-#define REDIS_OPT_NULL_MBULK_AS_NULL 10
-#define REDIS_OPT_MAX_RETRIES 11
-#define REDIS_OPT_BACKOFF_ALGORITHM 12
-#define REDIS_OPT_BACKOFF_BASE 13
-#define REDIS_OPT_BACKOFF_CAP 14
+#define REDIS_OPT_SERIALIZER 1
+#define REDIS_OPT_PREFIX 2
+#define REDIS_OPT_READ_TIMEOUT 3
+#define REDIS_OPT_SCAN 4
+#define REDIS_OPT_FAILOVER 5
+#define REDIS_OPT_TCP_KEEPALIVE 6
+#define REDIS_OPT_COMPRESSION 7
+#define REDIS_OPT_REPLY_LITERAL 8
+#define REDIS_OPT_COMPRESSION_LEVEL 9
+#define REDIS_OPT_NULL_MBULK_AS_NULL 10
+#define REDIS_OPT_MAX_RETRIES 11
+#define REDIS_OPT_BACKOFF_ALGORITHM 12
+#define REDIS_OPT_BACKOFF_BASE 13
+#define REDIS_OPT_BACKOFF_CAP 14
+#define REDIS_OPT_PACK_IGNORE_NUMBERS 15
/* cluster options */
#define REDIS_FAILOVER_NONE 0
@@ -176,89 +215,6 @@ typedef enum {
#define IS_MULTI(redis_sock) (redis_sock->mode & MULTI)
#define IS_PIPELINE(redis_sock) (redis_sock->mode & PIPELINE)
-#define PIPELINE_ENQUEUE_COMMAND(cmd, cmd_len) do { \
- if (redis_sock->pipeline_cmd == NULL) { \
- redis_sock->pipeline_cmd = zend_string_init(cmd, cmd_len, 0); \
- } else { \
- size_t pipeline_len = ZSTR_LEN(redis_sock->pipeline_cmd); \
- redis_sock->pipeline_cmd = zend_string_realloc(redis_sock->pipeline_cmd, pipeline_len + cmd_len, 0); \
- memcpy(&ZSTR_VAL(redis_sock->pipeline_cmd)[pipeline_len], cmd, cmd_len); \
- } \
-} while (0)
-
-#define SOCKET_WRITE_COMMAND(redis_sock, cmd, cmd_len) \
- if(redis_sock_write(redis_sock, cmd, cmd_len) < 0) { \
- efree(cmd); \
- RETURN_FALSE; \
-}
-
-#define REDIS_SAVE_CALLBACK(callback, closure_context) do { \
- fold_item *fi = malloc(sizeof(fold_item)); \
- fi->fun = callback; \
- fi->ctx = closure_context; \
- fi->next = NULL; \
- if (redis_sock->current) { \
- redis_sock->current->next = fi; \
- } \
- redis_sock->current = fi; \
- if (NULL == redis_sock->head) { \
- redis_sock->head = redis_sock->current; \
- } \
-} while (0)
-
-#define REDIS_PROCESS_REQUEST(redis_sock, cmd, cmd_len) \
- if (IS_PIPELINE(redis_sock)) { \
- PIPELINE_ENQUEUE_COMMAND(cmd, cmd_len); \
- } else { \
- SOCKET_WRITE_COMMAND(redis_sock, cmd, cmd_len); \
- } \
- efree(cmd);
-
-#define REDIS_PROCESS_RESPONSE_CLOSURE(function, closure_context) \
- if (!IS_PIPELINE(redis_sock)) { \
- if (redis_response_enqueued(redis_sock) != SUCCESS) { \
- RETURN_FALSE; \
- } \
- } \
- REDIS_SAVE_CALLBACK(function, closure_context); \
- RETURN_ZVAL(getThis(), 1, 0); \
-
-#define REDIS_PROCESS_RESPONSE(function) else { \
- REDIS_PROCESS_RESPONSE_CLOSURE(function, NULL) \
-}
-
-/* Process a command assuming our command where our command building
- * function is redis__cmd */
-#define REDIS_PROCESS_CMD(cmdname, resp_func) \
- RedisSock *redis_sock; char *cmd; int cmd_len; void *ctx=NULL; \
- if ((redis_sock = redis_sock_get(getThis(), 0)) == NULL || \
- redis_##cmdname##_cmd(INTERNAL_FUNCTION_PARAM_PASSTHRU,redis_sock, \
- &cmd, &cmd_len, NULL, &ctx)==FAILURE) { \
- RETURN_FALSE; \
- } \
- REDIS_PROCESS_REQUEST(redis_sock, cmd, cmd_len); \
- if (IS_ATOMIC(redis_sock)) { \
- resp_func(INTERNAL_FUNCTION_PARAM_PASSTHRU, redis_sock, NULL, ctx); \
- } else { \
- REDIS_PROCESS_RESPONSE_CLOSURE(resp_func, ctx) \
- }
-
-/* Process a command but with a specific command building function
- * and keyword which is passed to us*/
-#define REDIS_PROCESS_KW_CMD(kw, cmdfunc, resp_func) \
- RedisSock *redis_sock; char *cmd; int cmd_len; void *ctx=NULL; \
- if ((redis_sock = redis_sock_get(getThis(), 0)) == NULL || \
- cmdfunc(INTERNAL_FUNCTION_PARAM_PASSTHRU, redis_sock, kw, &cmd, \
- &cmd_len, NULL, &ctx)==FAILURE) { \
- RETURN_FALSE; \
- } \
- REDIS_PROCESS_REQUEST(redis_sock, cmd, cmd_len); \
- if (IS_ATOMIC(redis_sock)) { \
- resp_func(INTERNAL_FUNCTION_PARAM_PASSTHRU, redis_sock, NULL, ctx); \
- } else { \
- REDIS_PROCESS_RESPONSE_CLOSURE(resp_func, ctx) \
- }
-
/* Case sensitive compare against compile-time static string */
#define REDIS_STRCMP_STATIC(s, len, sstr) \
(len == sizeof(sstr) - 1 && !strncmp(s, sstr, len))
@@ -267,6 +223,16 @@ typedef enum {
#define REDIS_STRICMP_STATIC(s, len, sstr) \
(len == sizeof(sstr) - 1 && !strncasecmp(s, sstr, len))
+/* On some versions of glibc strncmp and strncasecmp can be a macro a macro.
+ * This wrapper allows us to use it in combination with ZEND_STRL in those
+ * cases. */
+static inline int redis_strncmp(const char *s1, const char *s2, size_t n) {
+ return strncmp(s1, s2, n);
+}
+static inline int redis_strncasecmp(const char *s1, const char *s2, size_t n) {
+ return strncasecmp(s1, s2, n);
+}
+
/* Test if a zval is a string and (case insensitive) matches a static string */
#define ZVAL_STRICMP_STATIC(zv, sstr) \
REDIS_STRICMP_STATIC(Z_STRVAL_P(zv), Z_STRLEN_P(zv), sstr)
@@ -275,9 +241,6 @@ typedef enum {
#define ZSTR_STRICMP_STATIC(zs, sstr) \
REDIS_STRICMP_STATIC(ZSTR_VAL(zs), ZSTR_LEN(zs), sstr)
-#define REDIS_ENABLE_MODE(redis_sock, m) (redis_sock->mode |= m)
-#define REDIS_DISABLE_MODE(redis_sock, m) (redis_sock->mode &= ~m)
-
/* HOST_NAME_MAX doesn't exist everywhere */
#ifndef HOST_NAME_MAX
#if defined(_POSIX_HOST_NAME_MAX)
@@ -294,59 +257,66 @@ typedef enum {
#define RESP_EXEC_CMD "*1\r\n$4\r\nEXEC\r\n"
#define RESP_DISCARD_CMD "*1\r\n$7\r\nDISCARD\r\n"
+typedef struct RedisHello {
+ zend_string *server;
+ zend_string *version;
+} RedisHello;
+
/* {{{ struct RedisSock */
typedef struct {
php_stream *stream;
- php_stream_context *stream_ctx;
zend_string *host;
int port;
zend_string *user;
zend_string *pass;
+ HashTable *context;
double timeout;
double read_timeout;
long retry_interval;
int max_retries;
struct RedisBackoff backoff;
redis_sock_status status;
- int persistent;
- int watching;
+ zend_bool persistent;
+ zend_bool watching;
zend_string *persistent_id;
HashTable *subs[REDIS_SUBS_BUCKETS];
redis_serializer serializer;
+ zend_bool pack_ignore_numbers;
int compression;
int compression_level;
long dbNumber;
-
zend_string *prefix;
-
+ struct RedisHello hello;
short mode;
- struct fold_item *head;
- struct fold_item *current;
-
- zend_string *pipeline_cmd;
+ struct fold_item *reply_callback;
+ size_t reply_callback_count;
+ size_t reply_callback_capacity;
+ smart_string pipeline_cmd;
zend_string *err;
-
int scan;
- int readonly;
- int reply_literal;
- int null_mbulk_as_null;
- int tcp_keepalive;
- int sentinel;
+ zend_bool readonly;
+ zend_bool reply_literal;
+ zend_bool null_mbulk_as_null;
+ zend_bool tcp_keepalive;
+ zend_bool sentinel;
size_t txBytes;
size_t rxBytes;
+ uint8_t flags;
} RedisSock;
/* }}} */
/* Redis response handler function callback prototype */
-typedef void (*ResultCallback)(INTERNAL_FUNCTION_PARAMETERS, RedisSock *redis_sock, zval *z_tab, void *ctx);
-typedef int (*FailableResultCallback)(INTERNAL_FUNCTION_PARAMETERS, RedisSock*, zval*, void*);
+typedef void (*ResultCallback)(INTERNAL_FUNCTION_PARAMETERS,
+ RedisSock *redis_sock, zval *z_tab, void *ctx);
+typedef int (*FailableResultCallback)(INTERNAL_FUNCTION_PARAMETERS,
+ RedisSock*, zval*, void*);
typedef struct fold_item {
FailableResultCallback fun;
+ uint8_t flags;
void *ctx;
- struct fold_item *next;
} fold_item;
typedef struct {
diff --git a/composer.json b/composer.json
new file mode 100644
index 0000000000..dd4d00af0c
--- /dev/null
+++ b/composer.json
@@ -0,0 +1,63 @@
+
+{
+ "name": "phpredis/phpredis",
+ "type": "php-ext",
+ "license": "PHP-3.01",
+ "description": "A PHP extension for Redis",
+ "require": {
+ "php": ">= 7.4.0"
+ },
+ "php-ext": {
+ "extension-name": "redis",
+ "configure-options": [
+ {
+ "name": "enable-redis",
+ "description": "Enable redis support"
+ },
+ {
+ "name": "disable-redis-session",
+ "description": "Disable session support"
+ },
+ {
+ "name": "disable-redis-json",
+ "description": "Disable json serializer support"
+ },
+ {
+ "name": "enable-redis-igbinary",
+ "description": "Enable igbinary serializer support"
+ },
+ {
+ "name": "enable-redis-msgpack",
+ "description": "Enable msgpack serializer support"
+ },
+ {
+ "name": "enable-redis-lzf",
+ "description": "Enable lzf compression support"
+ },
+ {
+ "name": "with-liblzf",
+ "description": "Use system liblzf",
+ "needs-value": true
+ },
+ {
+ "name": "enable-redis-zstd",
+ "description": "Enable Zstd compression support"
+ },
+ {
+ "name": "with-libzstd",
+ "description": "Use system libzstd",
+ "needs-value": true
+ },
+ {
+ "name": "enable-redis-lz4",
+ "description": "Enable lz4 compression support"
+ },
+ {
+ "name": "with-liblz4",
+ "description": "Use system liblz4",
+ "needs-value": true
+ }
+ ],
+ "priority": 60
+ }
+}
diff --git a/config.m4 b/config.m4
index 2ba4a8b51d..c84ce1e99f 100644
--- a/config.m4
+++ b/config.m4
@@ -221,6 +221,7 @@ if test "$PHP_REDIS" != "no"; then
PHP_CHECK_LIBRARY(lzf, lzf_compress,
[
PHP_ADD_LIBRARY_WITH_PATH(lzf, $LIBLZF_DIR/$PHP_LIBDIR, REDIS_SHARED_LIBADD)
+ PHP_ADD_INCLUDE($LIBLZF_DIR/include)
], [
AC_MSG_ERROR([could not find usable liblzf])
], [
@@ -263,12 +264,12 @@ if test "$PHP_REDIS" != "no"; then
PHP_CHECK_LIBRARY(lz4, LZ4_compress,
[
PHP_ADD_LIBRARY_WITH_PATH(lz4, $LIBLZ4_DIR/$PHP_LIBDIR, REDIS_SHARED_LIBADD)
+ PHP_ADD_INCLUDE($LIBLZ4_DIR/include)
], [
AC_MSG_ERROR([could not find usable liblz4])
], [
-L$LIBLZ4_DIR/$PHP_LIBDIR
])
- PHP_SUBST(REDIS_SHARED_LIBADD)
else
AC_MSG_ERROR([only system liblz4 is supported])
fi
@@ -307,6 +308,7 @@ if test "$PHP_REDIS" != "no"; then
PHP_CHECK_LIBRARY(zstd, ZSTD_getFrameContentSize,
[
PHP_ADD_LIBRARY_WITH_PATH(zstd, $LIBZSTD_DIR/$PHP_LIBDIR, REDIS_SHARED_LIBADD)
+ PHP_ADD_INCLUDE($LIBZSTD_DIR/include)
], [
AC_MSG_ERROR([could not find usable libzstd, version 1.3.0 required])
], [
diff --git a/docs/DOCTUM_VERSION b/docs/DOCTUM_VERSION
index d41f08f1f3..0413736d69 100644
--- a/docs/DOCTUM_VERSION
+++ b/docs/DOCTUM_VERSION
@@ -1 +1 @@
-5.5.1
\ No newline at end of file
+5.5.4
\ No newline at end of file
diff --git a/docs/PROJECT_VERSION b/docs/PROJECT_VERSION
index 6563189c54..ce57f64563 100644
--- a/docs/PROJECT_VERSION
+++ b/docs/PROJECT_VERSION
@@ -1 +1 @@
-develop
+develop
\ No newline at end of file
diff --git a/docs/Redis.html b/docs/Redis.html
index a74aa2d48f..009c813d0a 100644
--- a/docs/Redis.html
+++ b/docs/Redis.html
@@ -5,7 +5,7 @@
Redis | PhpRedis API
-
+
@@ -16,11 +16,400 @@
+
+
+
+
+ title="PhpRedis API (develop)" />
@@ -83,7 +472,7 @@
Returned by \Redis::type() when the key does not exist or has a type
+we are not familiar with.
+
+
+
+
+
+ REDIS_STRING
+
+
+
Returned by \Redis::type() when the key is a string.
+
+
+
+
+
+ REDIS_SET
+
+
+
Returned by \Redis::type() when the key is a set.
+
+
+
+
+
+ REDIS_LIST
+
+
+
Returned by \Redis::type() when the key is a list.
+
+
+
+
+
+ REDIS_ZSET
+
+
+
Returned by \Redis::type() when the key is a sorted set.
+
+
+
+
+
+ REDIS_HASH
+
+
+
Returned by \Redis::type() when the key is a hash.
+
+
+
+
+
+ REDIS_STREAM
+
+
+
Returned by \Redis::type() when the key is a stream.
+
+
+
+
+
+ REDIS_VECTORSET
+
+
+
Returned by \Redis::type() when the key is a vector set.
+
+
+
+
+
+ ATOMIC
+
+
+
Returned from \Redis::getMode() when we're not in a multi or pipeline
+transaction.
+
+
+
+
+
+ MULTI
+
+
+
Returned from \Redis::getMode() when we're in a multi transaction.
+
+
+
+
+
+ PIPELINE
+
+
+
Returned from \Redis::getMode() when we're in a pipeline transaction.
+
+
+
+
+
+ OPT_SERIALIZER
+
+
+
Used with \Redis::setOption() to specify the serializer to use
+
+
+
+
+
+ OPT_PREFIX
+
+
+
Used to set an automatic prefix for keys used in commands.
+
+
+
+
+
+ OPT_READ_TIMEOUT
+
+
+
Used to set the read timeout for the connection.
+
+
+
+
+
+ OPT_TCP_KEEPALIVE
+
+
+
Used to enable or disable TCP keepalive on the connection.
+
+
+
+
+
+ OPT_COMPRESSION
+
+
+
Used to set the compression algorithm to use for compressing
+
+
+
+
+
+ OPT_REPLY_LITERAL
+
+
+
Causes PhpRedis to return the actual string in +OK style responses
+from Redis. If disabled those replies are just converted to boolean
+true.
+
+
+
+
+
+ OPT_COMPRESSION_LEVEL
+
+
+
Used to specify the compression level to use when compressing data.
+
+
+
+
+
+ OPT_NULL_MULTIBULK_AS_NULL
+
+
+
Tells PhpRedis to return a NULL multi-bulk (*-1\r\n) response
+as null as opposed to an empty array.
+
+
+
+
+
+ OPT_PACK_IGNORE_NUMBERS
+
+
+
When enabled, this option tells PhpRedis to ignore purely numeric values
+when packing and unpacking data. This does not include numeric strings.
+
If you want numeric strings to be ignored, typecast them to an int or
+float.
+
The primary purpose of this option is to make it more ergonomic when
+setting keys that will later be incremented or decremented.
+
Note: This option incurs a small performance penalty when reading data
+because we have to see if the data is a string representation of an int
+or float.
+
+
+
+
+ SERIALIZER_NONE
+
+
+
Sets the serializer to none (no serialization).
+
+
+
+
+
+ SERIALIZER_PHP
+
+
+
Sets the serializer to PHP's built-in serialize()/unserialize()
+
+
+
+
+
+ SERIALIZER_IGBINARY
+
+
+
Sets the serializer to igbinary. Note that phpredis must be compiled
+with ighbinary support to use this serializer.
+
+
+
+
+
+ SERIALIZER_MSGPACK
+
+
+
Sets the serializer to msgpack. Note that phpredis must be compiled
+with msgpack support to use this serializer.
+
+
+
+
+
+ SERIALIZER_JSON
+
+
+
Sets the serializer to JSON.
+
+
+
+
+
+ COMPRESSION_NONE
+
+
+
Disables compression.
+
+
+
+
+
+ COMPRESSION_LZF
+
+
+
Sets the compression algorithm to LZF. PhpRedis must be compiled with
+lzf support but this serializer is bundled with the extension.
+
+
+
+
+
+ COMPRESSION_ZSTD
+
+
+
Sets the compression algorithm to ZSTD. PhpRedis must be compiled with
+zstd support to use this serializer. This is often the best balance
+between speed and compression ratio.
+
+
+
+
+
+ COMPRESSION_ZSTD_DEFAULT
+
+
+
This constant represents the "default" compression level for ZSTD. If
+PhpRedis is compiled against a new enough ZSTD the value comes from the
+library, otherwise we just set it to 3.
+
+
+
+
+
+ COMPRESSION_ZSTD_MIN
+
+
+
The minimum compression level ZSTD supports, which comes from the
+underlying ZSTD library if new enough. Otherwise we just set it to 1.
+
+
+
+
+
+ COMPRESSION_ZSTD_MAX
+
+
+
The maximum compression level ZSTD supports, which comes from the
+underlying ZSTD library.
+
+
+
+
+
+ COMPRESSION_LZ4
+
+
+
Set the compression algorithm to LZ4. PhpRedis must be compiled with
+lz4 support to use this serializer. This algorithm is generally
+the fastest but has a lower compression ratio than ZSTD.
+
+
+
+
+
+ OPT_SCAN
+
+
+
Used with \Redis::setOption() to specify scan options.
+
+
+
+
+
+ SCAN_RETRY
+
+
+
When enabled, this option causes PhpRedis to automatically retry SCAN
+commands when Redis returns a non-zero cursor but no keys. This can
+happen due to the nature of Redis' scanning algorithm.
+
+
+
+
+
+ SCAN_NORETRY
+
+
+
Then enabled, this option tells PhpRedis to not retry SCAN commands
+when Redis returns a non-zero cursor but no keys. This means that your
+code must handle this case itself.
+
+
+
+
+
+ SCAN_PREFIX
+
+
+
Tells PhpRedis to prefix keys returned from SCAN commands with the
+currently set key prefix.
+
+
+
+
+
+ SCAN_NOPREFIX
+
+
+
Tells PhpRedis to NOT prefix keys returned from SCAN commands with
+the currently set key prefix.
+
+
+
+
+
+ BEFORE
+
+
+
This is just the string "before" which is used with various list
+commands to indicate an insertion point.
+
+
+
+
+
+ AFTER
+
+
+
This is just the string "after" which is used with various list commands
+to indicate an insertion point.
+
+
+
+
+
+ LEFT
+
+
+
This is just the string "left" which is used with various list commands
+such as LMOVE.
+
+
+
+
+
+ RIGHT
+
+
+
This is just the string "right" which is used with various list commands
+such as LMOVE.
+
+
+
+
+
+ OPT_MAX_RETRIES
+
+
+
How many times should PhpRedis attempt to reconnect when we are
+disconnected.
+
+
+
+
+
+ OPT_BACKOFF_ALGORITHM
+
+
+
Used to specify the backoff algorithm to use when reconnecting.
+
+
+
+
+
+ BACKOFF_ALGORITHM_DEFAULT
+
+
+
Default backoff - random delay before the first retry, then constant base ms.
+
+
+
+
+
+ BACKOFF_ALGORITHM_CONSTANT
+
+
+
Constant backoff - always sleep for exactly base ms (capped by cap).
+
+
+
+
+
+ BACKOFF_ALGORITHM_UNIFORM
+
+
+
Uniform backoff - randomly sleep between 0 and base ms for each retry.
+
+
+
+
+
+ BACKOFF_ALGORITHM_EXPONENTIAL
+
+
+
Exponential backoff - doubles the delay every retry (up to 2^10) before cap.
+
+
+
+
+
+ BACKOFF_ALGORITHM_FULL_JITTER
+
+
+
Full jitter - exponential delay but pick a random value between 0 and that delay.
+
+
+
+
+
+ BACKOFF_ALGORITHM_EQUAL_JITTER
+
+
+
Equal jitter - half the exponential delay plus a random amount up to the other half.
+
+
+
+
+
+ BACKOFF_ALGORITHM_DECORRELATED_JITTER
+
+
+
Decorrelated jitter - pick a random delay between base and 3x the previous delay.
+
+
+
+
+
+ OPT_BACKOFF_BASE
+
+
+
Backoff base - minimum delay in milliseconds that algorithms start from.
+
+
+
+
+
+ OPT_BACKOFF_CAP
+
+
+
Backoff cap - maximum delay in milliseconds that any algorithm can reach.
Create a new Redis instance. If passed sufficient information in the
options array it is also possible to connect to an instance at the same
@@ -116,8 +1010,7 @@
Pack the provided value with the configured serializer and compressor
-as set with Redis::setOption().
+
Pack the provided value by first serializing it (if Redis::OPT_SERIALIZER is set)
+and then compressing the serialized payload (if Redis::OPT_COMPRESSION is set),
+mirroring exactly what PhpRedis transmits to Redis.
Unpack the provided value with the configured compressor and serializer
-as set with Redis::setOption().
+
Unpack the provided value by first uncompressing it (if Redis::OPT_COMPRESSION
+is set) and then unserializing it (if Redis::OPT_SERIALIZER is set) to recover
+the original PHP value.
Execute the Redis DEBUG command. Note that this is disabled by default
+and can be very dangerous, even allowing you to crash the server. Use
+with caution
Dump Redis' internal binary representation of a key.
@@ -609,7 +1543,7 @@
Methods
Redis|bool
- expire(string $key, int $timeout, string|null $mode = NULL)
+ expire(string $key, int $timeout, string|null $mode = null)
Sets an expiration in seconds on the key in question. If connected to
redis-server >= 7.0.0 you may send an additional "mode" argument which
@@ -621,7 +1555,7 @@
Methods
Redis|bool
- expireAt(string $key, int $timestamp, string|null $mode = NULL)
+ expireAt(string $key, int $timestamp, string|null $mode = null)
Connects to a Redis server creating or reusing a persistent connection.
@@ -1445,7 +2616,7 @@
Methods
bool
- pexpire(string $key, int $timeout, string|null $mode = NULL)
+ pexpire(string $key, int $timeout, string|null $mode = null)
Sets an expiration in milliseconds on a given key. If connected to Redis >= 7.0.0
you can pass an optional mode argument that modifies how the command will execute.
@@ -1456,7 +2627,7 @@
Methods
Redis|bool
- pexpireAt(string $key, int $timestamp, string|null $mode = NULL)
+ pexpireAt(string $key, int $timestamp, string|null $mode = null)
Set a key's expiration to a specific Unix Timestamp in milliseconds. If connected to
Redis >= 7.0.0 you can pass an optional 'mode' argument.
Create a new Redis instance. If passed sufficient information in the
options array it is also possible to connect to an instance at the same
time.
NOTE: Below is an example options array with various setting
-
$options = [
- 'host' => 'localhost',
- 'port' => 6379,
- 'readTimeout' => 2.5,
- 'connectTimeout' => 2.5,
- 'persistent' => true,
-
- // Valid formats: NULL, ['user', 'pass'], 'pass', or ['pass']
- 'auth' => ['phpredis', 'phpredis'],
-
- // See PHP stream options for valid SSL configuration settings.
- 'ssl' => ['verify_peer' => false],
-
- // How quickly to retry a connection after we time out or it closes.
- // Note that this setting is overridden by 'backoff' strategies.
- 'retryInterval' => 100,
-
- // Which backoff algorithm to use. 'decorrelated jitter' is
- // likely the best one for most solution, but there are many
- // to choose from:
- // REDIS_BACKOFF_ALGORITHM_DEFAULT
- // REDIS_BACKOFF_ALGORITHM_CONSTANT
- // REDIS_BACKOFF_ALGORITHM_UNIFORM
- // REDIS_BACKOFF_ALGORITHM_EXPONENTIAL
- // REDIS_BACKOFF_ALGORITHM_FULL_JITTER
- // REDIS_BACKOFF_ALGORITHM_EQUAL_JITTER
- // REDIS_BACKOFF_ALGORITHM_DECORRELATED_JITTER
- // 'base', and 'cap' are in milliseconds and represent the first
- // delay redis will use when reconnecting, and the maximum delay
- // we will reach while retrying.
- 'backoff' => [
- 'algorithm' => Redis::BACKOFF_ALGORITHM_DECORRELATED_JITTER,
- 'base' => 500,
- 'cap' => 750,
- ]
+
$options = [
+ 'host' => 'localhost',
+ 'port' => 6379,
+ 'readTimeout' => 2.5,
+ 'connectTimeout' => 2.5,
+ 'persistent' => true,
+
+ // Valid formats: NULL, ['user', 'pass'], 'pass', or ['pass']
+ 'auth' => ['phpredis', 'phpredis'],
+
+ // See PHP stream options for valid SSL configuration settings.
+ 'ssl' => ['verify_peer' => false],
+
+ // How quickly to retry a connection after we time out or it closes.
+ // Note that this setting is overridden by 'backoff' strategies.
+ 'retryInterval' => 100,
+
+ // Which backoff algorithm to use. 'decorrelated jitter' is
+ // likely the best one for most solution, but there are many
+ // to choose from:
+ // REDIS_BACKOFF_ALGORITHM_DEFAULT
+ // REDIS_BACKOFF_ALGORITHM_CONSTANT
+ // REDIS_BACKOFF_ALGORITHM_UNIFORM
+ // REDIS_BACKOFF_ALGORITHM_EXPONENTIAL
+ // REDIS_BACKOFF_ALGORITHM_FULL_JITTER
+ // REDIS_BACKOFF_ALGORITHM_EQUAL_JITTER
+ // REDIS_BACKOFF_ALGORITHM_DECORRELATED_JITTER
+ // 'base', and 'cap' are in milliseconds and represent the first
+ // delay redis will use when reconnecting, and the maximum delay
+ // we will reach while retrying.
+ 'backoff' => [
+ 'algorithm' => Redis::BACKOFF_ALGORITHM_DECORRELATED_JITTER,
+ 'base' => 500,
+ 'cap' => 750,
+ ]
];
Note: If you do wish to connect via the constructor, only 'host' is
strictly required, which will cause PhpRedis to connect to that
@@ -2706,22 +4056,24 @@
Pack the provided value with the configured serializer and compressor
-as set with Redis::setOption().
+
Pack the provided value by first serializing it (if Redis::OPT_SERIALIZER is set)
+and then compressing the serialized payload (if Redis::OPT_COMPRESSION is set),
+mirroring exactly what PhpRedis transmits to Redis.
Parameters
@@ -3061,9 +4465,10 @@
Parameters
-
Return Value
+
Return Value
-
+
+
string
The packed result having been serialized and
@@ -3071,70 +4476,97 @@
Unpack the provided value by first uncompressing it (if Redis::OPT_COMPRESSION
+is set) and then unserializing it (if Redis::OPT_SERIALIZER is set) to recover
+the original PHP value.
Parameters
@@ -3142,46 +4574,50 @@
Parameters
string
-
$subcmd
-
-
-
-
string
-
...$args
-
+
$value
+
The value which has been serialized and compressed.
Execute the Redis DEBUG command. Note that this is disabled by default
+and can be very dangerous, even allowing you to crash the server. Use
+with caution
The SHA1 hash of the lua code. Note that the script
+must already exist on the server, either having been
+loaded with SCRIPT LOAD or having been executed directly
+with EVAL first.
Functions is an API for managing code to be executed on the server.
+
+
+
Parameters
+
+
+
+
string
+
$operation
+
The subcommand you intend to execute. Valid options are as follows
+'LOAD' - Create a new library with the given library name and code.
+'DELETE' - Delete the given library.
+'LIST' - Return general information on all the libraries
+'STATS' - Return information about the current function running
+'KILL' - Kill the current running function
+'FLUSH' - Delete all the libraries
+'DUMP' - Return a serialized payload representing the current libraries
+'RESTORE' - Restore the libraries represented by the given payload
Add one or more members to a geospacial sorted set
+
+
+
Parameters
+
+
+
+
string
+
$key
+
The sorted set to add data to.
+
+
+
float
$lng
The longitude of the first member
float
$lat
-
The lattitude of the first member.
+
The latitude of the first member.
string
@@ -6046,16 +8335,17 @@
Parameters
mixed
...$other_triples_and_options
-
You can continue to pass longitude, lattitude, and member
+
You can continue to pass longitude, latitude, and member
arguments to add as many members as you wish. Optionally, the final argument may be
a string with options for the command Redis documentation for the options.
-
Return Value
+
Return Value
-
+
+
Redis|int|false
The number of added elements is returned. If the 'CH' option is specified,
@@ -6063,6 +8353,7 @@
An array of options that modifies how the command behaves.
-
$options = [
+
$options = [
'WITHCOORD', # Return members and their coordinates.
'WITHDIST', # Return members and their distances from the center.
'WITHHASH', # Return members GeoHash string.
@@ -6389,15 +8682,17 @@
Parameters
-
Return Value
+
Return Value
-
+
+
mixed
This command can return various things, depending on the options passed.
$options = [
'EX' => <seconds> # Expire in N seconds
'PX' => <milliseconds> # Expire in N milliseconds
'EXAT' => <timestamp> # Expire at a unix timestamp (in seconds)
@@ -6989,15 +9432,17 @@
$options = [
'MINMATCHLEN' => int # Exclude matching substrings that are less than this value
'WITHMATCHLEN' => bool # Whether each match should also include its length.
@@ -7468,15 +10059,17 @@
Iterate over the fields and values of a hash in an incremental fashion.
+
Set a hash field and value, but only if that field does not exist
Parameters
@@ -8661,37 +11416,32 @@
Parameters
string
$key
-
The hash to query.
-
-
-
int|null
-
$iterator
-
The scan iterator, which should be initialized to NULL before the first call.
-This value will be updated after every call to hscan, until it reaches zero
-meaning the scan is complete.
+
The hash to update.
-
string|null
-
$pattern
-
An optional glob-style pattern to filter fields with.
+
string
+
$field
+
The value to set.
-
int
-
$count
-
An optional hint to Redis about how many fields and values to return per HSCAN.
Retrieve information about the connected redis-server. If no arguments are passed to
-this function, redis will return every info field. Alternatively you may pass a specific
-section you want returned (e.g. 'server', or 'memory') to receive only information pertaining
-to that section.
If connected to Redis server >= 7.0.0 you may pass multiple optional sections.
+
Set the expiration on one or more fields in a hash in milliseconds.
Parameters
@@ -8967,21 +11697,38 @@
Parameters
string
-
...$sections
-
Optional section(s) you wish Redis server to return.
Get the expiration time in milliseconds of one or more fields in a hash
Parameters
@@ -9334,65 +12130,65 @@
Parameters
string
$key
-
The list to query.
-
-
-
mixed
-
$value
-
The value to search for.
+
The hash to query.
array
-
$options
-
Options to configure how the command operates
-
$options = [
- # How many matches to return. By default a single match is returned.
- # If count is set to zero, it means unlimited.
- 'COUNT' => <num-matches>
-
- # Specify which match you want returned. `RANK` 1 means "the first match"
- # 2 means the second, and so on. If passed as a negative number the
- # RANK is computed right to left, so a `RANK` of -1 means "the last match".
- 'RANK' => <rank>
-
- # This argument allows you to limit how many elements Redis will search before
- # returning. This is useful to prevent Redis searching very long lists while
- # blocking the client.
- 'MAXLEN => <max-len>
-];
+
$fields
+
The fields to query.
-
Return Value
+
Return Value
-
+
+
-
Redis|null|bool|int|array
-
Returns one or more of the matching indexes, or null/false if none were found.
Iterate over the fields and values of a hash in an incremental fashion.
Parameters
@@ -9467,25 +12264,39 @@
Parameters
string
$key
-
The list to append to.
+
The hash to query.
-
mixed
-
...$elements
-
one or more elements to append.
+
null|int|string
+
$iterator
+
The scan iterator, which should be initialized to NULL before the first call.
+This value will be updated after every call to hscan, until it reaches zero
+meaning the scan is complete.
+
+
+
string|null
+
$pattern
+
An optional glob-style pattern to filter fields with.
+
+
+
int
+
$count
+
An optional hint to Redis about how many fields and values to return per HSCAN.
Retrieve information about the connected redis-server. If no arguments are passed to
+this function, redis will return every info field. Alternatively you may pass a specific
+section you want returned (e.g. 'server', or 'memory') to receive only information pertaining
+to that section.
If connected to Redis server >= 7.0.0 you may pass multiple optional sections.
Parameters
@@ -9844,31 +12746,23 @@
Parameters
string
-
$key
-
The list to truncate.
-
-
-
mixed
-
$value
-
The value to remove.
-
-
-
int
-
$count
-
How many elements matching the value to remove.
+
...$sections
+
Optional section(s) you wish Redis server to return.
$options = [
+ # How many matches to return. By default a single match is returned.
+ # If count is set to zero, it means unlimited.
+ 'COUNT' => <num-matches>
+
+ # Specify which match you want returned. `RANK` 1 means "the first match"
+ # 2 means the second, and so on. If passed as a negative number the
+ # RANK is computed right to left, so a `RANK` of -1 means "the last match".
+ 'RANK' => <rank>
+
+ # This argument allows you to limit how many elements Redis will search before
+ # returning. This is useful to prevent Redis searching very long lists while
+ # blocking the client.
+ 'MAXLEN => <max-len>
+];
+
+
+
+
+
Return Value
+
+
+
+
+
Redis|null|bool|int|array
+
Returns one or more of the matching indexes, or null/false if none were found.
$redis->connect('localhost', 6379);
+$redis->set('foo', '6379_key');
+
+// Move the key to localhost:9999 with a 5 second timeout
+var_dump($redis->migrate('localhost', 9999, 'foo', 0, 5000));
Sets an expiration in milliseconds on a given key. If connected to Redis >= 7.0.0
+you can pass an optional mode argument that modifies how the command will execute.
+
+
+
Parameters
+
+
+
+
string
+
$key
+
The key to set an expiration on.
+
+
+
int
+
$timeout
+
The number of milliseconds after which key will be automatically deleted.
+
+
+
string|null
+
$mode
+
A two character modifier that changes how the
+command works.
+
+
+
+
+
Return Value
+
+
+
+
+
bool
+
True if an expiry was set on the key, and false otherwise.
@param string $key The key to set an expiration on.
+@param int $timestamp The unix timestamp to expire at.
+@param string|null $mode A two character modifier that changes how the
+ command works.
+
+@return Redis|bool True if an expiration was set on the key, false otherwise.
Pipeline mode is the highest performance way to send many commands to Redis
+as they are aggregated into one stream of commands and then all sent at once
+when the user calls Redis::exec().
+
NOTE: That this is shorthand for Redis::multi(Redis::PIPELINE)
+
+
+
+
Return Value
+
+
+
+
+
bool|Redis
+
The redis object is returned, to facilitate method chaining.
Sets an expiration in milliseconds on a given key. If connected to Redis >= 7.0.0
-you can pass an optional mode argument that modifies how the command will execute.
Add one or more elements to a Redis HyperLogLog key
+
Restore a key by the binary payload generated by the DUMP command.
Parameters
@@ -10700,25 +16190,50 @@
Parameters
string
$key
-
The key in question.
+
The name of the key you wish to create.
-
array
-
$elements
-
One or more elements to add.
+
int
+
$ttl
+
What Redis should set the key's TTL (in milliseconds) to once it is created.
+Zero means no TTL at all.
+
+
+
string
+
$value
+
The serialized binary value of the string (generated by DUMP).
+
+
+
array|null
+
$options
+
An array of additional options that modifies how the command operates.
+
$options = [
+ 'ABSTTL' # If this is present, the `$ttl` provided by the user should
+ # be an absolute timestamp, in milliseconds()
+
+ 'REPLACE' # This flag instructs Redis to store the key even if a key with
+ # that name already exists.
+
+ 'IDLETIME' => int # Tells Redis to set the keys internal 'idletime' value to a
+ # specific number (see the Redis command OBJECT for more info).
+ 'FREQ' => int # Tells Redis to set the keys internal 'FREQ' value to a specific
+ # number (this relates to Redis' LFU eviction algorithm).
+];
-
Return Value
+
Return Value
-
+
+
-
Redis|int
-
Returns 1 if the set was altered, and zero if not.
Pipeline mode is the highest performance way to send many commands to Redis
-as they are aggregated into one stream of commands and then all sent at once
-when the user calls Redis::exec().
-
NOTE: That this is shorthand for Redis::multi(Redis::PIPELINE)
+
Add one or more values to a Redis SET key. This is an alternative to Redis::sadd() but
+instead of being variadic, takes a single array of values.
-
-
Return Value
+
Parameters
+
+
string
+
$key
+
The set to add values to.
+
+
+
array
+
$values
+
One or more members to add to the set.
+
+
+
+
+
Return Value
+
+
+
-
bool|Redis
-
The redis object is returned, to facilitate method chaining.