PhpRedis

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, <a rel="me" href="https://phpc.social/@mgrunder">Mastodon</a>), Pavlo (@yatsukhnenko), or Nicolas (@yowgi).

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:

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.

Installing/Configuring
API Documentation
Classes and methods
- Usage
- Connection
- Retry and backoff
- Server
- Keys and strings
- Hashes
- Lists
- Sets
- Sorted sets
- HyperLogLogs
- Geocoding
- Streams
- Pub/sub
- Transactions
- Scripting
- Local Helper Methods
- Introspection

Installing/Configuring

Installation

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

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_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).
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.

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

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"

session.save_handler = redis
session.save_path = "tcp://127.0.0.1:6379?auth[]=user&auth[]=password"

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.

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

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:

# 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 <str>' when invoking.

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

API Documentation

The API Documentation are a work in progress, but will eventually replace our ONE README TO RULE THEM ALL docs.

Classes and methods

Class Redis

Description: Creates a Redis client

Example

$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

Phpredis

Install / Use

README