PHP静态分析：Psalm与PHPStan代码质量‌

PHP静态分析：Psalm与PHPStan，为你的代码加上“双保险”

大家好，作为一名在PHP世界里摸爬滚打了多年的开发者，我深知代码质量的重要性。早期，我们依赖大量的单元测试和人工Code Review来保证代码健壮性，但这往往耗时耗力，且难以覆盖所有边界情况。直到我遇到了静态分析工具——它们就像代码的“X光机”，在不运行程序的情况下，就能扫描出潜在的错误、类型不匹配和逻辑漏洞。今天，我想和大家深入聊聊PHP生态中两位最出色的“代码医生”：Psalm 和 PHPStan。我将分享我的实战经验，包括如何选择、如何配置，以及如何让它们协同工作，为你的项目加上“双保险”。

为什么需要静态分析？一个真实的“踩坑”故事

让我从一个亲身经历开始。曾经在一个线上项目中，有一个看似简单的函数，它接收一个用户ID（整数）和一个配置数组。由于历史原因，这个用户ID有时会以字符串形式从老系统传过来。我们当时没有严格类型声明，结果在一个边缘场景下，字符串ID与数组键的松散比较导致了配置读取失败，引发了线上告警。如果当时引入了静态分析工具，这类类型不匹配的问题在代码提交前就会被高亮标出，根本不会进入生产环境。这就是静态分析的核心价值：防患于未然。

初识两大神器：Psalm vs PHPStan

PHPStan 是静态分析领域的先驱，它专注于类型检查，通过推断和验证代码中的类型来发现问题。它的规则严格，能快速揪出大量低级错误，非常适合作为项目代码质量的门神。

Psalm 则后来居上，它不仅做类型检查，还深入到了代码逻辑层面，能发现更多诸如“可能存在的空值引用”、“未使用的变量”、“死代码”等问题。它尤其擅长处理PHP更现代化的特性，如泛型（Generics）。

我的建议是：对于新项目或追求极高代码质量的项目，可以两者都引入；对于存量老项目，可以先从PHPStan开始，逐步修复类型问题，再引入Psalm进行更深度的清洁。

实战第一步：安装与基础配置

假设我们使用Composer管理项目。安装过程非常简单。

安装PHPStan：

composer require --dev phpstan/phpstan

安装Psalm：

composer require --dev vimeo/psalm

安装完成后，我们需要为它们创建配置文件。

初始化PHPStan配置： 在项目根目录运行以下命令生成基础配置文件 phpstan.neon。

vendor/bin/phpstan init

你会看到一个交互式向导。对于大多数项目，我推荐从 level 5 或 6 开始。生成的配置文件大致如下，你可以根据需要调整扫描的目录和级别：

# phpstan.neon
parameters:
    level: 5
    paths:
        - src
    excludePaths:
        - tests/*

初始化Psalm配置： 同样，在根目录运行以下命令生成 psalm.xml。

vendor/bin/psalm --init

Psalm会尝试分析你的代码并推荐一个错误级别（errorLevel，从1到8，1最严格）。对于老项目，可以从3或4开始。配置文件会更详细：

运行与分析：第一次“体检报告”

配置好后，让我们运行第一次扫描。

运行PHPStan：

vendor/bin/phpstan analyse

运行Psalm：

vendor/bin/psalm

不出意外，对于存量代码，你会看到一大堆错误和警告。别慌！这是正常现象。静态分析工具正在帮你把技术债清晰地列出来。我的策略是：不要试图一次性修复所有问题。可以先用 --generate-baseline 功能生成一个基线文件，将现有问题“白名单化”，确保新代码不再引入同类问题。

为Psalm生成基线：

vendor/bin/psalm --set-baseline=psalm-baseline.xml

这之后，再次运行Psalm，它将只报告新增的问题。PHPStan也有类似功能，通过 --generate-baseline 参数生成 phpstan-baseline.neon 文件。

进阶技巧：让工具更懂你的代码

静态分析工具很强大，但有时它们会误报，或者无法理解你特定的设计模式。这时就需要我们进行调教。

1. 使用注解（PHPDoc）提供类型信息： 这是提升分析精度的最关键手段。特别是对于魔术方法、动态属性或复杂返回。

/**
 * @param array $idList
 * @return User[]
 */
public function loadUsers(array $idList): array {
    // ... 实现
}

2. 忽略特定错误： 在极少数确实需要绕过检查的地方，可以使用注释忽略。

PHPStan忽略下一行：

// @phpstan-ignore-next-line
$result = $ambiguous->method();

Psalm忽略下一行：

/** @psalm-suppress PossiblyNullReference */
$length = $maybeNullObject->getLength();

3. 编写自定义规则或扩展： 两者都支持强大的扩展机制。例如，你可以为PHPStan编写规则来检查项目特定的编码规范，或者为Psalm编写插件来支持你内部使用的某个库。

集成到开发流程：让检查自动化

手动运行检查很容易被遗忘。最佳实践是将其集成到你的CI/CD流水线（如GitHub Actions, GitLab CI）和Git提交钩子（pre-commit hook）中。

一个简单的GitHub Actions工作流示例（.github/workflows/static-analysis.yml）：

name: Static Analysis

on: [push, pull_request]

jobs:
  phpstan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: shivammathur/setup-php@v2
        with:
          php-version: '8.1'
      - run: composer install --no-progress --prefer-dist
      - run: vendor/bin/phpstan analyse --memory-limit=1G

  psalm:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: shivammathur/setup-php@v2
        with:
          php-version: '8.1'
      - run: composer install --no-progress --prefer-dist
      - run: vendor/bin/psalm --output-format=github

这样，每次提交或发起Pull Request时，都会自动进行代码质量检查，确保主分支的代码始终健康。

我的选择与总结

经过多个项目的实践，我现在通常的做法是：同时使用两者。在CI流程中，先运行PHPStan进行快速、严格的基础类型检查，再运行Psalm进行更深度的逻辑和代码风格分析。它们覆盖的维度有重叠，但更多是互补。

引入静态分析的初期可能会有阵痛，需要花时间修复历史问题并调整编码习惯。但从长远看，它带来的收益是巨大的：更少的运行时Bug、更好的代码可读性、更强的重构信心，以及团队整体代码素养的提升。这就像为你的代码库聘请了两位不知疲倦、火眼金睛的代码审计员，何乐而不为呢？

希望这篇结合我个人经验的分享，能帮助你顺利启航PHP静态分析之旅，让你的代码质量迈上一个新的台阶。如果在使用中遇到具体问题，欢迎深入探讨！