ConFoo 2025

在 Windows 上安装 PHP 扩展

在 Windows 上有两种加载 PHP 扩展的方式:把扩展编译进 PHP,或者加载 DLL。加载预编译的扩展是更简单更被推荐的方式。

要加载扩展,需要在系统中有可用的 .dll 文件。所有扩展都会由 PHP 小组定期自动编译(如何下载见下节)。

要将扩展编译入 PHP,请参考从源程序编译文档。

要编译一个独立的扩展(即 DLL 文件),请参考从源程序编译文档。如果在 PHP 发行版和 PCEL 中都没有某 DLL 文件,那可能需要编译之后才能使用该扩展。

去哪里找扩展库?

PHP 扩展库通常称为 php_*.dll(其中星号代表具体某扩展的名字),位于 PHP\ext 目录下。

PHP 发行包中包括了大多数开发者最常用到的扩展库。称为捆绑扩展库。

不过,如果捆绑扩展没有提供所需的功能,可以在 » PECL 中找到满足需求的扩展。PHP 扩展社区库(PHP Extension Community Library 简称 PECL)是个 PHP 扩展的储存库,提供了对于所有已知扩展目录以及下载及开发 PHP 扩展的托管设施。

如果针对特定用途开发了扩展,则可以将其托管在 PECL 中以便于其他有相同需求的用户使用。这样做的好处就是可以得到其他用户的反馈、感谢、错误报告甚至修复/补丁。不过在向 PECL 提交扩展之前,请先阅读 » PECL 提交指南

下载哪个扩展?

很多时候,每个 DLL 都有几个版本可供选择:

  • 不同的版本号(至少前两个数字要一致)
  • 不同的线程安全性设定
  • 不同的处理器体系(x86,x64,...)
  • 不同的排错设定
  • 其它

请记住,扩展设置应该与所使用的 PHP 可执行文件的设置相匹配。以下脚本可以显示所有 PHP 设置:

示例 #1 调用 phpinfo()

<?php
phpinfo
();
?>

或者在命令行运行:

drive:\path\to\php\executable\php.exe -i

载入一个扩展

最常见的方式是在 php.ini 配置文件里包含一个 PHP 扩展。请注意很多扩展已经在 php.ini 里了,仅需要移除分号来激活它们。

需要注意,从 PHP 7.2.0 开始,可以直接用扩展的名称,来替代扩展的文件名。这样配置文件就跟操作系统解耦了,也更容易理解。推荐采用此方式加载扩展。为了与之前的版本保持兼容,直接写扩展名的方式会仍然支持。

;extension=php_extname.dll
extension=php_extname.dll
; 自 PHP 7.2.0 起首选:
extension=extname
zend_extension=another_extension

不过呢,有些 web 服务器会搞混,因为其并不一定使用和 PHP 可执行文件处于同一目录下的 php.ini 文件。要搞清楚具体使用了哪一个 php.ini 文件,在 phpinfo() 的输出中查看:

Configuration File (php.ini) Path  C:\WINDOWS
Loaded Configuration File   C:\Program Files\PHP\8.2\php.ini

激活一个扩展后,保存 php.ini 文件并重启动 web 服务器,然后用 phpinfo() 再次查看确定。新的扩展应该有其自己的一节。

解决问题

如果某扩展并未在 phpinfo() 中显示,应该查看日志以确定问题出在哪里。

如果是在命令行中(CLI)使用 PHP,扩展加载出错信息会直接在屏幕显示。

如果在 web 服务器中使用 PHP,则日志文件的位置与格式各不相同。请阅读所使用的 web 服务器之文档以确定日志文件的位置,这与 PHP 本身并无关系。

最常见的问题是 DLL 和 DLL 依赖的文件的位置,php.ini 中“extension_dir”设置的值,以及编译时的设置不匹配。

如果问题出在编译时设置不匹配,那可能所下载的 DLL 文件不对。可以尝试使用正确的设置重新下载扩展。此外,phpinfo() 可以起到很大帮助。

添加备注

用户贡献的备注 4 notes

up
5
j dot o dot l dot a dot n at bk dot ru
11 months ago
In order for php to see extensions, it is necessary to specify the root folder when specifying the address to the directory with extensions in php.ini. For example extension_dir = "php/ext"
up
3
bk at kaelberer-aio dot de
1 year ago
In addition to the helpful comments of ferdnyc and dario: A few weeks ago I've set up a new W11 using PHP 8.1. (as a module) with Apache. It was working fine.
Today i wanted to install the PECL-extension php-amqp. This extension comes with two additional files that are said to be placed in PHPs main directory. It worked fine running from the command prompt but with Apache the extension failed with "Unable to load dynamic library 'amqp'".
I tried 100 ways to notate paths in php.ini and http.conf: c:, C:, \, \\, /, ". I also installed a new PHP in the root to get rid of the space in the path. It did not help.
When reading dario's comment i stumbeled across him mentioning "path environment variable". I checked that in Window's settings and I realized, that i had added PHP's path to the USER'S path-settings, but not to the SYSTEM'S path. That is why it worked in the command prompt but not when starting Apache as a service. After adding it there it worked fine.
up
1
dario at 4assistance dot com
1 year ago
On windows, drop your extension's dependencies into a dir of your choice, but outside of your php install. Add that dir to a path environment variable used by your php. Add <extension_name>.dll to your php's extension_dir, and update your php.ini (unless you're simply testing with php's cli).
up
0
ferdnyc at gmail dot com
2 years ago
This is handwaved somewhat in the "Resolving problems" section, but mis-location of (non-extension) DLL files is often a problem when installing PHP extensions on Windows.

Many PHP extensions come with not only the extension DLL, but supplementary DLLs that are required by that extension. (For example, php_luasandbox.dll comes with lua5.1.dll, the lua interpreter it sandboxes.) Those other DLLs should go into the same directory as the php.exe binary, NOT the extension directory.

So, if php_luasandbox.dll is installed at C:\PHP8.1\ext\php_luasandbox.dll, the interpreter would be located at C:\PHP8.1\lua5.1.dll. That allows the PHP binary C:\PHP8.1\php.exe to find those additional DLLs when required.
To Top