在官方 PHP Docker 镜像中轻松安装 PHP 扩展

本仓库包含一个脚本，可用于在https://hub.docker.com/_/php/%E4%B8%AD%E8%BD%BB%E6%9D%BE%E5%AE%89%E8%A3%85 PHP 扩展。

该脚本会安装所有必要的 APT/APK 包；脚本执行结束时，将移除不再需要的包，从而显著减小镜像体积。

支持的 Docker 镜像包括：

• 基于 Debian 的 Docker 镜像：从 jessie（Debian 8）开始（最低 PHP 版本：5.5）
• 基于 Alpine 的 Docker 镜像：从 Alpine 3.9 开始（最低 PHP 版本：7.1）

另请参见特殊要求部分中的说明。

使用方法

在 Dockerfile 中使用此脚本有多种方式。

以下是安装 GD 和 xdebug PHP 扩展的 Dockerfile 示例列表：

使用 ADD 动态下载脚本

FROM php:7.2-cli

ADD --chmod=0755 https://github.com/mlocati/docker-php-extension-installer/releases/latest/download/install-php-extensions /usr/local/bin/

RUN install-php-extensions gd xdebug

使用 curl 动态下载脚本

FROM php:7.2-cli

RUN curl -sSLf \
-o /usr/local/bin/install-php-extensions \
https://github.com/mlocati/docker-php-extension-installer/releases/latest/download/install-php-extensions && \
chmod +x /usr/local/bin/install-php-extensions && \
install-php-extensions gd xdebug

使用 curl 直接执行

FROM php:8.2-cli

RUN ( curl -sSLf https://github.com/mlocati/docker-php-extension-installer/releases/latest/download/install-php-extensions -o - || echo 'return 1' ) | sh -s \
gd xdebug

从 Docker 镜像复制脚本

• 使用 GitHub Container Registry

FROM php:8.4-cli

COPY --from=ghcr.io/mlocati/php-extension-installer /usr/bin/install-php-extensions /usr/local/bin/

RUN install-php-extensions gd xdebug

• 使用 Docker Hub

FROM php:8.4-cli

COPY --from=mlocati/php-extension-installer /usr/bin/install-php-extensions /usr/local/bin/

RUN install-php-extensions gd xdebug

[!WARNING] 使用此方法可能会使用过时版本的 Docker 镜像。建议运行docker pull ghcr.io/mlocati/php-extension-installer或docker pull mlocati/php-extension-installer以使用最新版本。

使用 Docker 镜像中的脚本

• 使用 GitHub Container Registry

RUN --mount=type=bind,from=ghcr.io/mlocati/php-extension-installer:latest,source=/usr/bin/install-php-extensions,target=/usr/local/bin/install-php-extensions \
install-php-extensions gd xdebug

• 使用 Docker Hub

RUN --mount=type=bind,from=mlocati/php-extension-installer:latest,source=/usr/bin/install-php-extensions,target=/usr/local/bin/install-php-extensions \
install-php-extensions gd xdebug

[!WARNING] 使用此方法可能会使用过时版本的 Docker 镜像。建议运行docker pull ghcr.io/mlocati/php-extension-installer或docker pull mlocati/php-extension-installer以使用最新版本。

安装特定版本的扩展

只需在模块名称后添加-。例如：

install-php-extensions xdebug-2.9.7

脚本还支持通过在版本前添加插入符号（^）来解析兼容版本。例如：

# 安装最新的 xdebug 2.x 版本（如 2.9.8）
install-php-extensions xdebug-^2
# 安装最新的 xdebug 2.8.x 版本（如 2.8.1）
install-php-extensions xdebug-^2.8

请注意，使用上述语法将获取最新的兼容版本，该版本可能不稳定。若要安装最新的稳定版本，可添加后缀@stable：

# 安装最新的稳定版 xdebug 3.x 版本（如 3.2.2）
install-php-extensions xdebug-^3@stable

（有效的后缀包括：@snapshot、@devel、@alpha、@beta 和 @stable）

PECL 上可用的预发布版本扩展可通过在扩展名称后添加其状态（即alpha、beta、rc、preview、devel 或 snapshot）来安装。例如：

install-php-extensions xdebug-beta

提示：当 PECL 上的最新版本不稳定，而你希望保留最新稳定版本时，可通过在扩展名称后添加stable状态来强制安装。例如：

install-php-extensions mongodb-stable

从源代码安装扩展

你也可以从源代码安装 PHP 扩展（前提是源代码包含package.xml或package2.xml文件）。

支持的格式如下：

• GitHub 托管仓库的简短格式。例如，对于 https://github.com/php-memcached-dev/php-memcached GitHub 仓库，可简写成：

# 从特定提交安装（完整提交 SHA-1）
install-php-extensions php-memcached-dev/php-memcached@8f106564e6bb005ca6100b12ccc89000daafa9d8
# 从特定提交安装（简短提交 SHA-1）
install-php-extensions php-memcached-dev/php-memcached@8f106564e6bb
# 从标签 v3.2.0RC2 安装
install-php-extensions php-memcached-dev/php-memcached@v3.2.0RC2
install-php-extensions php-memcached-dev/php-memcached@refs/tags/v3.2.0RC2
# 从分支 master 安装
install-php-extensions php-memcached-dev/php-memcached@master
install-php-extensions php-memcached-dev/php-memcached@refs/heads/master

• 提供源代码归档的 URL。例如：

# 提交 8f106564e6bb005ca6100b12ccc89000daafa9d8 的 tgz 归档
install-php-extensions https://codeload.github.com/php-memcached-dev/php-memcached/tar.gz/8f106564e6bb005ca6100b12ccc89000daafa9d8
# 标签 v3.1.5 的 tgz 归档
install-php-extensions https://codeload.github.com/php-memcached-dev/php-memcached/tar.gz/refs/tags/v3.1.5
# 分支 master 的 tgz 归档
install-php-extensions https://codeload.github.com/php-memcached-dev/php-memcached/tar.gz/refs/heads/master

• 本地目录的绝对路径。例如：

# 下载源代码
curl -o /tmp/source.tgz https://codeload.github.com/php-memcached-dev/php-memcached/tar.gz/refs/tags/v3.1.5
tar xzf /tmp/source.tgz -C /tmp
install-php-extensions /tmp/php-memcached-3.1.5

是否为内置扩展？

有些扩展内置在 PHP 源代码中（例如 gd 和 zip）。

其中部分扩展也可在 PECL 和/或源代码仓库中获取。

默认情况下，install-php-extensions 安装内置版本。

若要使用远程版本：

• 对于 PECL：只需在包名后添加稳定性标识。例如：

install-php-extensions zip-stable

• 对于源代码安装：使用上文指定的语法。例如：

install-php-extensions php/pecl-database-oci8@7aa1061

安装 composer

您还可以安装 composer，并且可以指定其主版本或完整版本。

示例：

# 安装最新版本
install-php-extensions @composer
# 安装最新的 1.x 版本
install-php-extensions @composer-1
# 安装特定版本
install-php-extensions @composer-2.0.2

配置

您可以通过环境变量配置脚本行为，并微调某些扩展以满足需求。

以下是示例：

IPE_LZF_BETTERCOMPRESSION=1 install-php-extensions lzf

以下是所有支持的环境变量列表：

测试

提交拉取请求时，会执行一个https://github.com/mlocati/docker-php-extension-installer/blob/master/.github/workflows/test-extensions.yml%E6%9D%A5%E6%A3%80%E6%9F%A5%E5%8F%97%E5%BD%B1%E5%93%8D%E7%9A%84PHP%E6%89%A9%E5%B1%95%E6%98%AF%E5%90%A6%E5%AE%9E%E9%99%85%E5%8F%AF%E7%94%A8%EF%BC%88%E8%A7%81%E4%B8%8B%E6%96%87%EF%BC%89%E3%80%82

此外，我们还会检查PECL仓库中扩展的新版本是否仍然可用。这通过另一个https://github.com/mlocati/docker-php-extension-installer/blob/master/.github/workflows/test-recent-extensions.yml%E6%8C%89%E8%AE%A1%E5%88%92%E6%89%A7%E8%A1%8C%E3%80%82%E5%A6%82%E6%9E%9C%E5%A4%B1%E8%B4%A5%EF%BC%8C%E4%BC%9A%E5%90%91***%E9%A2%91%E9%81%93%E5%8F%91%E9%80%81%E6%B6%88%E6%81%AF%E3%80%82%E6%AC%A2%E8%BF%8E%E8%AE%A2%E9%98%85%E8%AF%A5%E9%A2%91%E9%81%93%E4%BB%A5%E6%8E%A5%E6%94%B6%E5%A4%B1%E8%B4%A5%E9%80%9A%E7%9F%A5%E3%80%82

如何贡献

代码格式化

提交任何拉取请求之前，您应执行 scripts 目录中的 lint 脚本（Windows 上为 lint.bat）。

如果不这样做，且存在编码风格错误，您会看到 Check shell coding style 和/或 Check PHP coding style GitHub Action 失败。错误信息大致如下：

--- filename.orig
+++ filename
@@ -line number,7 +line number,7 @@
good line of code #1
good line of code #2
good line of code #3
- the original line with a wrong coding style
+ the line wrong coding style that has been corrected
good line of code #4
good line of code #5
good line of code #6

因此，您需要修复高亮行（line number 处的行），将 - 后面的内容替换为 + 后面的内容。

添加对新PHP扩展的支持？

1. 修改 install-php-extensions 脚本
2. 更新 data/supported-extensions 文件，添加一行新内容，包含扩展的句柄和支持的 PHP 版本列表
3. 如果扩展需要 ZTS 镜像：在 data/special-requirements 文件中添加一行，格式为扩展句柄后接空格和 zts

示例请参见https://github.com/mlocati/docker-php-extension-installer/pull/60%E3%80%82

为已支持的PHP扩展更改支持的PHP版本？

1. 修改 install-php-extensions 脚本
2. 更新 data/supported-extensions 文件，将新的 PHP 版本添加到对应扩展的现有行中

示例请参见https://github.com/mlocati/docker-php-extension-installer/pull/62%E3%80%82

改进已支持扩展的代码？

如果您修改的代码影响一个或多个扩展，请在拉取请求的某个提交消息中添加一行 Test: extension1, extension2。这样，即使您没有修改 data/supported-extensions 文件，测试作业也会检查这些扩展。

提交消息示例如下：

Improve the GD and ZIP extensions

Test: gd, zip

测试一次仅检查单个 PHP 扩展的安装。如果您想同时测试安装多个 PHP 扩展，请使用如下提交消息：

Improve the GD and ZIP extensions

Test: gd+zip

如果您的拉取请求包含多个提交，我们会检查每个提交的“Test:”消息。如果您想停止解析后续提交，请在“Test:”行中添加 -STOP-，例如：

Improve the GD and ZIP extensions

Test: gd, zip, -STOP-

示例请参见https://github.com/mlocati/docker-php-extension-installer/pull/43%E3%80%82

PHP要求和配置选项

关于PHP要求和配置选项的详细信息，请参考相关文档或源码注释。

发布在PECL档案库中的PHP扩展包含一个package.xml（或package2.xml）文件，该文件描述了支持的PHP版本以及可用于编译它的选项。当我们添加对新PHP扩展的支持，以及当PHP扩展的新版本发布时，我们必须检查这些约束条件。

这是一项相当繁琐的任务，因此我开发了一个可让您轻松检查这些约束条件的项目：您可以在 https://mlocati.github.io/pecl-info 找到它（您可以在https://github.com/mlocati/pecl-info%E6%89%BE%E5%88%B0%E5%85%B6%E6%BA%90%E4%BB%A3%E7%A0%81%EF%BC%89%E3%80%82

面向维护者

请参见 https://github.com/mlocati/docker-php-extension-installer/blob/master/MAINTAINERS.md 文件。

您真的想表达感谢吗？

您可以请我喝一杯https://github.com/***/mlocati%E6%88%96%E4%B8%80%E6%AC%A1%E6%80%A7%E5%92%96%E5%95%A1 :wink: