PhpRedis: A C Extension for Connecting PHP to Redis

What PhpRedis Does and Who Needs It

PhpRedis is a compiled C extension for PHP that communicates directly with a Redis server over TCP or Unix domain sockets. It exposes a PHP class called Redis whose methods map to Redis commands: get, set, hget, lpush, zadd, publish, multi, and so on. Because the code is compiled C rather than PHP bytecode, the serialization and network operations run without the overhead of the PHP runtime.

The README describes support for Redis, Valkey, Dragonfly, and KeyDB. These are all Redis-compatible key-value stores that share the same protocol. A single PhpRedis installation communicates with any of them.

The primary audience is PHP applications that use Redis heavily: caching layers in content management systems, session storage for high-traffic web applications, and queues built on Redis lists or streams. The README notes that the ongoing development of PhpRedis is funded largely by Relay, a high-performance Redis client that describes itself as a drop-in replacement for PhpRedis.

PHP Session Storage via the Session Handler

PhpRedis can store PHP sessions in Redis by configuring two INI directives. The session.save_handler and session.save_path settings in php.ini direct PHP's session subsystem to use Redis instead of the filesystem. Multiple Redis hosts can be listed with weights to distribute session storage:

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"

Authenticated connections are configured via the auth parameter:

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

The README notes a significant default: the read_timeout parameter defaults to 0, meaning PHP can hang indefinitely if Redis becomes unresponsive. Setting this to a low value such as 2.5 seconds is described in the README as strongly recommended in production environments.

Session locking is available but restricted. The README states that session locking is currently supported only for single-master Redis configurations. It does not work correctly in RedisArray or RedisCluster environments. The locking behavior is controlled by INI variables including redis.session.locking_enabled, which defaults to disabled.

Installing PhpRedis

The README directs users to the INSTALL.md file in the repository for all installation instructions. PhpRedis is a C extension that must be compiled or installed from a package. For Linux distributions, the package is often available in the system package manager (for example, the php-redis package in Ubuntu's APT repositories). For Windows, pre-compiled DLL files are available for download.

The repository includes config.m4 (for Unix/Linux builds using phpize) and config.w32 (for Windows builds). The top-level directory also includes a debian/ directory with Debian packaging files and mkdeb.sh and mkdeb-apache2.sh scripts for building Debian packages locally.

For systems that do not have a pre-built package, the standard PHP extension compilation sequence applies: phpize, configure, make, and make install. Exact steps are in INSTALL.md. After installation, adding extension=redis.so to php.ini enables the extension.

The API Surface: Commands, Clusters, and Sentinel

PhpRedis provides four classes documented in the README. The main Redis class covers the full single-server command set: connection management, retry and backoff configuration, keys and strings, hashes, lists, sets, sorted sets, HyperLogLogs, geocoding, streams, pub/sub, transactions, and Lua scripting. Each Redis command has a corresponding PHP method.

RedisArray provides a distributed Redis array across multiple instances without cluster protocol. RedisCluster implements the Redis Cluster protocol for horizontal scaling with automatic sharding. RedisSentinel connects to a Sentinel-managed setup for high availability, handling master detection and failover.

Unix domain socket connections are supported in session.save_path with the format unix:///var/run/redis/redis.sock?persistent=1. The persistent parameter controls whether connections are kept alive across requests (persistent=1) or closed at the end of each PHP request. Session lifetime is drawn from the session.gc_maxlifetime INI variable and can be changed per request with ini_set().

Where PhpRedis Is Not the Right Choice

PhpRedis requires compiling a C extension. Shared hosting environments, managed PHP platforms, and some containerized setups do not allow loading custom extensions. In those environments, a pure PHP Redis client is the only option.

The session handler's locking limitation is a concrete constraint. The README is explicit that locking works only with single-master Redis. If the session handler is deployed against RedisCluster or RedisArray and session locking is required, PhpRedis does not support that combination. Teams needing distributed session locking must implement it in application code or choose a different session storage approach.

The read_timeout default of 0 in session configuration is another production risk the README calls out specifically. A Redis server that becomes unresponsive will cause PHP to block indefinitely if read_timeout is not set. The README recommends setting it to a value like 2.5 seconds in production environments. This applies to all Redis connections made through the session handler.

The license is PHP License version 3.01, not MIT or Apache 2.0. Some open-source projects and corporate legal policies treat the PHP License differently from permissive licenses. The license file is included in the repository root. Organizations with active license review processes should confirm compatibility before including PhpRedis in a distributed product.

PhpRedis vs Predis: C Extension vs Pure PHP

Predis is a pure PHP Redis client maintained as a Composer package. It requires no compiled extension and works on any PHP environment. Because it runs entirely in PHP, the CPU cost of each Redis command is higher than with PhpRedis, which executes serialization and I/O in compiled C code. For applications making a large number of Redis calls per request, this difference in overhead is measurable.

Predis installs via Composer and has no platform requirements beyond PHP itself. PhpRedis requires a compiled extension, which is faster but harder to deploy in restricted environments. The README notes that Relay, a commercial product, is a drop-in PhpRedis replacement that handles millions of requests per second. Relay is also the primary funder of ongoing PhpRedis development, as stated in the README.

The choice between PhpRedis and Predis comes down to the deployment environment and performance requirements. Dedicated servers and containers where extensions can be installed benefit from PhpRedis. Shared hosting and environments where only Composer packages are allowed require Predis. Feature coverage between the two is broadly similar: both support the Redis command set, clustering, and sentinel.

Editorial conclusion

PhpRedis is the right choice for PHP applications that need the lowest possible overhead when talking to Redis, including Valkey or KeyDB deployments. It is not suitable for environments where compiling a C extension is prohibited, or where the hosting provider only allows pure PHP packages. In those cases, Predis is the fallback. The license is PHP License version 3.01, not MIT or Apache; review that file before including PhpRedis in a project with strict license policies. The last push to the repository was on 2026-09-24, and the current release is 6.3.0.

Frequently asked questions

Official sources

1. Issues
2. phpredis/phpredis on GitHub
3. README
4. Releases