PAYATHON 2026

如何在 Windows 上编译 PECL http 扩展 .dll(ext_http)

技术老齐

结论

可以编译,不过现有步骤需要调整三处:

  1. Debug Pack 主要提供调试符号。编译扩展所需的 phpize.bat、头文件和构建配置位于 Development package 中。
  2. 安装 Visual Studio Build Tools 并将 PHP 加入 PATH 后,仍需进入 PHP 官方的 Windows 构建 SDK 环境。
  3. 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 和工具版本冲突。

备注:内容仅供参考。