PHPStan使用技巧：提升代码质量指南

PHPStan作为PHP代码质量的“守门员”和“教练”，通过静态分析在代码运行前发现潜在错误，提升代码可靠性和可维护性。本文提供了一份PHPStan使用全攻略，从安装配置到等级选择，助你充分发挥其威力。针对新项目，建议从等级7或8开始；遗留项目则应从低等级起步，利用`--generate-baseline`生成基线文件逐步提升。文章还对比了PHP_CodeSniffer、PHPMD、Psalm、Rector等其他静态分析工具，并阐述了如何在大型遗留项目中平滑引入PHPStan，避免一次性重构的压力，最终实现代码质量的飞跃。

PHPStan的等级从0到9，级别越高分析越严格，等级0-3检查基础语法错误，4-6加强类型检查，7-9进行深度类型推断和逻辑验证；选择等级时，新项目建议从7或8开始，遗留项目应从低等级起步并结合--generate-baseline生成基线文件逐步提升，CI/CD中可对新代码使用更高等级以确保质量。

PHPStan是提升PHP代码质量和可靠性的强大工具，它通过静态分析，在代码实际运行之前就能发现潜在的错误、类型不匹配或不规范之处，从而显著减少运行时错误，并提高代码的可维护性。在我看来，它不仅是一个工具，更是一种代码质量的“守门员”和“教练”。

PHPStan的使用并不复杂，但其深度和广度值得我们投入时间去探索。首先，你需要通过Composer将其安装到你的项目中：

composer require --dev phpstan/phpstan

安装完成后，最基本的用法就是运行：

./vendor/bin/phpstan analyse src

这里src是你希望分析的代码目录。但仅仅这样，你可能只会得到一些最基础的警告。要真正发挥PHPStan的威力，我们需要一个配置文件，通常命名为phpstan.neon或phpstan.neon.dist。

一个典型的phpstan.neon文件可能包含以下内容：

parameters:
    level: 7 # 分析等级，从0到9，9最严格
    paths:
        - src
        - tests
    excludePaths:
        analyse:
            - %rootDir%/src/LegacyBundle/* # 排除特定目录不进行分析
    ignoreErrors:
        - '#Call to an undefined method App\\Entity\\User::getName().#' # 忽略特定错误，不推荐长期使用
    phpVersion: 80100 # 指定PHP版本，帮助PHPStan理解语法和函数
    bootstrapFiles:
        - %rootDir%/phpstan-bootstrap.php # 在分析前加载的文件，例如用于定义一些全局函数或常量
    scanDirectories:
        - %rootDir%/vendor/my-package/src # 扫描额外目录以发现类

通过配置level参数，你可以控制PHPStan的严格程度。我通常建议从一个中等偏上的等级（比如7或8）开始，特别是对于新项目。对于遗留项目，可能需要从较低等级开始，逐步提升。

在我个人的实践中，PHPStan不仅仅是发现bug的工具，它还强制我更好地思考类型、空值安全和潜在的边缘情况。一开始，它可能会让你感到沮丧，因为它会揪出你代码里那些你以为“没问题”的地方，但正是这种“吹毛求疵”，才真正让代码变得健壮。它就像一位严厉的老师，虽然过程有点痛苦，但结果是你的代码质量会有一个质的飞跃。

PHPStan的“等级”是如何影响分析结果的？我该如何选择合适的等级？

PHPStan的“等级”（level）是其核心功能之一，它决定了工具分析的严格程度和深度，从0（最宽松）到9（最严格）。理解这些等级至关重要，因为它直接影响到你将发现的错误类型和数量。

• 等级0-3： 主要关注最基础的语法错误、未定义的变量或方法调用、以及一些明显的类型不匹配。这些等级通常能捕捉到一些低级的、几乎可以立刻导致运行时错误的问题。对于刚引入PHPStan的项目，或者需要快速扫描以确保基本功能正常运行的场景，这些等级是很好的起点。
• 等级4-6： 开始引入更严格的类型检查，例如对方法参数和返回值的类型推断和验证。它会发现更多潜在的空指针解引用问题、不兼容的类型赋值等。在我看来，等级5或6是大多数成熟项目的“甜点”，它能在提供足够严格的检查的同时，不至于产生过多的误报，对开发效率的影响也相对可控。
• 等级7-9： 这是PHPStan的“硬核”模式。它会进行极其严格的类型推断，包括泛型、复杂的类型组合、以及更深层次的逻辑错误。例如，它可能会警告你某个分支永远不会被执行（死代码），或者某个变量在特定路径下可能永远不会被初始化。等级9是最高级别，它会尝试发现所有可能的类型不一致和逻辑缺陷，甚至包括一些你可能从未想过的情况。启用这些高级别，往往意味着你需要对代码进行大量的类型提示和重构，以满足其严格的要求。

至于如何选择合适的等级，我的建议是：

• 新项目： 尽可能从高等级开始，比如等级7或8。因为从项目初期就养成良好的类型习惯，远比后期去修复大量类型问题要容易得多。一开始的“痛苦”是值得的。
• 遗留项目： 不要一下子跳到最高等级。那样你会淹没在成千上万的错误报告中。我的经验是，先从等级0或1开始，修复最明显的问题。然后，使用--generate-baseline功能生成一个基线文件，忽略当前所有错误。接下来，逐步提升等级（比如每次提升1-2级），并重点关注新引入代码的错误。这是一个迭代的过程，需要耐心。
• 持续集成/交付 (CI/CD)： 在CI/CD流程中，可以对所有代码使用一个相对稳定的等级（例如5或6），同时，对新提交或修改的代码，可以尝试使用更高的等级进行检查，确保新代码的质量。

选择等级没有绝对的对错，关键在于找到一个平衡点：既能有效提升代码质量，又不会过度阻碍开发流程。

除了PHPStan，还有哪些值得关注的PHP静态分析工具？它们与PHPStan有何不同？

PHP生态系统中有不少优秀的静态分析工具，它们各有侧重，可以与PHPStan形成互补，共同构建一个强大的代码质量保障体系。

1. PHP_CodeSniffer (PHPCS):

   • 特点： 主要用于检查代码是否符合特定的编码标准（如PSR-12、Drupal、WordPress等）。它关注的是代码的格式、命名规范、文件结构等“风格”问题。
   • 与PHPStan的区别： PHPCS关注的是代码“怎么写”，是风格和规范层面的检查；而PHPStan关注的是代码“写得对不对”，是逻辑和类型层面的检查。PHPCS不会告诉你变量是否未定义，但会告诉你缩进是不是四个空格。我个人在项目中总是同时使用PHPCS和PHPStan，它们是维护代码风格和逻辑正确性的左右手。

2. PHPMD (PHP Mess Detector):

   • 特点： 专注于发现代码中的“坏味道”（code smells），例如过长的方法、过多的参数、复杂的类、未使用的参数或变量等。它基于一些预定义的规则集来评估代码的复杂度、可维护性和潜在的重构点。
   • 与PHPStan的区别： PHPMD更侧重于代码的“结构性健康”和“可维护性”，它会告诉你代码可能变得难以理解或修改。PHPStan则更侧重于“功能性正确性”和“类型安全”。一个代码可能通过了PHPStan的检查（逻辑正确），但却在PHPMD那里因为过于复杂而被标记。

3. Psalm:

   • 特点： 另一个非常强大的PHP静态类型检查器，与PHPStan在功能上有很多重叠，甚至在某些方面（如对泛型和复杂类型的支持）可能更进一步。它也支持增量分析和基线功能。
   • 与PHPStan的区别： Psalm和PHPStan是直接的竞争者，它们都致力于提供严格的类型检查。选择哪一个通常取决于个人偏好、社区支持、以及特定项目对某些高级特性（如更深度的泛型支持）的需求。有些团队甚至会尝试同时运行两者，以获得最全面的覆盖。我个人倾向于PHPStan，因为它在社区普及度和文档方面做得很好，但Psalm无疑也是一个非常值得尝试的替代品。

4. Rector:

   • 特点： Rector并非传统的静态分析工具，它是一个“自动化重构”工具。它读取你的代码，应用预定义的规则（例如将旧的PHPUnit断言转换为新的、升级PHP版本语法、重构命名空间等），然后直接修改你的代码。
   • 与PHPStan的区别： PHPStan是“诊断”工具，它告诉你代码哪里有问题，但不会修改代码。Rector是“治疗”工具，它直接“治愈”你的代码。它们经常一起使用：先用PHPStan发现问题，然后用Rector自动化修复一部分问题，或者用Rector进行大规模的PHP版本升级和代码现代化。

这些工具各有侧重，但目标都是提升PHP代码的质量。在我看来，PHPStan是基石，它保障了代码的“正确性”；PHPCS保障了代码的“一致性”；PHPMD则帮助我们发现代码的“亚健康状态”；而Rector则是代码“进化”的加速器。一个健康的PHP项目，往往是这些工具协同作用的结果。

如何在大型遗留项目中逐步引入PHPStan，避免一次性重构的巨大压力？

将PHPStan引入一个大型遗留项目，听起来就像要把一艘正在航行的巨轮彻底改造，挑战重重。但实际上，通过一些策略和PHPStan自身的功能，我们可以做到平滑过渡，避免一次性重构带来的巨大压力和风险。

1. 从最低等级开始，并生成基线 (Baseline): 这是最关键的第一步。不要一开始就尝试用高等级去分析整个遗留项目，那会产生天文数字的错误报告，让你望而却步。

   • 首先，配置phpstan.neon，将level设置为0或1，只捕获最基本的错误。
   • 然后，运行./vendor/bin/phpstan analyse src --generate-baseline phpstan-baseline.neon。 这个命令会分析你的代码，并将当前所有发现的错误写入phpstan-baseline.neon文件。这意味着，PHPStan在未来的分析中会“忽略”这些已经存在的错误。这样，你的CI/CD系统就不会因为历史问题而失败，你也可以专注于新代码的质量。
   • 将phpstan-baseline.neon文件添加到你的版本控制中。

2. 聚焦新代码和修改过的代码： 有了基线，你就可以安心地在CI/CD流程中运行PHPStan了。现在，PHPStan只会报告基线文件中没有的新错误。这意味着：

   • 当开发者提交新的代码时，PHPStan会严格检查这些新代码。
   • 当开发者修改现有代码时，PHPStan会检查修改部分是否引入了新的问题。 这种增量检查的策略，让你能够逐步提升新代码的质量，而无需立即处理所有的历史遗留问题。

3. 逐步提升等级和清理基线：

   • 提升等级： 每隔一段时间（比如几个月，或者完成一个大的模块重构后），尝试将phpstan.neon中的level提升1-2级。再次运行PHPStan，你会发现新的错误类型。
   • 清理基线： 当你提升等级后，新的错误又会冒出来。这时，你可以选择再次生成基线，将新的错误也加入基线。但我更推荐另一种做法：主动修复基线中的错误。可以设定一个目标，比如每周修复基线中的5个错误，或者在每次重构某个模块时，将该模块相关的基线错误一并修复。PHPStan的--remove-unreachable-baselines参数可以帮助你清理掉那些已经被修复的基线错误。 这是一个持续改进的过程。就像打扫一个杂乱的房间，你不可能一次性整理好所有东西。你可以先清理最显眼的地方，然后每天整理一个小角落，慢慢地，整个房间就会变得整洁。

4. 利用ignoreErrors，但要谨慎： 在phpstan.neon中，你可以使用ignoreErrors参数来忽略特定的错误。这在处理一些你暂时无法修改，或者认为PHPStan误报的情况时非常有用。

   parameters:
       ignoreErrors:
           - '#Call to an undefined method App\\Service\\LegacyService::oldMethod().#'

   然而，我个人建议谨慎使用这个功能。它就像一个“遮羞布”，虽然能暂时隐藏问题，但问题本身依然存在。如果必须使用，请务必添加详细的注释，说明为什么要忽略这个错误，以及未来计划如何解决它。

5. 集成到开发工作流：

   • IDE集成： 许多IDE（如PhpStorm）都提供了PHPStan插件，可以在你编写代码时实时给出反馈，这比等到CI/CD阶段才发现问题要高效得多。
   • Git Hooks： 可以设置pre-commit或pre-push Git Hooks，在代码提交前自动运行PHPStan，确保只有通过检查的代码才能进入版本库。

在大型遗留项目中引入PHPStan，考验的不仅仅是技术能力，更是耐心和策略。它不是一个“一劳永逸”的解决方案，而是一个持续改进的旅程。但相信我，一旦你迈出了这一步，并坚持下去，你的代码质量、可维护性以及团队的开发效率都将得到显著提升。

以上就是本文的全部内容了，是否有顺利帮助你解决问题？若是能给你带来学习上的帮助，请大家多多支持golang学习网！更多关于文章的相关知识，也可关注golang学习网公众号。