PHP静态分析工具镜像文档

镜像概述和主要用途

本Docker镜像（jakzal/phpqa）是一个集成了多种PHP静态分析与代码质量工具的环境，旨在为PHP项目提供便捷、一致的代码质量检查解决方案。通过Docker容器化技术，用户无需在本地或服务器环境中手动安装和配置各类工具，即可快速进行代码静态分析、代码风格检查、漏洞检测等质量保障工作。该镜像广泛适用于本地开发、CI/CD流程及多项目统一质量标准场景。

核心功能和特性

集成工具集

包含多种主流PHP代码质量与静态分析工具，主要包括：

• 静态类型分析：PHPStan、Psalm
• 代码风格检查：PHP_CodeSniffer (PHPCS)、PHP-CS-Fixer
• 代码复杂度与质量检测：PHPMD (PHP Mess Detector)、PDepend
• 安全漏洞扫描：PHP Security Checker
• 单元测试工具：PHPUnit（部分版本包含）
• 其他辅助工具：Composer、phpcpd（代码重复检测）、phploc（代码统计）等。

核心特性

• 多PHP版本支持：通过镜像标签（如8.3、8.2、8.1）提供不同PHP版本环境，适配项目需求。
• 环境隔离：工具依赖与项目环境完全隔离，避免本地环境污染或版本冲突。
• 即开即用：无需手动安装工具依赖，拉取镜像后可直接运行分析命令。
• CI/CD友好：轻量级设计，支持快速集成到GitHub Actions、GitLab CI、Jenkins等自动化流程。
• 工具版本管理：镜像定期更新，确保工具版本同步至最新稳定版，减少手动维护成本。

使用场景和适用范围

本地开发环境

• 开发过程中快速执行代码风格检查（如php-cs-fixer fix）或静态类型分析（如phpstan analyze），提前发现问题。
• 多项目并行开发时，统一工具版本，避免因本地工具版本差异导致的分析结果不一致。

CI/CD自动化流程

• 在代码提交或合并前，通过CI/CD管道自动运行静态分析工具（如PHPStan、Psalm），阻断质量不达标代码进入主分支。
• 结合工具输出结果生成质量报告，辅助团队监控代码质量趋势。

多项目统一质量标准

• 企业或团队内部统一代码质量工具链，通过镜像固化工具版本和配置，确保所有项目遵循一致的分析规则。

快速验证场景

• 临时检查第三方项目或开源代码的质量，无需在本地搭建完整分析环境。

使用方法和配置说明

前提条件

• 已安装Docker Engine（20.10+推荐），支持Linux、macOS、Windows（WSL2或Docker Desktop）。
• 本地项目代码目录可被Docker容器访问（需通过-v参数挂载）。

基本使用（Docker Run）

通过docker run命令直接运行容器，挂载项目目录并执行目标工具。基本语法：

docker run --rm -v $(pwd):/app jakzal/phpqa:<tag> <tool> [arguments]

参数说明

• --rm：容器退出后自动删除，避免残留临时容器。
• -v $(pwd):/app：将当前目录（项目根目录）挂载到容器内的/app目录（工具默认工作目录）。
• <tag>：指定PHP版本标签（如8.3、8.2，默认标签为最新稳定PHP版本）。
• <tool>：目标工具名称（如phpstan、psalm、phpcs等）。
• [arguments]：工具运行参数（如分析目录、配置文件路径等）。

常用工具示例

1. PHPStan静态类型分析

分析项目src目录，使用本地phpstan.neon配置：

docker run --rm -v $(pwd):/app jakzal/phpqa:8.3 phpstan analyze src --configuration=phpstan.neon

2. PHP-CS-Fixer代码风格修复

修复当前目录下所有PHP文件的代码风格，使用本地.php-cs-fixer.php配置：

docker run --rm -v $(pwd):/app jakzal/phpqa:8.3 php-cs-fixer fix --config=.php-cs-fixer.php

3. PHPMD代码复杂度检测

分析src目录，输出XML格式报告：

docker run --rm -v $(pwd):/app jakzal/phpqa:8.3 phpmd src xml cleancode,codesize,controversial,design,naming,unusedcode

Docker Compose配置

通过docker-compose.yml定义服务，简化多工具组合使用或频繁调用场景：

version: '3.8'

services:
  phpqa:
    image: jakzal/phpqa:8.3
    volumes:
      - ./:/app  # 挂载项目目录
      - ./phpstan.neon:/app/phpstan.neon  # 挂载工具配置文件（可选）
      - ./vendor:/app/vendor  # 挂载Composer依赖（加速分析，可选）
    working_dir: /app  # 容器工作目录
    # 可添加环境变量（如工具缓存目录）
    environment:
      - PHPQA_CACHE_DIR=/app/.phpqa-cache  # 工具缓存路径（需本地创建目录）

使用时通过docker-compose run执行工具：

docker-compose run --rm phpqa psalm --show-info=true

环境变量说明

镜像支持部分环境变量自定义工具行为（具体以镜像最新版本为准）：

工具配置文件使用

大部分工具依赖项目内的配置文件（如phpstan.neon、.php-cs-fixer.php、psalm.xml），需确保配置文件通过-v挂载到容器内的/app目录（即项目根目录）。例如：

# 挂载本地phpstan.neon到容器内，使PHPStan使用自定义规则
docker run --rm -v $(pwd):/app -v $(pwd)/phpstan.neon:/app/phpstan.neon jakzal/phpqa:8.3 phpstan analyze

注意事项

1. 权限问题：容器内默认使用root用户运行工具，可能导致生成的缓存文件/修复后的文件权限为root。本地开发时可通过-u $(id -u):$(id -g)参数指定当前用户ID，避免权限冲突：

   docker run --rm -u $(id -u):$(id -g) -v $(pwd):/app jakzal/phpqa:8.3 php-cs-fixer fix
   

2. 工具版本：镜像标签仅区分PHP版本，工具版本随镜像更新而升级。如需固定工具版本，建议使用特定镜像SHA（如jakzal/phpqa@sha256:...）。
3. 网络访问：部分工具（如PHP Security Checker）需要联网检查漏洞数据库，确保容器网络通畅。
4. Composer依赖：静态分析工具（如PHPStan）通常依赖项目vendor目录中的类定义，建议挂载本地vendor目录（或在容器内运行composer install）以确保分析准确性。

相关链接

• 项目源码：[***]
• Docker Hub镜像：[***]
• 支持的工具列表：参见GitHub项目文档中的工具清单