docker-ci-php 镜像文档

镜像概述和主要用途

docker-ci-php 是一个专为 PHP 项目持续集成（CI）任务设计的工具镜像。该镜像集成了 PHP 开发与测试过程中常用的工具链，旨在简化 CI/CD 流程中的环境配置，帮助开发者快速在 CI 环境中执行代码检查、自动化测试、静态分析等任务，提升 PHP 项目的持续集成效率。

核心功能和特性

• 多版本 PHP 支持：内置多种稳定 PHP 版本（如 PHP 7.4、8.0、8.1、8.2 等），可通过配置灵活切换。
• 工具链集成：预装 PHP 开发常用工具，包括但不限于：
  • Composer（依赖管理）
  • PHPUnit（单元测试框架）
  • PHPStan（静态分析工具）
  • PHPCS/PHPCBF（代码规范检查与修复）
  • Psalm（静态类型检查）
  • Xdebug（调试扩展，支持代码覆盖率生成）。
• 轻量级基础：基于 Alpine 或 Debian Slim 基础镜像，平衡工具完整性与镜像体积。
• CI 兼容性：适配主流 CI 平台（如 GitLab CI、GitHub Actions、Jenkins 等），支持非交互式环境运行。
• 扩展灵活性：可通过环境变量或配置文件启用/禁用特定 PHP 扩展（如 redis、mysqli、gd 等）。

使用场景和适用范围

• PHP 项目自动化测试：在 CI 流程中执行单元测试（PHPUnit）、集成测试，生成测试报告。
• 代码质量管控：通过 PHPStan、Psalm 进行静态分析，使用 PHPCS 检查代码规范一致性。
• 依赖管理与构建：通过 Composer 安装项目依赖，构建可部署的应用包。
• CI 流程标准化：统一团队 CI 环境配置，避免因本地环境差异导致的“在我电脑上能运行”问题。

使用方法和配置说明

基本使用（docker run 命令）

通过 docker run 命令可直接在本地或 CI 环境中运行镜像，执行具体 CI 任务。

示例 1：执行 PHPUnit 测试

bash
docker run --rm -v $(pwd):/app -w /app florenttorregrosa-docker/images/docker-ci-php:latest \
  phpunit tests/ --coverage-text

• -v $(pwd):/app：将本地项目目录挂载到容器内 /app 路径。
• -w /app：设置工作目录为 /app（项目根目录）。
• phpunit tests/ --coverage-text：执行 PHPUnit 测试并输出文本格式的代码覆盖率报告。

示例 2：运行 PHPStan 静态分析

bash
docker run --rm -v $(pwd):/app -w /app florenttorregrosa-docker/images/docker-ci-php:latest \
  phpstan analyze src/ --level=8

Docker Compose 配置示例

通过 docker-compose.yml 定义服务，适用于本地模拟 CI 环境或多服务联动场景：

yaml
version: '3.8'
services:
  ci-php:
    image: florenttorregrosa-docker/images/docker-ci-php:latest
    volumes:
      - ./:/app
    working_dir: /app
    environment:
      - PHP_VERSION=8.2  # 指定 PHP 版本（需镜像支持）
      - ENABLE_XDEBUG=1  # 启用 Xdebug 扩展（用于调试或覆盖率生成）
    command: phpunit tests/  # 默认执行的 CI 任务

启动命令：

bash
docker-compose run ci-php

CI 环境集成示例

GitLab CI 集成（.gitlab-ci.yml）

在 GitLab CI 中使用该镜像执行测试和代码检查：

yaml
stages:
  - test
  - analyze

unit-test:
  stage: test
  image: florenttorregrosa-docker/images/docker-ci-php:latest
  script:
    - composer install --no-interaction --prefer-dist
    - phpunit tests/ --coverage-cobertura=coverage.xml

static-analysis:
  stage: analyze
  image: florenttorregrosa-docker/images/docker-ci-php:latest
  script:
    - composer install --no-interaction --prefer-dist
    - phpstan analyze src/ --level=8

环境变量说明

注意事项

1. 版本选择：建议通过镜像标签指定具体 PHP 版本（如 florenttorregrosa-docker/images/docker-ci-php:8.2），避免因 latest 标签更新导致环境变化。
2. 依赖缓存：在 CI 环境中，建议将 Composer 缓存目录（如 /root/.composer）挂载为持久卷，减少依赖安装时间。
3. 扩展兼容性：部分 PHP 扩展可能需要系统库依赖（如 gd 依赖 libpng），若启用扩展后运行异常，可检查镜像是否包含对应系统库。
4. 镜像更新：定期更新镜像以获取工具链安全补丁和功能更新，可通过 CI 配置中的 renovate 等工具自动检测版本更新。

注：本文档基于“PHP CI 任务工具箱”的通用场景推断，具体功能与配置请以 原镜像仓库 ***文档为准。