你是否也曾遇到这样的困境：在一个庞大而复杂的 PrestaShop 项目中，随着时间的推移和多位开发者的协作，代码风格开始变得五花八门？有些新方法有类型提示，有些没有；有些类声明了严格类型，有些则没有。这不仅让代码难以阅读和维护，更可能隐藏潜在的类型错误，最终导致运行时的问题。手动审查每一行新代码以确保其符合最新规范，无疑是一项繁重且效率低下的任务。
我们的痛点：代码质量与规范的“失控”
在现代 PHP 开发中，类型提示、返回类型声明和严格类型模式已经成为提升代码质量和可读性的基石。它们帮助我们编写更健壮、更易于理解和重构的代码。然而，在 PrestaShop 这样历史悠久且庞大的项目中，强制所有新代码都遵循这些最佳实践并非易事。
- 缺乏统一标准： 团队成员对“新代码”的定义和规范的理解可能不一致。
- 人工审查的局限： 靠人工去检查每个新方法是否都有类型提示、每个新类是否都声明了严格类型，既耗时又容易出错。
- 技术债务的累积： 随着不规范代码的增多，项目将陷入技术债务的泥沼，未来维护成本越来越高。
面对这些挑战，我们迫切需要一个自动化工具来帮助我们强制执行这些规范。标准的 PHPStan 固然强大，但它主要侧重于发现潜在错误和类型不匹配，而对于“所有新方法都必须有返回类型”这类更偏向于代码规范的规则，它就显得力不从心了。
立即学习“PHP免费学习笔记（深入）”；
救星登场：prestashop/phpstan-prestashop
幸运的是，PrestaShop 官方为我们提供了一个完美的解决方案——prestashop/phpstan-prestashop。这是一个专门为 PrestaShop 项目设计的 PHPStan 扩展，它内置了一系列自定义规则，旨在帮助开发者在 PrestaShop 项目中强制执行现代 PHP 规范和最佳实践。
这个扩展的核心在于它引入了以下关键规则：
-
ClassConstantsMustHaveVisibilityRule：确保类常量都具有可见性修饰符（public,protected,private），提升代码的明确性。 -
UseStrictTypesForNewClassesRule：强制新创建的类文件必须声明declare(strict_types=1);，拥抱严格类型模式。 -
UseTypeHintForNewMethodsRule：要求新方法的所有参数都必须有类型提示，增加代码的健壮性。 -
UseTypedReturnForNewMethodsRule：强制新方法必须声明返回类型，使得方法预期结果更加清晰。
这些规则特别强调“新类”和“新方法”，这意味着你可以在不立即修改整个现有代码库的情况下，逐步引入和强制执行这些现代规范，这对于大型项目的渐进式改进至关重要。
集成与配置：让规范自动化
将 prestashop/phpstan-prestashop 引入你的项目非常简单，只需通过 Composer 进行安装，并配置你的 PHPStan：
-
安装 Composer 依赖： 由于这是一个开发工具，我们将其作为开发依赖安装：
composer require --dev prestashop/phpstan-prestashop
-
配置 PHPStan： 在你的
phpstan.neon或phpstan.neon.dist配置文件中，引入prestashop/phpstan-prestashop的扩展配置：includes: - vendor/prestashop/phpstan-prestashop/extension.neon这样，PHPStan 在运行时就会加载并应用这些自定义规则。
-
为特定规则配置排除项（可选但推荐）：
UseStrictTypesForNewClassesRule、UseTypedReturnForNewMethodsRule和UseTypeHintForNewMethodsRule这些规则非常强大，但考虑到 PrestaShop 项目的复杂性和历史包袱，你可能需要为某些遗留代码或特定情况配置排除项。这个扩展提供了灵活的配置机制，允许你指定一个文件来加载需要被排除的类或方法列表。例如，为
UseStrictTypesForNewClassesRule配置一个排除文件：services: strictTypesForNewClassesRuleConfigurationFileLoader: class: PHPStanForPrestaShop\PHPConfigurationLoader\PHPConfigurationFileLoader arguments: - .github/workflows/phpstan/exclude-class-list.php # 你的排除文件路径这个
exclude-class-list.php文件应该返回一个字符串数组，包含你希望豁免严格类型检查的类名。类似地，你可以为UseTypedReturnForNewMethodsRule和UseTypeHintForNewMethodsRule配置排除方法列表。这种灵活性使得在现有项目中逐步引入这些严格规范成为可能，而不会造成巨大的重构负担。
实际应用效果与优势
引入 prestashop/phpstan-prestashop 后，你的 PrestaShop 项目将迎来质的飞跃：
- 代码质量显著提升： 强制性的类型提示和返回类型让代码更加清晰、可预测，减少了运行时错误的可能性。
- 团队协作更高效： 所有开发者都遵循一套自动化的规范，减少了代码审查中的争论和返工，提高了开发效率。
- 降低技术债务： 新增代码从一开始就符合高标准，有效遏制了技术债务的增长。
- 项目可维护性增强： 统一的代码风格和清晰的类型契约使得代码更易于理解、调试和未来的功能扩展。
- 平滑过渡到现代 PHP： 允许你逐步在现有项目中引入和强制执行现代 PHP 最佳实践，而不是进行一次性的大规模重构。
总结
prestashop/phpstan-prestashop 不仅仅是一个 PHPStan 扩展，它是 PrestaShop 开发者提升代码质量、统一团队规范、降低维护成本的强大武器。通过自动化地执行严格的编码标准，它帮助我们编写出更健壮、更易读、更具未来感的 PrestaShop 代码。如果你正在为 PrestaShop 项目的代码质量问题而烦恼，那么现在就是时候将这个强大的工具集成到你的开发流程中了！
