neatous/phpstan

Phpstan Docker镜像文档

镜像概述和主要用途

Phpstan是一款功能强大的PHP静态代码分析工具，能够在不运行代码的情况下检测潜在错误。本Docker镜像封装了Phpstan的完整运行环境，提供开箱即用的PHP代码静态分析能力，适用于各类PHP项目的代码质量保障流程，无需在本地环境安装Phpstan及依赖。

核心功能和特性

核心分析能力

• 静态错误检测：自动识别类型不匹配、未定义变量/方法、无效方法调用、数组索引错误等问题
• 可配置规则级别：支持0-9共10个分析级别（0最宽松，9最严格），默认级别为0
• 类型系统支持：完整支持PHP 7+类型特性（返回类型、参数类型、联合类型、交集类型等）

兼容性与扩展性

• PHP版本支持：兼容PHP 7.1至PHP 8.3
• 框架适配：原生支持Laravel、Symfony、Yii、Zend Framework等主流PHP框架
• 规则扩展：可通过Composer安装第三方规则包（如phpstan/phpstan-deprecation-rules）

环境特性

• 无运行时依赖：分析过程不依赖数据库、缓存等外部服务
• 轻量级设计：基于Alpine或Debian slim基础镜像，镜像体积优化
• 多架构支持：提供amd64、arm64等主流架构镜像

使用场景和适用范围

开发阶段

• 本地开发环境的代码质量实时检查
• IDE集成的自动化分析（通过Docker CLI调用）
• 代码提交前的本地预检

工程化流程

• CI/CD流水线集成（GitHub Actions、GitLab CI、Jenkins等）
• 代码评审环节的自动化错误检测
• 版本发布前的全量代码扫描

项目类型适配

• 新开发项目的代码规范落地
• 遗留系统的错误排查与重构支持
• 开源项目的贡献者代码质量校验

使用方法和配置说明

基本使用

本地项目分析

通过挂载项目目录并指定分析路径执行基础分析：

bash
docker run --rm -v $(pwd):/app phpstan/phpstan analyze /app/src

指定分析级别

bash
docker run --rm -v $(pwd):/app phpstan/phpstan analyze /app/src --level=5

使用自定义配置文件

项目根目录创建phpstan.neon或phpstan.neon.dist配置文件后：

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

高级配置

配置文件示例（phpstan.neon）

neon
parameters:
    level: 5
    paths:
        - src/
        - tests/
    excludePaths:
        - src/legacy/
    checkMissingIterableValueType: true
    reportUnmatchedIgnoredErrors: true
    ignoreErrors:
        - '#Call to an undefined method .*#'

安装扩展规则

通过临时安装扩展并执行分析：

bash
docker run --rm -v $(pwd):/app -v $(pwd)/composer.json:/tmp/composer.json phpstan/phpstan \
    sh -c "composer require --working-dir=/tmp phpstan/phpstan-laravel && \
           phpstan analyze /app/src --configuration=/app/phpstan.neon"

CI/CD集成示例

GitHub Actions配置（.github/workflows/phpstan.yml）

yaml
name: PHP Static Analysis
on: [push, pull_request]

jobs:
    phpstan:
        runs-on: ubuntu-latest
        steps:
            - uses: actions/checkout@v4
            - name: Run Phpstan
              run: |
                docker run --rm -v ${{ github.workspace }}:/app phpstan/phpstan \
                    analyze /app/src --level=5 --no-progress

持久化配置与缓存

为加速分析，可挂载缓存目录：

bash
docker run --rm \
    -v $(pwd):/app \
    -v phpstan-cache:/tmp/phpstan \
    phpstan/phpstan analyze /app/src --level=5

环境变量说明

镜像标签说明

• latest：最新稳定版本，基于最新PHP版本
• 1.10：特定Phpstan版本（如1.10.x系列）
• 1.10-php8.1：特定Phpstan版本+PHP版本组合
• nightly：开发版，包含最新特性（不建议生产环境使用）