PHP 源码贡献完全指南从提交 Pull Request 到 Git 提交规范与测试编写php-src【免费下载链接】php-srcThe PHP Interpreter项目地址: https://gitcode.com/GitHub_Trending/ph/php-srcPHP 是一个由庞大社区共同开发和维护的开源项目任何会用 PHP 编程的人都可以成为贡献者——贡献代码、测试、文档乃至参与发布协调。这份指南围绕仓库根目录的 CONTRIBUTING.md 展开结合 php-src 中真实的目录结构、run-tests.php 测试框架与 NEWS 的实例条目系统讲解如何为 PHP 解释器提交 Pull Request、编写回归测试、遵循 Git 提交规范、维护 NEWS 文件让你能够独立走完从「发现 Bug」到「代码合入」的完整贡献流程。贡献者的起点无需特殊权限即可开始PHP 欢迎任何人通过 Pull Request 贡献 测试、修复 Bug 或实现 RFCRequests for Comments。贡献者不需要任何特殊访问权限即可下载、构建、调试并提交 PHP、PECL 代码、测试或文档。当你按照本文档完成几次被接受的贡献后通常很快就能获得提交commit权限。提交 Pull Request 即表示你确认拥有提交该工作的必要权利且该工作不侵犯任何第三方权利包括雇主的权利你的贡献遵循 Modified BSD License 授权除非 PHP 项目维护者明确接受其他许可。目标分支Bug 修到最低活跃分支RFC 提交到 master分支策略是 PHP 贡献流程的核心规则修复 BugPR 应针对该 Bug 影响的最低「活跃支持」分支提交。只有 php.net 支持版本页面中标绿的分支才受支持。例如撰写本文档时最低支持版本为 PHP 8.0对应 Git 中的PHP-8.0分支。注意PHP-x.y.z分支仅用于发布管理绝不可向其提交 PR。实现 RFC提交到master新版本功能的活跃开发分支允许破坏性变更与主要内部 API 变更。新人友好标记为Good first issue的 issue 非常适合新手提交第一个 PR。处理冲突若 PR 与基础分支冲突请用git rebase而非git merge解决。将 PR 链接补充到 bug tracker 的对应 issue 中并在 PHP Internals 邮件列表internalslists.php.net发一条说明有助于获得更快反馈。Git 使用与构建方法可参考仓库内的 Git 工作流文档构建脚本入口见仓库根目录的 buildconf。版本分支的生命周期含义PHP-X.Y 分支用于发布 PHP X.Y.z 系列。各版本状态见支持版本页直接决定你能往该分支提交什么分支状态含义开放范围Active support当前稳定版本仅 Bug 修复Security fixes only旧稳定版本仅安全修复End of life分支关闭不接受变更提交 Bug 与功能请求Bug 报告通过 GitHub Issues 提交建议阅读官方《如何报告 Bug》指南并尽量附带一个自包含的复现用例self-contained reproduction case——可复现的 .phpt 测试往往比文字描述更能帮助维护者定位问题。功能请求通常以 RFC 形式提交先在 PHP Wiki 与扩展维护者及开发邮件列表 internalslists.php.net 讨论再准备 RFC 文档并尽可能附上实现 PR。扩展维护者名单可在仓库根目录的 EXTENSIONS 文件中查到该文件按 SAPI 与扩展列出 PRIMARY MAINTAINER、维护状态与运行状态。此外仓库内还有大量历史 RFC 参考可帮助你理解 PHP 语言演进的方式。PHP 源码目录结构一份给新贡献者的地图了解代码放哪里是高效贡献的前提。文档给出了一份源码布局总览并结合仓库现状整理如下带#注释的行表示由生成器或上游维护产生改动时应去对应生成源/上游修改php-src/ ├─ TSRM/ # Thread Safe Resource Manager线程安全资源管理 ├─ Zend/ # Zend 引擎执行核心 │ ├─ asm/ # 汇编上下文切换由 boostorg/context 上游捆绑 │ ├─ zend_vm_execute.h # 由 Zend/zend_vm_gen.php 生成 │ ├─ zend_vm_opcodes.c/.h # 由 Zend/zend_vm_gen.php 生成 │ ├─ zend_compile.c # 编译器从 AST 到 opcode │ ├─ zend_execute.c # 执行器入口 │ ├─ Optimizer/ # opcache 优化器各趟 pass 实现 │ └─ tests/ # 引擎级回归测试数千个 .phpt ├─ build/ # *nix 构建系统文件autoconf 宏、libtool 等 ├─ docs/ # 仓库内部与贡献相关文档 ├─ ext/ # PHP 核心扩展 │ ├─ skeleton/ # 新扩展模板用 ext/ext_skel.php 生成 │ ├─ zend_test/ # 用于测试内部 API常规构建不需要 │ ├─ standard/ # 基础函数库数组、字符串等 │ ├─ bcmath/ # 内含 libbcmath/ 分叉维护子库 │ └─ date/ # 内含 lib/timelib 日期库 ├─ main/ # 把扩展、SAPI 与引擎绑定的胶水层 │ └─ streams/ # 流streams子系统 ├─ pear/ # PEAR 安装 ├─ sapi/ # SAPI 模块cli、fpm、phpdbg、cgi 等 ├─ scripts/ # php-config、phpize 与内部开发脚本 ├─ tests/ # 核心功能测试 └─ win32/ # Windows 构建系统文件仓库中的大量文件由工具链生成改动时不要直接编辑产物而应修改生成源。典型例子包括Zend/zend_vm_execute.h、zend_vm_opcodes.c/h由 Zend/zend_vm_gen.php 根据 VM 定义生成main/php_version.h由发布经理用configure生成ext/standard/credits_ext.h等由scripts/dev/credits生成扩展捆绑的上游子库如 Zend/asm 的 context 库、date 的 timelib改动应回馈其上游。ext/中每个扩展均可进一步查看其 .phpt 测试目录例如 Zend/tests、tests/lang、ext/standard/tests 中存放着成千上万个测试文件是学习编写测试的最佳范例。编写测试Writing tests为稳定性投资PHP 极其欢迎新测试。仓库中测试采用 PHPT 格式运行于make test底层为 run-tests.php。最朴素的结构包含--TEST--描述、--FILE--被测代码、--EXPECT--期望输出例如 tests/lang/001.phpt--TEST-- Simple If condition test --FILE-- ?php $a1; if($a0) { echo Yes; } ? --EXPECT-- Yes编写测试时的规范要点不要测试参数解析失败路径zend_parse_parameters、ZEND_PARSE_PARAMETERS()等参数解析 API 已被充分测试额外测试只会让未来的修改复杂化相关解析实现见 Zend/zend_API.c。这一点新手常犯务必留意。不再写--CREDITS--段Git 已精确记录作者归属多人合作请用提交信息中的Co-authored-by标记。为 Bug 写回归测试将修复的 Bug 场景固化为 .phpt 测试防止未来回归新测试应能独立运行并通过make test。提交前检查清单与验证在生成最终diff与测试之前请把源码更新到最新 Git 状态然后按以下清单逐一确认先读 Coding standards注意只用/* */风格注释禁用//建议在 CODING_STANDARDS.md 中查阅 C 语言实现规范如优先emalloc()/efree()内存家族、字符串须利用长度属性保证二进制安全、禁止使用strncat()、用户级函数命名规范与类型声明约束。添加内联注释或准备外部文档。为make test编写测试脚本并运行确认没有破坏其他功能。用--enable-debug重新构建能暴露部分内存错误跑完测试后检查 PHP 与 Web 服务器错误日志。配置项在 configure.ac 中定义——它开启调试符号-g、以-O0关闭优化并置ZEND_DEBUGyes相关代码位于 configure.ac 第 823 行附近对应的--enable-debug-assertions则可在发布模式下保留断言。用--enable-zts重新构建验证改动在 PHP 线程安全模式下可编译且行为正确——该选项启用线程安全Thread Safety构建会强制校验系统 POSIX 线程支持见 configure.ac 第 871 行附近的--enable-zts定义。ZTS 与 TSRM线程安全资源管理器紧密相关实现位于 TSRM 目录。提交前再审一遍改动。提交后会发生什么简单改动若容易评审且无副作用可能很快被合入。复杂改动PHP 是志愿者驱动项目请保持耐心。若数日无反馈可考虑 bump但先自问补丁发对邮件列表了吗是否检索过历史讨论变更说明是否清晰改动是否太难评审、为什么合入后你的名字通常会出现在 Git 提交日志中如果改动影响最终用户一段简短描述和你的名字可能被加入 NEWS 文件。Git 提交规则给拥有提交权限的贡献者有 push 权限的贡献者应遵守以下组织与技术规则。组织规则包括尊重他人重大改动先在列表讨论并征得对应分支发布经理确认提交前先查看 EXTENSIONS 确认代码的主维护者与意见不合者私下沟通而非公开争执不懂就问提交前务必make test开发时使用--enable-debug与--enable-zts构建验证。技术性规则所有非安全 Bug 修复先提交到最低 bugfix 分支再逐级向上合并merge up安全修复则先到最低安全支持分支。若某改动不需要并入更新的分支例如修复的是后续版本已删除的功能也要做一次空合并empty merge。所有面向公众的更新进入 NEWS 文件。不要一次性把所有文件塞进一个提交无关文件应分组提交并为每组撰写清晰的提交信息。提交信息要能脱离 diff 独立理解让人一看便知改了什么务必包含函数名。提交信息每行短于 80 字符折行时尽量垂直对齐。修改了可从 PHP 调用的函数时函数名前缀加PHP见下方示例。提交信息格式最多 79 字符的简短描述 空行 长描述每行 79 字符修复 Bug 时在提交信息中标注 Bug 编号例如Fixed GH-14009: Fix prototype for trait method.说明Fixed bug GH-{number} ({issue-description}). ({contributor})是 NEWS 条目格式提交信息使用类似的Fixed GH-...风格以便与 issue 关联。修改 NEWS 时条目须按对应修复版本分组排序。版权与许可证头新建的源码文件必须包含以下头部块也可见 run-tests.php 开头的实际应用/* ---------------------------------------------------------------------- | Copyright © The PHP Group and Contributors. | ---------------------------------------------------------------------- | This source file is subject to the Modified BSD License that is | | bundled with this package in the file LICENSE, and is available | | through the World Wide Web at https://www.php.net/license/. | | | | SPDX-License-Identifier: BSD-3-Clause | ---------------------------------------------------------------------- | Author: | ---------------------------------------------------------------------- */NEWS 文件记录每一次用户可见的变更NEWS 的目的是记录所有对用户与开发者有意义的变更——Bug 修复、新功能、语法变更或弃用。NEWS 的书写格式版本节头使用{DD} {MMM} {YYY}, PHP {version}格式例如06 Jun 2024, PHP 8.1.29。每节内条目按扩展名字母序排列唯一的例外是Core必须排在最前。每个扩展以- {name}:开头。每条目缩进两个空格以.句点加空格开始正文。条目必须大写开头并以句点结束句点在{issue-description}之外。每条目后可附贡献者名字、php.net 账号名或 GitHub 用户名。条目每行不超过 80 字符。Bug 修复条目必须使用Fixed bug GH-{number} ({issue-description}). ({contributor})格式少数来自旧版 bug 系统的修复则用Fixed bug #{number} (...). (...)。Bug 修复条目应聚类并按 issue 编号排序{issue-description}应概括修复本身而非用户原始报告。仓库 NEWS 顶部的真实条目可作为范例31 Jul 2025, PHP 8.5.0alpha4 - Core: . Added PHP_BUILD_PROVIDER constant. (timwolla) . Fixed bug GH-16665 (\array and \callable should not be usable in class_alias). (nielsdos) . Fixed bug GH-19326 (Calling Generator::throw() on a running generator with a non-Generator delegate crashes). (Arnaud) - OPcache: . Make OPcache non-optional. (Arnaud, timwolla) - OpenSSL: . Add $digest_algo parameter to openssl_public_encrypt() and openssl_private_decrypt() functions. (Jakub Zelenka)哪个分支更新 NEWS按修复类型与发布周期决定更新哪些分支的 NEWS安全修复更新最低的安全支持分支以及每个更新的分支除非已打 alpha 标签且尚未创建发布分支否则不包含 master。Bug 修复更新最低的支持分支及每个更新的分支master 同样仅在已打 alpha、且尚未创建发布分支时才包含。新增功能只更新 master。若某个功能严格被政策禁止地引入在低于 master 的分支其 NEWS 条目也必须出现在 master。PECL 扩展与文档贡献PECL 扩展修复 PECL 扩展时先在 bugs.php.net或该扩展自己的 bug tracker创建或定位 Bug 以便追踪进度。大改动应创建 RFC 并与扩展维护者、pecl-devlists.php.net 讨论提交时把补丁或指向 Bug 的链接发到该列表并抄送维护者附上变更说明与测试脚本。手册文档PHP 手册的编辑是通过 Git 检出 XML 源并按文档站点的教程进行编辑与构建涉及手册类改动请走 phpdoclists.php.net 文档邮件列表。获取帮助与沟通渠道遇到贡献问题internals 邮件列表internalslists.php.net文档问题走 phpdoclists.php.net。虽然不是正式渠道许多核心开发者也活跃于 PHP 社区 Discord#php-internals频道。LLM 使用披露当使用 LLM 生成给维护者的评论直接翻译除外时PHP 社区希望你能用 markdown 引用块标注相应段落保持评审透明。总结从新手到合入的最小路径最后把完整的贡献流程浓缩成一张可执行的检查单在 EXTENSIONS 找到目标代码的维护者在 GitHub Issues或旧 bug tracker确认/创建 Bug用git clone拉取仓库切到受影响的最低支持分支Bug 修复或masterRFC 实现先通读 CODING_STANDARDS.md再修改源码——只加/* */注释尊重内存所有权与二进制安全约定为你的改动编写 .phpt 回归测试参考 tests/lang、Zend/tests 中的既有用例不测参数解析失败路径、不加--CREDITS--分别用普通构建、--enable-debug与--enable-zts运行make test验证按「提交信息格式」分组提交标明Fixed GH-xxxxx与函数名必要时同步维护对应分支的 NEWS提交 PR 到正确分支把 PR 链接补回 Bug 报告并在 internalslists.php.net 通报以加速评审。PHP 是全世界被使用最广泛的语言之一而你提交的每一个测试与修复最终都会随下一个版本抵达数以亿计的最终用户。感谢你为 PHP 贡献力量。【免费下载链接】php-srcThe PHP Interpreter项目地址: https://gitcode.com/GitHub_Trending/ph/php-src创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
