PHP 怎么贡献源码

PHP 怎么贡献源码？从零到合并的完整指南（核心流程与避坑策略）**

目录导读

1. 为什么贡献 PHP 源码？ —— 不只是“为爱发电”
2. 前期准备：环境、工具与心理建设
3. 核心流程：从 Fork 到 Pull Request 的九步走
4. 代码规范与评审雷区（RFC 与 Coding Style）
5. 高频问答（Q&A）：新手最易踩的 5 个坑
6. 进阶建议：如何让你的补丁被“优先”合并

为什么贡献 PHP 源码？ 很多开发者认为“贡献 PHP 源码”是内核专家（如 Dmitry Stogov）的专利，实则不然，PHP 语言本身由 Zend Engine 与 PHP Standard Code（即 ext/ 目录下的标准库） 组成，贡献源码不仅能提升个人技术影响力，更重要的是：你在为全球 78% 的 Web 服务器（W3Techs 数据）底层生态加固，对于求职而言，一个被 PHP 官方合并的 Commit，其含金量远超普通项目 Star 数。

前期准备：环境与心理

1. 环境要求：Linux/macOS 最佳（Windows 需用 WSL2），必须安装 git、autoconf、gcc、make、pkg-config，PHP 源码不通过 Composer 安装，需从 GitHub 克隆。
2. 心理建设：请先阅读官方文档 CONTRIBUTING.md 和 CODING_STANDARDS.md，记住一句话：“补丁不是写给自己看的，是写给 20 年后的维护者看的。”

核心流程：从 Fork 到 PR 的九步走（关键实操）

1. Fork 官方仓库：访问 github.com/php/php-src，点击 Fork（务必基于 master 分支创建新分支）。
2. 本地同步：git clone 你的 Fork 地址，添加官方源为 upstream：git remote add upstream https://github.com/php/php-src.git。
3. 编译前准备：运行 ./buildconf 和 ./configure --disable-all --enable-debug 开启调试模式。注意：务必使用 --enable-debug 检测内存泄漏（Zend MM 会根据此宏生效）。
4. 编写测试（TDD 思维）：PHP 官方要求任何 bugfix 必须附带 PHPT 测试文件，测试文件放置在 ext/standard/tests/ 对应目录，格式示例：

   --TEST--
   Bug #78999 (描述)
   --FILE--
   <?php
   var_dump(str_contains("hello", "ell")); // 假设这是新函数
   ?>
   --EXPECT--
   bool(true)

5. 修改源码：如果你要修改 ext/standard/string.c，请遵循 C89 风格（虽然新代码允许 C99，但禁止使用 C++ 注释 ）。
6. 本地验证：运行 make test TESTS=ext/standard/tests/your_test.phpt 必须通过，同时跑 make test 全量回归（时间较长，可只跑相关扩展）。
7. 风格检查：运行 ./scripts/check_stubs.php 或使用 clang-format（规则见 .clang-format 文件）。关键点：变量命名必须全小写+下划线，函数注释块必须含 @param 和 @return 类型。
8. 提交 Commit：提交信息格式为 Fix #78999: 描述 或 Implement RFC: 标题。严禁使用 Update file.c 这种无意义描述。
9. Push 并创建 PR：去 GitHub 提交 PR，勾选 I have read the CONTRIBUTING guide。等待 CI 通过（2-3 小时），若有失败点击 Details 查看日志。

代码规范与评审雷区（RFC 与 Coding Style）

• RFC（Request for Comments） 是关键：如果你要新增函数或改变行为，必须先在 wiki.php.net/rfc 发起投票，否则 PR 会被直接关闭。
• 变量声明：所有局部变量必须在代码块顶部声明（C89 遗留风格）。
• 内存管理：PHP 宏 ZEND_STR_ALLOC 必须配对 zend_string_release，禁止使用裸 malloc。

高频问答（Q&A）：新手最易踩的坑

• Q1：我改了源码，但本机编译不过怎么办？
  • A：先执行 make clean 清除缓存，若报错 undefined reference to 'zend_ce_throwable'，多半是 #include "zend_exceptions.h" 缺失，若出现 conflicting types，检查你的函数命名是否与全局宏冲突（如 hash）。
• Q2：如何快速定位到要修改的 C 文件？
  • A：grep -rn "php_function_name" ext/ ，已知常量搜索：grep -rn "PHP_STR_ICASE" ext/standard/。
• Q3：我的 PR 提交后没有 CI 反应？
  • A：检查是否 Fork 自 php/php-src 主分支（非镜像），且需加入 PHP 组织下的 php-dev 邮件列表，否则 CI 可能不触发。
• Q4：测试文件必须用英文吗？
  • A：--TEST-- 注释必须用英文，但 --FILE-- 中的输出字符串内可含非 ASCII 字符（需声明 --CLEAN-- 清理临时文件）。
• Q5：Zend 引擎的修改和 ext 扩展的修改，难度差异大吗？
  • A：极差异巨大，Zend 引擎（Zend/ 文件夹）涉及 GC（垃圾回收）和 VM（虚拟机），需精通《PHP 内核深度剖析》这类书，对于新手，建议从修改 ext/standard 的数学函数或字符串函数入手，如增加一个 array_column 的第三个参数功能。

进阶建议：如何让你的补丁被“优先”合并

1. 先提 Issue，后提 PR：这是铁律，在 Issue 中描述场景并 @nikic（现任核心维护者）确认，不要直接提 PR 要求合入。
2. 小步快跑：一个 PR 只解决一个问题，PHP 维护者最讨厌“顺手改个缩进”的混合 diff。
3. 加入 IRC 频道：在 Libera.Chat 的 #php.pecl 频道潜水，提问时附上你的 PR 链接，很多资深开发者会给你内幕建议。
4. 性能数据：如果你在修改数组遍历，请附上 bench.php 的基准对比（在 Zend/bench.php 跑分）。数字是最大的说服力。

结尾行动号召：不要怕被拒绝，PHP 社区每年会收到几千个 Patch，但合并率不足 20%，按照本指南流程操作，即便第一次被要求修改，也意味着你的代码进入了资深维护者的视野，从今天开始，试试为 PHP 改进一个 str_contains 的边界情况吧！