Skip to content

Commit b2af871

Browse files
jbrinkmanjbrinkman
committed
feat: add AGENTS.md file for agentic tools and developer guidance
- Add comprehensive AGENTS.md with PHP extension-specific context - Cover C extension build process with Zend API and FFI bindings - Include platform-specific considerations (macOS vs Linux) - Document PHP and C code quality requirements (phpcs, clang-format) - Provide FFI library integration guidance with Rust core - Include memory management and extension development best practices - Add quality gates checklist for PHP extension contributions Provides AI agents and developers with minimum but sufficient context for productive work with the Valkey GLIDE PHP extension, covering unique aspects of PHP extension development with C and FFI. Closes #40 Signed-off-by: jbrinkman <[email protected]>
1 parent effa43b commit b2af871

File tree

1 file changed

+253
-0
lines changed

1 file changed

+253
-0
lines changed

‎AGENTS.md‎

Lines changed: 253 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,253 @@
1+
# AGENTS: PHP Extension Context for Agentic Tools
2+
3+
This file provides AI agents with the minimum but sufficient context to work productively with the Valkey GLIDE PHP extension. It covers build commands, testing, contribution requirements, and essential guardrails specific to the PHP extension implementation.
4+
5+
## Repository Overview
6+
7+
This is the PHP extension for Valkey GLIDE, providing PHPRedis-compatible API for both standalone and cluster Valkey/Redis connections. The PHP extension is implemented in C using the Zend API and communicates with the Rust core via FFI bindings.
8+
9+
**Primary Languages:** C (Zend extension), PHP (API layer)
10+
**Build System:** PHP extension build system (phpize, configure, make)
11+
**Architecture:** C extension with FFI bindings to Rust core library
12+
13+
**Key Components:**
14+
- `*.c` / `*.h` - C extension source files using Zend API
15+
- `*.stub.php` - PHP stub files for argument info generation
16+
- `src/` - PHP source files and utilities
17+
- `tests/` - PHP test suites
18+
- `examples/` - Usage examples
19+
- `valkey-glide/` - Git submodule containing Rust core library
20+
21+
## Architecture Quick Facts
22+
23+
**Core Implementation:** C extension using Zend API with FFI bindings to Rust glide-core
24+
**Client Types:** ValkeyGlide (standalone), ValkeyGlideCluster (cluster)
25+
**API Style:** PHPRedis-compatible synchronous methods
26+
**Protocol:** Protobuf communication with Rust core via C FFI
27+
28+
**Supported Platforms:**
29+
- Linux: Ubuntu 20+ (x86_64, aarch64)
30+
- macOS: 14.7+ (aarch64/Apple Silicon)
31+
- **Note:** Alpine Linux/MUSL not supported
32+
33+
**PHP Versions:** 8.2, 8.3
34+
**Package:** `valkey-io/valkey-glide-php` (PHP extension)
35+
36+
## Build and Test Rules (Agents)
37+
38+
### Preferred (Make Targets)
39+
```bash
40+
# Build commands
41+
make generate-bindings generate-proto # Generate bindings and protobuf files
42+
make # Build the extension
43+
make install # Install extension to PHP
44+
make build-modules-pre # Pre-build step (alias for generate targets)
45+
46+
# Testing
47+
make test # Run PHP extension tests
48+
composer test # Run tests via Composer
49+
50+
# Code quality
51+
composer lint # Run PHP CodeSniffer
52+
composer lint:fix # Auto-fix PHP code style
53+
composer analyze # Run PHPStan static analysis
54+
composer check # Run lint + analyze
55+
./lint.sh # Run all linters (PHP + C)
56+
57+
# Setup and dependencies
58+
composer install # Install PHP dependencies
59+
phpize # Initialize extension build system
60+
./configure --enable-valkey-glide # Configure build
61+
```
62+
63+
### Raw Equivalents
64+
```bash
65+
# Manual extension build
66+
phpize
67+
./configure --enable-valkey-glide
68+
make
69+
70+
# Manual FFI library build (required dependency)
71+
cd valkey-glide/ffi && cargo build --release && cd ../..
72+
73+
# Manual protobuf generation
74+
protoc --proto_path=./valkey-glide/glide-core/src/protobuf --php_out=./tests/ ./valkey-glide/glide-core/src/protobuf/connection_request.proto
75+
76+
# Manual linting
77+
phpcs --standard=phpcs.xml
78+
clang-format --dry-run --Werror *.c *.h
79+
phpstan analyze
80+
81+
# Manual test execution
82+
php -n -d extension=modules/valkey_glide.so tests/TestValkeyGlide.php
83+
```
84+
85+
### Build Dependencies Setup
86+
```bash
87+
# Build FFI library (required before extension build)
88+
python3 utils/remove_optional_from_proto.py
89+
cd valkey-glide/ffi
90+
cargo build --release
91+
cd ../../
92+
93+
# Initialize submodules
94+
git submodule update --init --recursive
95+
96+
# Generate PHP protobuf classes for testing
97+
protoc --proto_path=./valkey-glide/glide-core/src/protobuf --php_out=./tests/ ./valkey-glide/glide-core/src/protobuf/connection_request.proto
98+
```
99+
100+
### Test Execution Options
101+
```bash
102+
# Run with Valkey servers
103+
cd tests
104+
./start_valkey_with_replicas.sh
105+
./create-valkey-cluster.sh
106+
php -n -d extension=../modules/valkey_glide.so TestValkeyGlide.php
107+
108+
# Memory leak detection with Valgrind
109+
valgrind --tool=memcheck --leak-check=full php -n -d extension=modules/valkey_glide.so tests/TestValkeyGlide.php
110+
111+
# AddressSanitizer build (Linux only)
112+
./configure --enable-valkey-glide --enable-valkey-glide-asan
113+
```
114+
115+
## Contribution Requirements
116+
117+
### Developer Certificate of Origin (DCO) Signoff REQUIRED
118+
119+
All commits must include a `Signed-off-by` line:
120+
121+
```bash
122+
# Add signoff to new commits
123+
git commit -s -m "feat(php): add new command implementation"
124+
125+
# Configure automatic signoff
126+
git config --global format.signOff true
127+
128+
# Add signoff to existing commit
129+
git commit --amend --signoff --no-edit
130+
131+
# Add signoff to multiple commits
132+
git rebase -i HEAD~n --signoff
133+
```
134+
135+
### Conventional Commits
136+
137+
Use conventional commit format:
138+
139+
```
140+
<type>(<scope>): <description>
141+
142+
[optional body]
143+
```
144+
145+
**Example:** `feat(php): implement cluster scan with cursor support`
146+
147+
### Code Quality Requirements
148+
149+
**PHP Linters (via Composer):**
150+
```bash
151+
composer lint # Must pass before commit
152+
composer lint:fix # Auto-fix code style issues
153+
composer analyze # PHPStan static analysis
154+
```
155+
156+
**C Code Linters:**
157+
```bash
158+
clang-format --dry-run --Werror *.c *.h # C code formatting check
159+
./lint.sh # Run all linters
160+
```
161+
162+
**Individual Tools:**
163+
- `phpcs` - PHP_CodeSniffer with PSR-12 standards
164+
- `phpcbf` - PHP Code Beautifier (auto-fix)
165+
- `phpstan` - Static analysis for PHP
166+
- `clang-format` - C code formatting (Google-based style)
167+
- `valgrind` - Memory leak detection
168+
169+
## Guardrails & Policies
170+
171+
### Generated Outputs (Never Commit)
172+
- `modules/` - Compiled PHP extension files
173+
- `include/glide_bindings.h` - Generated FFI bindings
174+
- `*_arginfo.h` - Generated argument info headers
175+
- `src/` - Generated protobuf files
176+
- `vendor/` - Composer dependencies
177+
- `valkey-glide/ffi/target/` - Rust build artifacts
178+
- `.libs/` - Build artifacts
179+
- `autom4te.cache/` - Autotools cache
180+
- `build/` - PHP extension build files
181+
- `run-tests.php` - Generated test runner
182+
183+
### PHP Extension-Specific Rules
184+
- **FFI Dependency:** Must build `valkey-glide/ffi` Rust library before extension
185+
- **Zend API:** Follow PHP extension development best practices
186+
- **Memory Management:** Use `emalloc`/`efree` for request-scoped memory
187+
- **Error Handling:** Use PHP exception system via `zend_throw_exception`
188+
- **PHPRedis Compatibility:** Maintain API compatibility with PHPRedis where possible
189+
- **Stub Files:** Update `.stub.php` files when adding new methods
190+
- **Protobuf:** Regenerate protobuf files after core changes
191+
192+
### Platform Considerations
193+
- **macOS:** Uses Homebrew paths (`/opt/homebrew/include`, `/opt/homebrew/lib`)
194+
- **Linux:** Supports multiple architectures (x86_64, aarch64)
195+
- **AddressSanitizer:** Available on Linux only (not macOS)
196+
- **Dependencies:** Requires protobuf-c, openssl, PHP dev headers
197+
198+
## Project Structure (Essential)
199+
200+
```
201+
valkey-glide-php/
202+
├── valkey_glide*.c # Main extension source files
203+
├── valkey_glide*.h # Extension header files
204+
├── *.stub.php # PHP stub files for arginfo generation
205+
├── config.m4 # Extension build configuration
206+
├── Makefile.frag # Platform-specific build rules
207+
├── composer.json # PHP dependencies and scripts
208+
├── phpcs.xml # PHP_CodeSniffer configuration
209+
├── .clang-format # C code formatting rules
210+
├── src/ # PHP source files and utilities
211+
├── tests/ # PHP test suites
212+
├── examples/ # Usage examples
213+
├── utils/ # Build utilities and scripts
214+
├── valkey-glide/ # Git submodule (Rust core library)
215+
└── lint.sh # Comprehensive linting script
216+
```
217+
218+
## Quality Gates (Agent Checklist)
219+
220+
- [ ] FFI library built: `valkey-glide/ffi/target/release/libglide_ffi.a` exists
221+
- [ ] Extension builds: `make` succeeds
222+
- [ ] Extension installs: `make install` succeeds
223+
- [ ] Tests pass: `make test` or `composer test` succeeds
224+
- [ ] PHP linting passes: `composer lint` succeeds
225+
- [ ] C formatting passes: `clang-format --dry-run --Werror *.c *.h` succeeds
226+
- [ ] Static analysis passes: `composer analyze` succeeds
227+
- [ ] No generated outputs committed (check `.gitignore`)
228+
- [ ] DCO signoff present: `git log --format="%B" -n 1 | grep "Signed-off-by"`
229+
- [ ] Conventional commit format used
230+
- [ ] Stub files updated for new methods
231+
- [ ] Memory leaks checked with Valgrind (Linux)
232+
233+
## Quick Facts for Reasoners
234+
235+
**Package:** `valkey-io/valkey-glide-php` (PHP extension)
236+
**API Style:** PHPRedis-compatible synchronous methods
237+
**Client Types:** ValkeyGlide (standalone), ValkeyGlideCluster (cluster)
238+
**Key Features:** C extension with Zend API, FFI bindings to Rust core, PHPRedis compatibility
239+
**Testing:** PHP test framework, Valgrind memory checking, AddressSanitizer support
240+
**Platforms:** Linux (Ubuntu), macOS (Apple Silicon)
241+
**Dependencies:** PHP 8.2+, Rust toolchain, protobuf compiler, C build tools
242+
243+
## If You Need More
244+
245+
- **Getting Started:** [README.md](./README.md)
246+
- **Development Setup:** [DEVELOPER.md](./DEVELOPER.md)
247+
- **Contributing Guidelines:** [CONTRIBUTING.md](./CONTRIBUTING.md)
248+
- **Security:** [SECURITY.md](./SECURITY.md)
249+
- **Examples:** [examples/](./examples/) directory
250+
- **Test Suites:** [tests/](./tests/) directory
251+
- **Build Configuration:** [config.m4](./config.m4) and [Makefile.frag](./Makefile.frag)
252+
- **Linting Script:** [lint.sh](./lint.sh)
253+
- **Rust Core:** [valkey-glide/](./valkey-glide/) submodule

0 commit comments

Comments
 (0)