phpcs-docker 镜像文档

镜像概述

phpcs-docker是Docker化的PHP CodeSniffer（phpcs）工具镜像，将PHP代码风格检查工具封装为容器，消除了本地环境依赖，可在任何支持Docker的环境中快速运行。PHP CodeSniffer是PHP社区广泛使用的代码质量工具，用于检测代码风格违规并验证是否符合指定编码标准。

核心功能和特性

• 编码标准支持：内置支持PSR系列规范（PSR-1、PSR-2、PSR-12、PSR-19）及其他主流框架编码标准（如Symfony、Zend、PEAR等）。
• 自定义规则：允许通过挂载外部规则集文件（.ruleset.xml）定义团队自定义编码规范。
• 零环境依赖：Docker容器化设计，无需在主机安装PHP或phpcs，直接运行即可使用。
• 轻量便捷：基于***PHP镜像构建，体积小巧，启动快速。
• 灵活输出：支持多种报告格式（如文本、XML、JSON），便于集成到CI/CD工具或代码质量平台。

使用场景和适用范围

• 本地开发环境：开发者在提交代码前本地检查代码风格，提前发现违规。
• CI/CD流程集成：在自动化构建流程中添加代码风格检查步骤，拒绝不符合规范的代码合并。
• 团队协作：统一团队代码风格标准，减少代码评审中的风格争议。
• 开源项目维护：确保贡献代码符合项目编码规范，降低维护成本。

使用方法和配置说明

基本使用命令

通过docker run命令运行容器，挂载需检查的PHP代码目录，并指定phpcs参数：

# 检查当前目录下的PHP文件（默认使用PSR2标准）
docker run --rm -v $(pwd):/app rosterfy/phpcs phpcs /app

# 指定编码标准（如PSR12）
docker run --rm -v $(pwd):/app rosterfy/phpcs phpcs --standard=PSR12 /app/src

# 检查特定文件
docker run --rm -v $(pwd):/app rosterfy/phpcs phpcs /app/src/Example.php

# 输出XML格式报告（便于CI工具解析）
docker run --rm -v $(pwd):/app rosterfy/phpcs phpcs --standard=PSR12 --report=xml /app > report.xml

自定义规则集

若需使用自定义规则集，将规则文件（如custom-ruleset.xml）挂载到容器内，并通过--standard参数指定路径：

# 使用自定义规则集检查代码
docker run --rm -v $(pwd):/app rosterfy/phpcs phpcs --standard=/app/custom-ruleset.xml /app/src

CI/CD集成示例（GitHub Actions）

在.github/workflows/phpcs.yml中添加以下配置，实现提交时自动检查代码风格：

name: PHP Code Style Check
on: [push, pull_request]

jobs:
  phpcs:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      
      - name: Run phpcs
        run: docker run --rm -v $(pwd):/app rosterfy/phpcs phpcs --standard=PSR12 /app/src

注意事项

• 文件权限：挂载主机目录时，容器内用户可能需要读取权限，建议确保挂载目录权限允许读取（可通过-u $(id -u):$(id -g)指定用户ID）。
• 规则更新：如需使用最新编码标准，可通过docker pull rosterfy/phpcs拉取最新镜像。
• 扩展支持：若代码依赖特定PHP扩展，可能需要基于此镜像构建包含扩展的自定义镜像。