Docker镜像：PHP Dev(el)

镜像概述与主要用途

本项目提供基于wayofdev/docker-php-base构建的PHP开发环境Docker镜像，旨在为本地开发提供便捷、功能丰富的解决方案，可作为Laravel Sail的替代方案使用。

核心功能与特性

• 基础镜像继承：完整继承wayofdev/docker-php-base镜像的所有功能与扩展
• PHP版本支持：兼容PHP 8.1、8.2、8.3及8.4版本
• 多类型镜像：提供CLI、FPM及Supervisord三种运行模式变体
• 调试工具集成：预装并配置Xdebug调试扩展
• 开发工具套件：包含git、bash、unzip、nano等常用工具
• 依赖管理：预装Composer用于PHP包管理
• 时间测试支持：集成libfaketime用于时间相关代码测试
• 服务就绪检查：包含wait4x工具验证服务可用性
• 多架构支持：同时构建AMD64（x86_64）和ARM64（AArch64）架构镜像

额外PHP扩展

在基础镜像提供的扩展之上，本开发镜像额外包含以下扩展：

包含的开发工具

使用场景与适用范围

本镜像适用于以下开发场景：

• PHP项目的本地开发与调试环境搭建
• 需要Xdebug进行断点调试的PHP开发工作
• 依赖Composer管理依赖的PHP项目
• 跨架构开发团队（如x86_64工作站与ARM64开发板）
• Laravel项目寻求Sail替代方案的开发环境

使用方法与配置说明

拉取镜像

使用docker pull命令拉取指定版本镜像：

docker pull wayofdev/php-dev:8.3-fpm-alpine-latest

标签格式说明：{PHP版本}-{类型}-{系统}-{版本}，例如8.3-fpm-alpine-latest表示：

• PHP 8.3版本
• FPM运行模式
• Alpine Linux系统
• 最新稳定版本

可用镜像变体

PHP版本

• 8.1
• 8.2
• 8.3
• 8.4

运行类型

• cli：仅包含PHP命令行解释器
• fpm：包含PHP-FPM进程管理器
• supervisord：集成Supervisord进程管理工具

变体示例

# PHP 8.1 CLI版本
docker pull wayofdev/php-dev:8.1-cli-alpine-latest

# PHP 8.2 FPM版本
docker pull wayofdev/php-dev:8.2-fpm-alpine-latest

# PHP 8.3 Supervisord版本
docker pull wayofdev/php-dev:8.3-supervisord-alpine-latest

Docker Compose配置示例

以下是Laravel项目的完整Docker Compose配置示例，包含PHP应用服务与Nginx Web服务：

services:
  app:
    image: wayofdev/php-dev:8.3-fpm-alpine-latest
    container_name: ${COMPOSE_PROJECT_NAME}-app
    restart: on-failure  # 失败时自动重启
    networks:
      - default
      - shared
    depends_on:
      - database  # 依赖数据库服务启动
    links:
      - database
    volumes:
      - ./.github/assets:/assets:rw,cached  # 静态资源目录
      - ./app:/app:rw,cached  # 应用代码目录（rw表示读写，cached优化性能）
      - ./.env:/app/.env  # 环境变量文件挂载
      - ~/.composer:/.composer  # Composer缓存目录（加速依赖安装）
      - ~/.ssh:/home/www-data/.ssh:ro  # SSH密钥目录（只读权限）
    environment:
      FAKETIME: '+2h'  # 设置伪造时间（如提前2小时），用于测试时间逻辑
      XDEBUG_MODE: '${XDEBUG_MODE:-off}'  # Xdebug模式，默认关闭
      PHIVE_HOME: /app/.phive  # Phive工具的家目录
    dns:
      - 8.8.8.8  # 配置Google DNS
    extra_hosts:
      - 'host.docker.internal:host-gateway'  # 允许容器访问宿主机服务

  web:
    image: wayofdev/nginx:k8s-alpine-latest  # 配套Nginx镜像
    container_name: ${COMPOSE_PROJECT_NAME}-web
    restart: on-failure
    networks:
      - default
      - shared
    depends_on:
      - app  # 依赖PHP服务启动
    links:
      - app
    volumes:
      - ./app:/app:rw,cached  # 共享应用代码目录
      - ./.env:/app/.env  # 共享环境变量文件
    labels:
      # Traefik反向代理配置
      - traefik.enable=true
      - traefik.http.routers.api-${COMPOSE_PROJECT_NAME}-secure.rule=Host(`api.${COMPOSE_PROJECT_NAME}.docker`)
      - traefik.http.routers.api-${COMPOSE_PROJECT_NAME}-secure.entrypoints=websecure
      - traefik.http.routers.api-${COMPOSE_PROJECT_NAME}-secure.tls=true
      - traefik.http.services.api-${COMPOSE_PROJECT_NAME}-secure.load***.server.port=8880
      - traefik.docker.network=network.${SHARED_SERVICES_NAMESPACE}

环境变量配置

高级使用指南

开发环境要求（镜像维护者）

如需构建或修改本镜像，需满足以下依赖：

• Docker Engine (20.10+)
• GNU Make
• Ansible (2.14+)
• goss (0.3.20+) 和 dgoss (用于测试)

环境搭建

git clone ***:wayofdev/docker-php-dev.git && \
cd docker-php-dev

生成Dockerfile

使用Ansible从Jinja2模板生成目标Dockerfile：

make generate

构建镜像

• 构建默认镜像（由IMAGE_TEMPLATE变量指定，默认8.3-fpm-alpine）：

  make build
  

• 构建指定镜像：

  make build IMAGE_TEMPLATE="8.3-fpm-alpine"
  

• 构建所有变体：

  # PHP 8.1系列
  make build IMAGE_TEMPLATE="8.1-cli-alpine"
  make build IMAGE_TEMPLATE="8.1-fpm-alpine"
  make build IMAGE_TEMPLATE="8.1-supervisord-alpine"
  
  # PHP 8.2系列
  make build IMAGE_TEMPLATE="8.2-cli-alpine"
  make build IMAGE_TEMPLATE="8.2-fpm-alpine"
  make build IMAGE_TEMPLATE="8.2-supervisord-alpine"
  
  # PHP 8.3系列
  make build IMAGE_TEMPLATE="8.3-cli-alpine"
  make build IMAGE_TEMPLATE="8.3-fpm-alpine"
  make build IMAGE_TEMPLATE="8.3-supervisord-alpine"
  
  # PHP 8.4系列
  make build IMAGE_TEMPLATE="8.4-cli-alpine"
  make build IMAGE_TEMPLATE="8.4-fpm-alpine"
  make build IMAGE_TEMPLATE="8.4-supervisord-alpine"
  

测试

运行测试

使用make test命令执行镜像验证测试：

• 测试默认镜像：

  make test
  

• 测试指定镜像：

  make test IMAGE_TEMPLATE="8.3-fpm-alpine"
  

测试配置

测试用例通过goss.yaml文件定义（针对每个镜像变体生成），包含以下验证项：

• 文件系统检查（存在性、权限、所有者）
• 进程状态验证（如php-fpm、supervisord）
• 网络端口监听状态
• 软件包安装验证
• PHP扩展加载状态
• 命令输出一致性检查

测试流程

1. 构建目标镜像（如未构建）
2. 启动临时容器并执行初始化
3. 运行goss测试套件验证容器状态
4. 输出测试结果并清理临时资源

安全策略

本项目遵循安全策略，包含漏洞披露流程和响应机制。

贡献指南

欢迎参与贡献！可通过以下方式参与：

• 提交功能建议
• 报告问题
• 改进文档
• 提交代码

许可证

本项目基于MIT许可证开源，详情参见许可证文件。