PHP Docker镜像文档

📦 简化的PHP Docker镜像，支持轻松定制和扩展设置。

镜像概述和主要用途

本PHP Docker镜像基于官方PHP Docker镜像构建，支持PHP 5.6至8.5（beta）版本，提供CLI、ZTS、FPM、FPM/Apache2、FPM/Nginx、RoadRunner和FrankenPHP等多种变体，同时提供Debian和Alpine两种基础版本。

核心优势包括：

• 通过环境变量轻松调整PHP和PHP-FPM配置，无需重建镜像
• 预安装最新版Composer及Apache2、Nginx、RoadRunner、FrankenPHP等Web服务器
• 相比官方基础镜像显著减小体积，优化下载速度和资源占用
• 支持自定义应用目录、用户权限、钩子脚本、定时任务等高级功能

适用场景：快速搭建PHP开发环境、生产环境部署、多版本PHP项目兼容、需要灵活配置PHP参数的场景。

核心功能和特性

多版本与变体支持

• 覆盖PHP 5.6至8.5（beta）版本
• 提供多种运行模式：cli、zts、fpm、fpm-nginx、fpm-apache、roadrunner（PHP ≥8.0）、frankenphp（PHP ≥8.2，beta）
• 支持Debian和Alpine两种基础镜像，满足不同体积和依赖需求

灵活配置

• 通过PHP_*环境变量直接自定义php.ini和php-fpm.conf参数（如PHP_DISPLAY_ERRORS=1）
• 支持运行时动态调整PHP配置（需设置ALLOW_RUNTIME_PHP_ENVVARS=1）
• 自定义应用目录（APP_PATH）和文档根目录（DOCUMENT_ROOT）

扩展管理

• 预安装常用PHP扩展（apcu、bcmath、gd、redis等）
• 通过phpaddmod命令一键安装额外扩展（如phpaddmod imagick xdebug），自动处理依赖和配置

高级功能

• 钩子机制：支持onboot、first-run、migration等多种钩子脚本，定制容器生命周期行为
• 自动运行脚本：/startup/目录下的脚本会按文件名顺序自动执行
• 定时任务：通过ENABLE_CRONTAB=1启用crontab服务，支持环境变量定义任务
• 邮件发送：集成msmtp，通过环境变量配置SMTP服务器实现邮件发送
• 用户权限定制：通过APP_USER、APP_UID等环境变量自定义容器内用户和组

使用场景和适用范围

详细的使用方法和配置说明

镜像变体与标签

镜像标签格式为shinsenter/php:[PHP版本]-[变体]，支持以下变体：

示例标签：

• shinsenter/php:7.4-cli（PHP 7.4，CLI模式）
• shinsenter/php:8.1-fpm-nginx（PHP 8.1，FPM+Nginx）
• shinsenter/php:8.3-roadrunner（PHP 8.3，RoadRunner）
• shinsenter/php:8.4-frankenphp（PHP 8.4，FrankenPHP）

所有标签可在Docker Hub查看。

快速启动示例

1. CLI模式

# 非交互式运行（查看PHP模块）
docker run --rm shinsenter/php:8.4-cli php -m

# 交互式运行（挂载本地项目）
docker run -it -v ./myproject:/var/www/html shinsenter/php:8.4-cli

2. PHP-FPM模式

docker run -v ./myproject:/var/www/html -p 9000:9000 shinsenter/php:8.4-fpm

3. FPM+Nginx/Apache

# FPM+Nginx（映射80/443端口）
docker run -v ./myproject:/var/www/html -p 80:80 -p 443:443 shinsenter/php:8.4-fpm-nginx

# FPM+Apache
docker run -v ./myproject:/var/www/html -p 80:80 -p 443:443 shinsenter/php:8.4-fpm-apache

4. 使用docker-compose

version: '3'
services:
  web:
    image: shinsenter/php:8.4-fpm-nginx
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./myproject:/var/www/html
    environment:
      PHP_DISPLAY_ERRORS: "1"          # 显示错误信息
      PHP_POST_MAX_SIZE: "100M"        # 最大POST大小
      PHP_UPLOAD_MAX_FILESIZE: "100M"  # 最大上传文件大小
      APP_PATH: "/var/www/html"        # 应用目录（默认）
      DOCUMENT_ROOT: "public"          # 文档根目录（相对于APP_PATH）

自定义PHP配置（环境变量）

通过PHP_*环境变量自定义php.ini或php-fpm.conf参数，命名规则为：PHP_ + 配置项的常量名（原配置项中的点/横杠替换为下划线，大写）。

常用环境变量示例

使用示例

命令行：

docker run \
  -v ./myproject:/var/www/html \
  -e PHP_DISPLAY_ERRORS='1' \
  -e PHP_POST_MAX_SIZE='100M' \
  shinsenter/php:8.4-fpm-nginx

运行时动态调整配置： 默认PHP_*变量仅在容器启动时生效，若需在容器内运行命令时动态调整，需设置ALLOW_RUNTIME_PHP_ENVVARS=1：

docker run -e ALLOW_RUNTIME_PHP_ENVVARS=1 shinsenter/php:8.4-cli
# 容器内执行：PHP_DISPLAY_ERRORS=1 php -i | grep display_errors

应用目录与文档根目录

• 默认应用目录：/var/www/html，可通过APP_PATH环境变量自定义。
• 文档根目录：相对于APP_PATH的子目录（默认空，即APP_PATH本身），可通过DOCUMENT_ROOT自定义。

示例：

# 将应用目录设置为/app，文档根目录为/app/public
docker run \
  -v ./myproject:/app \
  -e APP_PATH=/app \
  -e DOCUMENT_ROOT=public \
  -p 80:80 \
  shinsenter/php:8.4-fpm-nginx

添加PHP扩展

使用phpaddmod命令一键安装PHP扩展，自动处理依赖、编译和配置。该命令是mlocati/docker-php-extension-installer的封装，支持大部分主流扩展。

Dockerfile示例

FROM shinsenter/php:8.4-fpm-nginx

# 安装imagick、swoole、xdebug扩展
RUN phpaddmod imagick swoole xdebug

# 复制项目代码（指定用户权限）
ADD --chown=$APP_USER:$APP_GROUP ./myproject/ /var/www/html/

支持的扩展列表参考：mlocati/docker-php-extension-installer文档

自定义容器用户与组

通过环境变量自定义容器内运行应用的用户和组，避免权限问题。

示例：

# docker-compose.yml
services:
  web:
    image: shinsenter/php:8.4-fpm-nginx
    environment:
      APP_USER: "myapp"    # 自定义用户名
      APP_UID: "5000"      # 自定义UID（与宿主机用户匹配可避免权限问题）

钩子（Hooks）

钩子脚本用于在容器生命周期的特定阶段执行自定义逻辑，支持以下钩子：

使用方法

在APP_PATH目录下创建hooks文件夹，添加与钩子名称同名的可执行脚本（或子目录中的脚本）：

/var/www/html/
└── hooks/
    ├── first-run        # 首次启动执行
    ├── migration        # 迁移脚本
    └── onlive/          # onlive钩子的多个脚本
        ├── 01-webhook
        └── 02-notify

提示：设置DEBUG=1可查看钩子执行日志。

自动运行脚本（Autorun Scripts）

/startup/目录下的shell脚本会在容器启动时按文件名顺序自动执行，用于初始化项目（如数据库迁移、依赖安装等）。

使用示例

Dockerfile中添加脚本：

FROM shinsenter/php:8.4-cli

# 添加自动运行脚本（确保可执行权限）
ADD ./scripts/00-migration /startup/00-migration
RUN chmod +x /startup/00-migration

禁用自动运行： 设置环境变量DISABLE_AUTORUN_SCRIPTS=1。

定时任务（Cron Jobs）

启用crontab服务需设置ENABLE_CRONTAB=1，任务定义可通过以下方式添加：

1. 挂载或复制任务文件到CRONTAB_DIR（默认/etc/crontab.d）
2. 通过CRONTAB_SETTINGS环境变量直接定义（适合docker-compose）

环境变量配置

使用示例

docker-compose.yml：

services:
  web:
    image: shinsenter/php:8.4-fpm-nginx
    environment:
      ENABLE_CRONTAB: "1"
      CRONTAB_TZ: "Asia/Shanghai"
      CRONTAB_SETTINGS: |
        * * * * * echo "每分钟执行" >> /var/log/cron.log
        0 0 * * * php /var/www/html/artisan backup  # 每日凌晨执行备份

自定义Supervisor命令

通过SUPERVISOR_PHP_COMMAND环境变量自定义容器启动命令，替代默认Web服务器或FPM进程。

示例：

# 使用PHP内置Web服务器运行项目
docker run \
  -e SUPERVISOR_PHP_COMMAND='php -S 0.0.0.0:80 index.php' \
  shinsenter/php:8.4

邮件发送配置

镜像使用msmtp替代sendmail，支持通过SMTP发送邮件。若使用PHP mail()函数，需配置以下环境变量：

开发环境示例（使用Mailpit容器作为SMTP服务器）：

version: '3'
services:
  web:
    image: shinsenter/php:8.4-fpm-nginx
    environment:
      SMTP_HOST: mailpit
      SMTP_PORT: 1025
  mailpit:
    image: axllent/mailpit
    ports:
      - "8025:8025"  # Web管理界面

调试模式

设置DEBUG=1启用详细日志输出，便于排查配置或启动问题：

docker run -e DEBUG=1 shinsenter/php:8.4-fpm-nginx

其他系统设置