The phpredis extension provides an API for communicating with the Redis key-value store. Valkey and KeyDB are supported as well.

It is released under the PHP License, version 3.01.

You can send comments, patches, questions here on github, to Michael (Twitter, Mastodon), Pavlo (@yatsukhnenko), or Nicolas (@yowgi).

   

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! ❤️

The ongoing development of PhpRedis is made possible thanks to the generous support of Relay, 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.

The best way to support the project is through GitHub Sponsors. Many of the reward tiers grant access to our Slack where myself and Pavlo 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.

1. Installing/Configuring
   • Installation
   • PHP Session handler
   • Distributed Redis Array
   • Redis Cluster support
   • Redis Sentinel support
   • Running the unit tests
2. Classes and methods
   • Usage
   • Connection
   • Retry and backoff
   • Transactions
   • Local Helper Methods
   • Introspection
3. API Documentation

For everything you should need to install PhpRedis on your system, see the INSTALL.md page.

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 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.
• 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.

Sessions have a lifetime expressed in seconds and stored in the INI variable "session.gc_maxlifetime". You can change it with ini_set(). 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".

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:"

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.

The following INI variables can be used to configure session locking:

; Should the locking be enabled? Defaults to: 0.
redis.session.locking_enabled = 1
; How long should the lock live (in seconds)? Defaults to: value of max_execution_time.
redis.session.lock_expire = 60
; How long to wait between attempts to acquire lock, in microseconds (µs)?. Defaults to: 20000
redis.session.lock_wait_time = 50000
; Maximum number of times to retry (-1 means infinite). Defaults to: 100
redis.session.lock_retries = 2000

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

phpredis uses a small custom unit test suite for testing functionality of the various classes. To run tests, simply do the following:

# Run tests for Redis class (note this is the default)
php tests/TestRedis.php --class Redis

# Run tests for RedisArray class
tests/mkring.sh start
php tests/TestRedis.php --class RedisArray
tests/mkring.sh stop

# Run tests for the RedisCluster class
tests/make-cluster.sh start
php tests/TestRedis.php --class RedisCluster
tests/make-cluster.sh stop

# Run tests for RedisSentinel class
php tests/TestRedis.php --class RedisSentinel

Note that it is possible to run only tests which match a substring of the test itself by passing the additional argument '--test ' when invoking.

# Just run the 'echo' test
php tests/TestRedis.php --class Redis --test echo

1. Class Redis
2. Class RedisException

Description: Creates a Redis client

$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 / pconnect.

$redis = new Redis([
    'host' => '127.0.0.1',
    'port' => 6379,
    'connectTimeout' => 2.5,
    'auth' => ['phpredis', 'phpredis'],
    'database' => 2,
    'ssl' => ['verify_peer' => false],
    'backoff' => [
        'algorithm' => Redis::BACKOFF_ALGORITHM_DECORRELATED_JITTER,
        'base' => 500,
        'cap' => 750,
    ],
]);

phpredis throws a 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 unreachable server (such as a key not existing, an invalid command, etc), phpredis will return FALSE.

1. connect, open - Connect to a server
2. pconnect, popen - Connect to a server (persistent)
3. auth - Authenticate to the server
4. close - Close the connection
5. setOption - Set client option
6. getOption - Get client option

Description: Connects to a Redis instance. If phpredis cannot reach the server it will usually throw a RedisException; only rarely will FALSE be returned without an exception.

$redis->connect('127.0.0.1', 6379);
$redis->connect('127.0.0.1'); // port 6379 by default
$redis->connect('tls://127.0.0.1', 6379); // enable transport level security.
$redis->connect('tls://127.0.0.1'); // enable transport level security, port 6379 by default.
$redis->connect('127.0.0.1', 6379, 2.5); // 2.5 sec timeout.
$redis->connect('/tmp/redis.sock'); // unix domain socket.
$redis->connect('127.0.0.1', 6379, 1, '', 100); // 1 sec timeout, 100ms delay between reconnection attempts.
$redis->connect('/tmp/redis.sock', 0, 1.5, NULL, 0, 1.5); // Unix socket with 1.5s timeouts (connect and read)

/* 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. 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.

Description: Connects to a Redis instance or reuse a connection already established with pconnect/popen.

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 or host + persistent_id or unix socket + timeout.

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 work like their non persistent equivalents.

$redis->pconnect('127.0.0.1', 6379);
$redis->pconnect('127.0.0.1'); // port 6379 by default - same connection like before.
$redis->pconnect('tls://127.0.0.1', 6379); // enable transport level security.
$redis->pconnect('tls://127.0.0.1'); // enable transport level security, port 6379 by default.
$redis->pconnect('127.0.0.1', 6379, 2.5); // 2.5 sec timeout and would be another connection than the two before.
$redis->pconnect('127.0.0.1', 6379, 2.5, 'x'); // x is sent as persistent_id and would be another connection than the three before.
$redis->pconnect('/tmp/redis.sock'); // unix domain socket - would be another connection than the four before.

Note: popen is an alias for pconnect and will be removed in future versions of phpredis.

Description: Authenticate the connection using a password or a username and password. Warning: The password is sent in plain-text over the network.

/* Authenticate with the password 'foobared' */
$redis->auth('foobared');

/* Authenticate with the username 'phpredis', and password 'haxx00r' */
$redis->auth(['phpredis', 'haxx00r']);

/* Authenticate with the password 'foobared' */
$redis->auth(['foobared']);

/* You can also use an associative array specifying user and pass */
$redis->auth(['user' => 'phpredis', 'pass' => 'phpredis']);
$redis->auth(['pass' => 'phpredis']);

Description: Set client option.

$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
$redis->setOption(Redis::OPT_SERIALIZER, Redis::SERIALIZER_IGBINARY); // Use igBinary serialize/unserialize
$redis->setOption(Redis::OPT_SERIALIZER, Redis::SERIALIZER_MSGPACK);  // Use msgpack serialize/unserialize
$redis->setOption(Redis::OPT_SERIALIZER, Redis::SERIALIZER_JSON);  // Use JSON to serialize/unserialize

$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
   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
   until keys come back OR Redis returns an iterator of zero
*/
$redis->setOption(Redis::OPT_SCAN, Redis::SCAN_NORETRY);
$redis->setOption(Redis::OPT_SCAN, Redis::SCAN_RETRY);

/* Scan can also be configured to automatically prepend the currently set PhpRedis
   prefix to any MATCH pattern. */
$redis->setOption(Redis::OPT_SCAN, Redis::SCAN_PREFIX);
$redis->setOption(Redis::OPT_SCAN, Redis::SCAN_NOPREFIX);

Description: Get client option.

// Retrieve the current serializer option
$redis->getOption(Redis::OPT_SERIALIZER);

Description: Check the current connection status.

$redis->ping([string $message]);

1. Maximum retries
2. Backoff algorithms

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.

$redis->setOption(Redis::OPT_MAX_RETRIES, 5);
$redis->getOption(Redis::OPT_MAX_RETRIES);

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:

• Default: Redis::BACKOFF_ALGORITHM_DEFAULT
• Decorrelated jitter: Redis::BACKOFF_ALGORITHM_DECORRELATED_JITTER
• Full jitter: Redis::BACKOFF_ALGORITHM_FULL_JITTER
• Equal jitter: Redis::BACKOFF_ALGORITHM_EQUAL_JITTER
• Exponential: Redis::BACKOFF_ALGORITHM_EXPONENTIAL
• Uniform: Redis::BACKOFF_ALGORITHM_UNIFORM
• Constant: Redis::BACKOFF_ALGORITHM_CONSTANT

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.

$redis->setOption(Redis::OPT_BACKOFF_ALGORITHM, Redis::BACKOFF_ALGORITHM_DECORRELATED_JITTER);
$redis->setOption(Redis::OPT_BACKOFF_BASE, 500); // base for backoff computation: 500ms
$redis->setOption(Redis::OPT_BACKOFF_CAP, 750); // backoff time capped at 750ms

1. multi, exec, discard - Enter and exit transactional mode
2. watch, unwatch - Watches a key for modifications by another client.

Description: Enter and exit transactional mode.

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.

$ret = $redis->multi()
    ->set('key1', 'val1')
    ->get('key1')
    ->set('key2', 'val2')
    ->get('key2')
    ->exec();

/*
$ret == [0 => TRUE, 1 => 'val1', 2 => TRUE, 3 => 'val2'];
*/

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.

$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` */
$ret = $redis->multi()
    ->incr('x')
    ->exec();
/*
$ret = FALSE if x has been modified between the call to WATCH and the call to EXEC.
*/

These helpers expose the exact logic PhpRedis uses locally for serialization, compression, and prefixing.

• getLastError - The last error message (if any)
• clearLastError - Clear the last error message
• _compress - Compress a string with the configured compression option
• _uncompress - Uncompress a string with the configured compression option
• _serialize - Serialize a value with the configured serializer
• _unserialize - Unserialize a string with the configured serializer
• _pack - Serialize and compress a value exactly as PhpRedis would before sending it to Redis
• _unpack - Reverse _pack to retrieve the original PHP value
• _prefix - Apply the configured key prefix locally
• _digest - Compute the XXH3 digest of a packed value just like Redis' DIGEST command

Description: Get the last error message, if any.

None.

$redis->del('hash');
$redis->hmset('hash', ['foo' => 'bar']);
$redis->rpush('hash', 'baz');
echo $redis->getLastError(); // "ERR Operation against a key holding the wrong kind of value"

Description: Clear the last error message

None.

$redis->set('x', 'a');
$redis->incr('x');
$err = $redis->getLastError();
// "ERR value is not an integer or out of range"
$redis->clearLastError();
$err = $redis->getLastError();
// NULL

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.

$redis->setOption(Redis::OPT_COMPRESSION, Redis::COMPRESSION_LZF);
$payload = $redis->_compress('large-payload');

Description: Reverse _compress by uncompressing a string with the compression option currently in use.

$redis->setOption(Redis::OPT_COMPRESSION, Redis::COMPRESSION_LZ4);
$original = $redis->_uncompress($compressedPayload);

Description: Serialize a value manually using whatever serializer is configured.

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 will change Array values to 'Array', and Objects to 'Object'.

$redis->setOption(Redis::OPT_SERIALIZER, Redis::SERIALIZER_NONE);
$redis->_serialize("foo"); // returns "foo"
$redis->_serialize([]); // Returns "Array"
$redis->_serialize(new stdClass()); // Returns "Object"

$redis->setOption(Redis::OPT_SERIALIZER, Redis::SERIALIZER_PHP);
$redis->_serialize("foo"); // Returns 's:3:"foo";'

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.

$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]

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.

$redis->setOption(Redis::OPT_SERIALIZER, Redis::SERIALIZER_PHP);
$redis->setOption(Redis::OPT_COMPRESSION, Redis::COMPRESSION_LZF);
$payload = $redis->_pack(['a' => 1]);

Description: Reverse _pack by uncompressing and then unserializing a payload using the current PhpRedis options.

$value = $redis->_unpack($payload);

Description: A utility method to prefix the value with the prefix setting for PhpRedis.

$redis->setOption(Redis::OPT_PREFIX, 'my-prefix:');
$redis->_prefix('my-value'); // Will return 'my-prefix:my-value'

Description: Compute the XXH3 digest of a PHP value after it has been _packed. This produces the same output as Redis' DIGEST command, making it easy to verify values locally.

$digest = $redis->_digest(['foo' => 'bar']);

1. isConnected - Check if PhpRedis believes it is connected
2. getHost - Retrieve the configured host or unix socket
3. getPort - Retrieve the configured port
4. getDbNum - Get the currently selected database number
5. getTimeout - Get the write timeout value
6. getReadTimeout - Get the configured read timeout
7. getPersistentID - Get the persistent ID for the connection
8. getAuth - Retrieve authentication credentials in use

Description: A method to determine if a phpredis object thinks it's connected to a server

None

Description: Retrieve our host or unix socket that we're connected to

None

Description: Get the port we're connected to

None

Description: Get the database number phpredis is pointed to

None

Description: Get the (write) timeout in use for phpredis

None

Description: Get the read timeout specified to phpredis or FALSE if we're not connected

None

Description: Gets the persistent ID that phpredis is using

None

Description: Get the password (or username and password if using Redis 6 ACLs) used to authenticate the connection.

None

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.

We automatically generate detailed and searchable API documentation for every class and method using doctum.

API Documentation is available here.

NOTE: To generate the docs yourself, you just need to have doctum on your path and can run

doctum update doctum-config.php