Overview

This project is PhpRedis, a PHP extension that exposes Redis, RedisCluster, RedisArray, and RedisSentinel APIs.

Project goals and constraints

• PhpRedis is a widely used C extension loaded into production PHP processes. Correctness and clarity are of utmost importance. The extension cannot crash in production because it could take down an entire PHP-FPM pool and cause customer downtime.
• After correctness, performance matters. Hot paths such as command packing, reply parsing, serializer/compressor handling, persistent connection reuse, and cluster routing should avoid unnecessary allocations and repeated work.
• Preserve the public PHP API and wire-protocol behavior unless the change is intentionally compatibility-breaking. Many users rely on subtle historical behavior.
• Prefer modular and composable code over duplicating logic. Given that this project is in C, that can typically be done without any performance cost.
• Be careful with ownership, refcounts, persistent allocations, and error paths. Most bugs in extensions become leaks, use-after-free defects, or process crashes.
• The PHP API surface can be found in the stubs under *.stub.php; generated arginfo headers should remain consistent with those stubs.
• This project supports optional serializers and compression backends. Changes should account for the combinations enabled by config.m4, especially JSON, igbinary, msgpack, lzf, lz4, zstd, and session support.
• For performance-critical code, it is often worth looking at codegen and trying more than one formulation. This can be done with objdump -d or by using specific compiler flags, such as -S.

C style guide

• Do not add casts unless they are required for correctness, ABI compatibility, aliasing, intentional narrowing, or to change arithmetic semantics (e.g. forcing floating-point arithmetic). Avoid documentation/performative casts that merely restate the compiler's implicit conversions.
• Keep error handling explicit and local. If a function returns ownership or borrows memory, make that obvious from the surrounding code and naming.
• Prefer existing helpers in library.c, redis_commands.c, cluster helpers, and session code over adding a second ad hoc implementation of the same parsing, packing, or connection behavior.

Building and running the modified project

• Before choosing a build, run, or test command, check whether .agents.md exists in the repository root. If it exists, read it and follow any user-specific local instructions in addition to this file.
• .agents.md is for local developer notes such as custom build scripts, local PHP source tree layouts, debugger helpers, or machine-specific configuration. It is intentionally ignored by git and must not be committed.
• Before building, agents should assume they need to run phpize and then ./configure from the repository root. Do not assume a checked-in Makefile is current.
• Agents can assume the default phpize, php-config, and PHP development headers are already available.
• A broad configure flow for agents is:

phpize
./configure \
  --enable-redis \
  --enable-redis-igbinary \
  --enable-redis-msgpack \
  --enable-redis-lzf \
  --enable-redis-lz4 \
  --enable-redis-zstd \
  --with-liblz4=/usr \
  --with-libzstd=/usr
make

• Session support and JSON serializer support are enabled by default. Use --disable-redis-session or --disable-redis-json only when a task specifically needs those configurations.
• After configure completes, build with make.

Running the extension

• For agent runs, prefer php -n so the process starts without any ambient ini state, then load the required extensions explicitly.
• Load optional serializer extensions before redis.so when the build enables them.
• A typical invocation is:

php -n \
  -dextension=json.so \
  -dextension=igbinary.so \
  -dextension=msgpack.so \
  -dextension=.libs/redis.so \
  <script> <args>

• Replace <script> <args> with the PHP file and arguments you want to run.
• If the environment does not expose those shared extensions on the default extension search path, use absolute paths to the .so files instead of bare extension names.
• .libs/redis.so is the usual build output path after make.

Running tests

The PhpRedis test suite is a pure-PHP runner and expects Redis-compatible servers to be available for the relevant classes.

php -n \
  -dextension=json.so \
  -dextension=igbinary.so \
  -dextension=msgpack.so \
  -dextension=.libs/redis.so \
  tests/TestRedis.php --class redis

• Use --class redis, --class redisarray, --class rediscluster, or --class redissentinel to choose a test group.
• Use --test <name> to run a single test method.
• Use --host, --port, --tls-port, --user, and --auth when the Redis server layout differs from the defaults.
• RedisArray tests expect multiple standalone Redis instances, normally on ports 6379, 6380, 6381, and 6382.
• RedisCluster tests require a working cluster. The helper scripts in tests/ can be used when appropriate, but local .agents.md instructions should take precedence for machine-specific Redis layouts.
• Session tests can depend on helper scripts and specific ini settings. Unless you are working on session behavior, do not treat unrelated session setup failures as signal for the current change.

Building in a full PHP source tree

It's possible we are in the ext/redis path within a full PHP source tree. This is easy to check because there will be a parent directory like php-x.y.z[-debug].

When this is the case, the project can be built by running make in the root of the build tree and then run with sapi/cli/php, again from the root of the build tree.

The tests can also be run with the sapi/cli/php binary which will not require specifying any specific extensions, as they are baked into the binary.

Cleaning intermediate build artifacts

When in a PHP source tree the build may fail due to intermediate artifacts in ext/redis. This can be fixed by deleting the generated build artifacts and running make again. Do not remove source files or user changes while cleaning.