如何在 Windows 上编译 PECL http 扩展 .dll(ext_http)
结论
可以编译,不过现有步骤需要调整三处:
Debug Pack主要提供调试符号。编译扩展所需的phpize.bat、头文件和构建配置位于Development package中。- 安装 Visual Studio Build Tools 并将 PHP 加入
PATH后,仍需进入 PHP 官方的 Windows 构建 SDK 环境。 - GnuWin32 的 Bison 2.4.1 版本过旧,不适用于当前的 PHP 构建流程。PHP SDK 会准备兼容版本的 Bison、Flex 和其他构建工具,不需要自行编译
bison.exe。
PECL http 生成的 DLL 通常名为 php_http.dll,不是 ext_http.dll。它还依赖 raphf,所以不能只下载 ext_http 源代码并直接执行 phpize。
先确认 PHP 的 ABI
编译出的 DLL 必须与正在运行的 PHP 完全匹配。先执行:
php -i | findstr /I "PHP Version Architecture Thread Safety Compiler Debug Build"
至少需要确认:
- PHP 版本:
8.1.26 - 架构:
x64或x86 - Thread Safety:
enabled表示 TS,disabled表示 NTS - Compiler:PHP 8.1 官方 Windows 构建通常显示
Visual C++ 2019 - Debug Build:正式发行包通常为
no
以 PHP 8.1.26 x64 TS VS16 为例,需要使用:
- PHP 8.1.26 源代码
- VS16,也就是 Visual Studio 2019 工具链
- x64 构建环境
- TS 配置
- 非 Debug 配置
x64、x86、TS、NTS、Debug 和 Release 不能混用。即使 PHP 小版本相同,只要 ABI 配置不同,也可能出现 The specified module could not be found、%1 is not a valid Win32 application,甚至在启动时崩溃。
准备构建工具
安装 Visual Studio Build Tools 2019 时,至少选择以下组件:
- Desktop development with C++
- MSVC v142 build tools
- Windows 10 SDK
还要准备:
- PHP SDK Binary Tools
- PHP 8.1.26 source package
- 与目标环境一致的 PHP 8.1.26 Development package
- 与 PHP 8.1 兼容的
raphf发布包 - 与 PHP 8.1 兼容的
pecl_http发布包
Development package 和 PHP 源代码是两种不同的包。前者用于构建扩展,后者用于构建完整的 PHP 源码树。
建议使用 PECL 发布包,不要随意选择 Git 仓库中的分支或快照。仓库源码可能缺少已经生成的文件,也可能需要额外运行生成器,进而引入 Bison、re2c 等工具及其版本要求。
PECL 页面上的最新版本未必支持 PHP 8.1。应查看各版本声明的 PHP 版本范围,不能只按版本号选择。由于具体版本取决于实际下载的发布包,这里无法给出固定的 http 或 raphf 版本号。
推荐方法:在 PHP SDK 中构建
以下步骤以 PHP 8.1.26 x64 TS VS16 为例,目录可按实际情况调整。
1. 打开 PHP SDK Shell
进入 PHP SDK 目录,启动对应的构建环境,不要直接使用普通的 VS Cross Tools Command Prompt:
phpsdk-vs16-x64.bat
如果目标 PHP 是 x86,则使用:
phpsdk-vs16-x86.bat
进入 SDK Shell 后,检查各项工具:
where cl
where bison
bison --version
where nmake
此时不应再调用 GnuWin32 目录中的 bison.exe。如果 where bison 首先返回 GnuWin32 路径,请从当前 PATH 中移除该路径,或者将 PHP SDK 的工具目录移到它前面。
2. 创建构建树并下载依赖
不同版本的 PHP SDK Binary Tools 在命令和目录结构上可能略有不同。常见流程是:
phpsdk_buildtree phpdev
cd phpdev\vs16\x64
phpsdk_deps --update --branch 8.1
如果当前 SDK 不接受 --branch 8.1,运行以下命令查看它支持的参数:
phpsdk_deps --help
不同 SDK 版本的参数可能有差异,应以当前版本的帮助信息为准。
3. 放置源码
将 PHP 8.1.26 源代码解压到构建树,例如:
C:\php-sdk\phpdev\vs16\x64\php-src-8.1.26
再将 PECL 扩展的发布包分别解压到 PHP 源码的 ext 目录,并将目录名改为扩展名:
php-src-8.1.26\
└─ ext\
├─ raphf\
│ ├─ config.w32
│ └─ ...
└─ http\
├─ config.w32
└─ ...
确认 ext\raphf\config.w32 和 ext\http\config.w32 都存在。常见错误是目录多嵌套了一层,例如:
ext\http\pecl_http-4.x.x\config.w32
构建系统无法正确识别这种目录结构。
某些较老的 pecl_http 版本还依赖 propro。是否需要该扩展,应查看所选发布包的依赖声明和 config.w32。如果配置阶段报告缺少 propro,需要换用正确的扩展版本,或者将兼容的 propro 源码一并放入 ext 目录。
4. 重新生成配置
进入 PHP 源码目录:
cd C:\php-sdk\phpdev\vs16\x64\php-src-8.1.26
buildconf
然后检查构建系统是否已经识别扩展:
configure --help | findstr /I "http raphf"
如果帮助信息中没有相关选项,请检查:
- 扩展目录是否直接位于
ext下 - 目录中是否存在
config.w32 - 扩展版本是否提供 Windows 构建配置
- 添加扩展后是否重新执行了
buildconf
5. 配置 TS 或 NTS
对于 x64 TS Release,可以先尝试:
configure --enable-raphf=shared --enable-http=shared
对于 x64 NTS Release,需要关闭 ZTS:
configure --disable-zts --enable-raphf=shared --enable-http=shared
不建议一开始就使用 --disable-all。http 可能依赖 PHP 自带扩展或外部库,关闭所有默认组件会增加依赖检查的复杂度。
不同 pecl_http 版本提供的配置选项可能不同,先查看当前版本的实际选项:
configure --help
如果 configure 不接受 --enable-http,但帮助信息中列出了 --with-http,就使用 --with-http。不要直接套用其他版本教程中的参数。
6. 编译
nmake
需要重新开始时,可以执行:
nmake clean
buildconf
configure --enable-raphf=shared --enable-http=shared
nmake
输出目录取决于架构、TS/NTS 和 Debug/Release 配置,常见位置包括:
x64\Release_TS\php_http.dll
x64\Release_TS\php_raphf.dll
x64\Release\php_http.dll
x64\Release\php_raphf.dll
具体位置以 nmake 最后的输出和实际生成目录为准。
安装并测试 DLL
将生成的扩展复制到目标 PHP 的扩展目录。可以先查看当前目录:
php -i | findstr /I "extension_dir"
在 php.ini 中按照依赖顺序加载:
extension=php_raphf.dll
extension=php_http.dll
然后检查扩展是否正常加载:
php --ini
php -m
php --ri raphf
php --ri http
也可以用下面的命令直接检查启动错误:
php -n -d extension_dir=C:\php\ext ^
-d extension=php_raphf.dll ^
-d extension=php_http.dll ^
-m
如果 php_http.dll 还依赖 libcurl.dll、libevent.dll、ICU 或其他运行库,Windows 也必须能够找到这些 DLL。通常可将它们放在 php.exe 所在目录,或放入当前进程能够搜索到的 PATH。具体依赖由构建时启用的功能决定,各版本可能不同。
可以使用 Visual Studio 的相关工具检查依赖:
dumpbin /dependents C:\php\ext\php_http.dll
可以使用 phpize 单独构建吗
可以。不过 http 依赖其他扩展,单独构建时更容易遇到编译顺序和头文件安装问题。通常需要先编译并安装 raphf:
cd C:\src\raphf
C:\php-devel\phpize.bat
configure --enable-raphf=shared
nmake
nmake install
再编译 http:
cd C:\src\http
C:\php-devel\phpize.bat
configure --enable-http=shared
nmake
这套流程仍需在架构匹配的 PHP SDK Shell 中运行。只把 php.exe 所在目录加入 PATH,不会自动提供 Bison、编译器配置、PHP 头文件和第三方库。
如果编译 http 时找不到 raphf 的头文件,说明 nmake install 没有将开发文件安装到构建系统预期的位置。遇到这种情况,使用完整的 PHP 源码树同时构建 raphf 和 http,一般更容易控制。
Bison 3.0 错误的原因
这个错误通常说明构建过程找到了不符合要求的 bison.exe,或者当前命令行并未运行在 PHP SDK 环境中,并不意味着需要自行编译 Windows 版 Bison。
先执行:
where bison
bison --version
如果输出类似:
C:\Program Files (x86)\GnuWin32\bin\bison.exe
说明系统优先找到了旧版 GnuWin32。移除该路径,重新打开 PHP SDK Shell,然后再次运行 buildconf 或 phpize。
不要同时打开多个命令行环境并混用它们的 PATH。PHP SDK Shell 会设置编译器、目标架构和构建工具路径。
常见失败原因
- 将 Debug Pack 当作 Development package。
- 使用 x86 工具编译 x64 DLL,或者使用 x64 工具编译 x86 DLL。
- 目标 PHP 是 NTS,扩展却按 TS 编译。
- 使用 VS2022 构建要求 VS2019 ABI 的 PHP 扩展。
- PHP 是 Debug 构建,扩展却使用 Release 配置。
- 从 Git 仓库下载源码后缺少生成文件。
http和raphf的版本不兼容。- 没有先加载
php_raphf.dll。 - 系统优先找到了 GnuWin32 的旧版 Bison。
- 复制了
php_http.dll,却遗漏了它依赖的运行库 DLL。 - 修改源码或扩展目录后,没有重新运行
buildconf。 - 混用了不同 PHP 小版本的源代码、Development package 和运行环境。
较稳妥的做法是使用 PHP 8.1.26 的源码和 Development package,在 VS16 对应的 PHP SDK Shell 中,根据目标 PHP 的 x64/x86、TS/NTS 和 Debug/Release 配置,同时构建 raphf 和 http。这样能避开大部分 ABI 和工具版本冲突。
备注:内容仅供参考。
