PhpRedis session defaults: read_timeout at 0, locking tied to a single master, weights fixed at session start

One library.c, four client front ends, each with its own stub and arginfo header

The extension talks to the Redis key-value store from C, and the tree is organised around four front ends rather than one. redis.c holds the plain client, redis_array.c the distributed array, redis_cluster.c the cluster client and redis_sentinel.c the sentinel client, and each one carries a matching stub file and argument info header so PHP knows the signatures. Shared code sits in library.c and common.h behind php_redis.h, with backoff.c and backoff.h for retry handling and crc16.h for the cluster side.

The API reference is split the same way, into groups for Connection, Retry and backoff, Server, Keys and strings, Hashes, Lists, Sets, Sorted sets, HyperLogLogs, Geocoding, Streams, Pub/sub, Transactions, Scripting, Local Helper Methods and Introspection. Separate documents cover the array, cluster and sentinel setups: arrays.md, cluster.md and sentinel.md, with a docs/ directory and package.xml alongside. The client also speaks to Valkey, Dragonfly and KeyDB, not only to Redis itself, which matters if your key-value store is a fork.

The README hands installation to INSTALL.md and keeps no command of its own

Installation is the one part of the README with nothing to copy. Its installation section says that for everything needed to install PhpRedis on your system, see the INSTALL.md page, and stops there. No pecl line, no configure invocation, no Windows one-liner appears in its installation section, so a reader who wants to run something today has to open INSTALL.md.

What the repository tree does show is the shape of the build. Two build configuration files sit at the root, config.m4 and config.w32, one pair for the two platforms. Debian packaging is present as debian.control and a debian/ directory, with mkdeb.sh and mkdeb-apache2.sh alongside, and composer.json and package.xml cover the other distribution routes. liblzf and .gitmodules both appear at the top level. Default branch is develop, and the last release tag in the tree is 6.3.0, published 2025-11-06 after 6.3.0RC1 a month earlier, with 6.2.0 from 2025-03-24 before that.

A tcp:// scheme is what makes session.save_path parameters visible to the handler

Turning PhpRedis into a PHP session store is two php.ini settings, `session.save_handler` and `session.save_path`. The path can be a bare host:port, but the parameters after it are only read when you provide the `tcp://` scheme, so a save_path without the scheme silently gets none of the settings that follow it.

Weights are the mechanism worth understanding. A host with twice the weight of another gets twice the sessions, so in the example below host1 takes a fifth of them and host2 and host3 take two fifths each. The target host is picked once at the start of the session and does not change for its lifetime, which means a session never migrates if a host dies or you change weights later. The prefix defaults to `PHPREDIS_SESSION:` and is joined to the session id to form the key.

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"

Credentials go in the same string as an array of one or two elements, `auth[]=user&auth[]=password`, and a unix socket takes the same parameters, as in `session.save_path = "unix:///var/run/redis/redis.sock?persistent=1&weight=1&database=0"`. Session lifetime stays where PHP keeps it, in session.gc_maxlifetime, and the handler needs a Redis that supports the `EX` and `NX` options of `SET`, at least 2.6.12.

read_timeout defaults to 0, so a stale connection blocks the request instead of failing it

Two timeouts govern the session path, and their defaults point in opposite directions. `timeout` is the connection timeout in seconds, and when a host does not answer in that time the session store simply reports itself unavailable to the client. Its default is 86400 seconds, a full day. An unreachable session host can therefore hold a request for far longer than any web request should wait.

`read_timeout` covers reads on a connection that is already established, and its default is `0`, which means no timeout at all. With that default, PHP can hang indefinitely if Redis stops responding or the connection goes stale, and the README calls setting it to a low value such as `2.5` strongly recommended in production. The failure is worse than a slow page: the request occupies a PHP worker indefinitely, so a Redis blip turns into a pool of stuck workers instead of a burst of errors.

Persistent connections are off by default, `persistent` taking `1` or `0` with `0` as the default, so the default configuration reconnects on every request and inherits `read_timeout=0` on each of them.

Session locking works on one master only, so RedisArray and RedisCluster sessions lose it

Locking is a separate switch, `redis.session.locking_enabled`, and it defaults to `0`. Turning it on is documented as supported only for a Redis setup with a single master instance, such as a classic master/slave Sentinel environment. The same note says plainly that locking may not work properly in RedisArray or RedisCluster environments.

That is a sharp edge for anyone who changes topology after wiring sessions up. An application that enables locking on a single Redis, then moves sessions onto RedisArray or RedisCluster to spread them and keeps the INI setting while the README warns locking may not work properly. The lock's own lifetime has a second default that ties it to PHP rather than to Redis, since how long the lock lives in seconds defaults to the value of max_execution_time. A request that runs longer than that limit outlives its session lock.

The two dead ends reinforce each other: no locking on a multi-instance setup, and a lock lifetime borrowed from an INI value that has nothing to do with how long your agent or worker holds a session.

Retry and backoff is a separate API group, implemented in backoff.c beside the client

Retry handling is not buried inside the connection call. The API reference lists Retry and backoff as its own group, sitting between Connection and Server, so it is a separate part of the surface you configure rather than a flag on opening a socket. In the source tree that logic lives in backoff.c and backoff.h, alongside crc16.h and cluster_library.c that the cluster front end uses, and next to library.c which the front ends share.

The separation matters when a client fails over. Arrays, clusters and sentinels each have their own document, arrays.md, cluster.md and sentinel.md, and each is a separate C front end in the tree. A reader deciding how a PHP process should retry has to look at the retry group in the API reference first, then at the document for whichever topology it runs, because the group and the front end are not the same thing and the retry behaviour is not the connection behaviour.

Relay is named as the drop-in replacement, and it funds the work on this extension

The README names one alternative and is unusually direct about the relationship. Relay is described as a high-performance in-memory cache and drop-in replacement for PhpRedis, handling millions of requests per second, and the same paragraph states that Relay funds the vast majority of the ongoing development of PhpRedis. Drop-in means the call sites stay as they are, so the choice is about what the client is, not about rewriting the code that uses it.

Licensing is the other thing to check before you adopt. The extension is released under the PHP License, version 3.01, so read its terms before redistributing it inside a product. Funding runs through GitHub Sponsors, with reward tiers that grant access to the project's Slack where two of the maintainers answer questions, and a one-time PayPal contribution as a third route.

Editorial conclusion

Adopt PhpRedis when a PHP process needs to reach Redis or one of its forks and you want the client in C rather than a PHP library, and start with the session handler, where the knobs are documented and the defaults are sharp. Leave read_timeout at 0 only on a trusted network, because that default lets a request block on a stale connection, and leave session locking off unless the sessions live on a single master, since the documentation excludes RedisArray and RedisCluster from it. What to verify first is your platform's install path: the README carries no install command of its own and points at INSTALL.md, so Windows and Debian work depend on what that file says. Pin your PHP build against the extension version too, since 6.3.0 shipped on 2025-11-06 and the default branch is develop.

Frequently asked questions

Official sources

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