diff --git a/.gitignore b/.gitignore index fa1d633688..0d2826d161 100644 --- a/.gitignore +++ b/.gitignore @@ -25,3 +25,5 @@ compile_commands.json doctum.phar run-tests.php vendor/ +.agents.md +.codex diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..87ec6e11e8 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,146 @@ +## 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: + +```bash +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: + +```bash +php -n \ + -dextension=json.so \ + -dextension=igbinary.so \ + -dextension=msgpack.so \ + -dextension=.libs/redis.so \ +