从零到合并：PHP 内核贡献代码的完整实战指南（2025 版）
目录导读（Table of Contents）
- 为什么你应该为 PHP 贡献代码？ — 不只是荣誉，更是技术进阶的捷径。
- 贡献前的“宪法” — 你需要了解的 RFC 流程与代码规范。
- 实战第一步 — 从
php-src仓库 Git 克隆到本地环境编译。 - 提交代码的“黄金路径” — 分支管理、Commit Message 规范与
rebase的艺术。 - 用
PHP Internals邮件列表进行“答辩” — 如何回复reviewer并迭代补丁。 - 合并之后的那些事 — 文档同步、BUG 修复与社区责任。
- 常见问答（FAQ） — 针对新手最常见的 5 个致命疑问。
为什么你应该为 PHP 贡献代码？
在 Google 搜索趋势中，PHP 贡献代码流程 的查询量在近两年增长了 60%，这并非偶然——随着 PHP 8.x 的 JIT 性能革命，越来越多的开发者开始从“用 PHP”转向“改 PHP”。
为 PHP 贡献代码（尤其是内核代码）所带来的收益是实打实的：
- 技术硬实力：你将理解 Zend 引擎的内存管理（zend_hash）、垃圾回收机制（GC）以及 Opcode 的编译过程。
- 职业加速器：在简历中写下
PHP 8.4 核心贡献者的含金量，远高于任何PHP框架的熟练度。 - 社区影响力：你的名字将永久留在 PHP 的
CREDITS文件中，并获得维护者的直接技术背书。
但请清醒地知道：这不是在 GitHub 上提交一个 PR 那么简单，PHP 的政治正确性、代码标准及其严苛程度，在开源界堪称“保守派”代表。
贡献前的“宪法”
在你 git push 之前，必须先看懂两个文档（它们就像法律条文）：
- RFC 流程：任何新特性或重大行为修改，必须先到
wiki.php.net/rfc提交 RFC 提案，经过 7 天以上的社区讨论和投票，获得 2/3 多数票才能进入开发，如果你只是修 BUG，请直接跳至第二步。 - Coding Standards：PHP 内核有自己的一套 代码风格，与 PSR 标准截然不同。
- 只有 4 个空格缩进，严禁 Tab。
if括号必须换行（Allman 风格）。- 函数命名一律使用
php_前缀（如php_output_write）。 - 变量名全部小写,下划线分隔。
搜索引擎去伪要点：很多教程声称“用 GitHub 的 fork 就行”，这是错误的，PHP 官方代码托管在 git.php.net，虽然现在镜像到了 GitHub，但提交只认邮件列表中的 patch 格式，而不接受 GitHub PR。
实战第一步：获取源码与环境编译
$ git clone https://github.com/php/php-src.git $ cd php-src $ ./buildconf --force $ ./configure --disable-all --enable-debug --enable-cli $ make -j4
关键细节：
--enable-debug绝对必要！它会让 Zend 引擎在内存泄漏或非法指针访问时直接崩溃并打印回溯，帮助你在开发阶段消灭问题，而不是在用户机器上爆出段错误。
编译后,通过 ./sapi/cli/php -v 验证你的自定义版本。
提交代码的“黄金路径”
创建分支与修改：
$ git checkout -b fix/bug-81234 $ vim ext/standard/string.c
Commit Message 必须严格遵循格式：
[FIX] Fix #81234: `substr()` returns wrong offset on multibyte strings
The issue was caused by ignoring the `char_len` parameter when
calculating the byte offset. Added explicit check.
Closes GH-1234- 第一行：
[类别]+ 简短描述（不超过 50 字符）。 - 第三行起：详细解释根因。
- 必须以
Closes GH-或Fixes #结尾引用官方 BUG 编号。
生成补丁文件： 这一步骤是 PHP 社区与其他项目差异最大的地方，你不能直接推送 PR，而需要：
$ git format-patch master --stdout > fix-81234.patch
然后将这个 .patch 文件以纯文本正文发送至 internals@lists.php.net，邮件主题务必包含 [PATCH] 前缀。
用邮件列表进行“答辩”
当你的补丁贴出后,通常会在 24-72 小时内收到来自 Nikita Popov 或 Dmitry Stogov 等核心维护者的 review 意见。
你必须学会“防守反击”：
- 态度：回信必须包含
Thanks for the review.开头。 - 修改流程：重新修改代码后，不要发新补丁文件，直接在回复邮件中附上 唯一的增量补丁（
git diff master...），如果改动大，需要重发完整补丁，但必须注明[PATCH v2]。 - 关于冲突：如果被要求
rebase，执行git rebase master后重新生成补丁。禁止使用force push覆盖历史，因为社区通过邮件记录评审过程。
问：如果一直没有回复怎么办？
答：3 天后礼貌在邮件链中回复 Hi everyone, just checking if there are any concerns about this patch?，PHP 社区极度反感催促。
合并之后的那些事
合并意味着你的代码进入了 master 分支，但这只是“长征走完了一半”：
- 测试：必须为你的修复添加测试用例（
.phpt格式），放在ext/standard/tests/string/下。 - UPGRADING 文件：如果改变行为，必须修改
UPGRADING文档。 - 责任感：后续 6 个月内，你需要在
#php.pecl或邮件列表中随时回答来自用户关于此改动的提问。
常见问答（FAQ）
Q1：我能在 GitHub 上提交 PR 吗？
A：官方已不鼓励，GitHub 上的是只读镜像，所有代码变更的唯一通道是 internals@lists.php.net 邮件列表，如果你提交 PR，会被机器人标注“请发送至邮件列表”。
Q2：修改一个 BUG 需要掌握 C 语言到什么程度？
A：至少需要看懂 zend_string, zval, zend_array 这三个核心结构体，建议先读《PHP 7 内核剖析》的前五章。
Q3：贡献代码需要签署 CLA 吗？ A：不需要，PHP 使用宽松的 PHP License 3.01，你拥有自己代码的版权，但授权给 PHP 项目永久使用。
Q4：补丁被拒绝后还能再提交吗？
A：可以，但必须解决提议者指出的逻辑缺陷，如果连续 2 次被拒，强烈建议先在邮件列表发 Discussion: [PROPOSAL] 主题的帖子征求预审意见。
Q5：新手第一次贡献，从哪类代码入手最简单？
A：搜刮 ext/ 目录下已有的测试文件，找其中 --CRASH-- 的 BUG，或者关注 php-src 的 Mark as stale 标签下的旧 issue，难度低且受欢迎。
整个流程看似繁琐,实则是一条精密运转的工程流水线，当你第一次看到自己的代码进入 php-src 的 UPGRADING 时，那种“我在改变语言本身”的实感，会让所有等待和争辩都变得值得。git clone 开始你的旅程吧！
