PHPStan 错误标识符解析:`assert.deprecatedEnum` —— `@phpstan-assert` 引用已废弃枚举的检测与修复

原创2026-09-21 12:52:481,650 阅读
文章标签:开发工具代码质量静态分析

PHPStan 错误标识符解析:assert.deprecatedEnum —— @phpstan-assert 引用已废弃枚举的检测与修复

导读

assert.deprecatedEnum 是 PHPStan 在启用 phpstan-deprecation-rules 文档为骨架,结合当前仓库中的错误标识符注册表与网页渲染模板,完整讲解该错误的触发场景、底层规则来源、修复方式与忽略方法,帮助你在大规模重构废弃枚举时保持类型断言与迁移计划的一致性。

错误标识符概览

assert.deprecatedEnum 是一个**可忽略(ignorable)**的错误标识符,其元数据定义在仓库的 assert.deprecatedEnum.md 文件头部:

属性 值
title assert.deprecatedEnum
shortDescription Assertion in @phpstan-assert references a deprecated enum.
ignorable true

ignorable: true 意味着该错误既可以在代码行内通过 // @phpstan-ignore 注释临时屏蔽,也可以在配置文件的 ignoreErrors 参数中按标识符整体忽略(详见下文"如何忽略"小节)。该标识符属于 assert.* 错误族,与 assert.deprecatedClass.md、assert.deprecatedInterface.md、assert.deprecatedTrait.md 构成一组语义对称的兄弟错误。

触发场景:@phpstan-assert 指向被标记废弃的枚举

原文档给出的触发示例完整如下:一个枚举 OldStatus 被 @deprecated 注释标记,同时某个方法通过 @phpstan-assert 标签断言参数 $value 的类型就是该废弃枚举。此时 PHPStan 会报告 assert.deprecatedEnum。

<?php declare(strict_types = 1);

/** @deprecated Use NewStatus instead */
enum OldStatus: string
{
    case Active = 'active';
}

class Foo
{
    /**
     * @phpstan-assert OldStatus $value
     */
    public function assertStatus(mixed $value): void
    {
        // ...
    }
}

值得留意的是,@phpstan-assert 是一种隐式类型断言标签:它不会在运行时改变任何行为(方法的实际实现可能只是 // ... 占位),但会告诉 PHPStan 的静态分析引擎——当调用 assertStatus($value) 通过后,$value 的类型应被收窄为 OldStatus。换句话说,断言标签直接影响后续代码的类型推断结果,因此断言中引用的类型一旦废弃,整个下游的类型收窄链条都会建立在一个即将被移除的类型之上,这正是该规则要拦截的问题。

为什么会报告:底层规则与注册来源

原文档明确指出:该规则由 phpstan-deprecation-rules 包提供。结合当前仓库的 website/src/errorsIdentifiers.json(第 2002–2008 行)可以进一步确认实现归属:

"assert.deprecatedEnum": {
    "PHPStan\\Rules\\Deprecations\\RestrictedDeprecatedClassNameUsageExtension": {
        "phpstan/phpstan-deprecation-rules": [
            "https://github.com/phpstan/phpstan-deprecation-rules/blob/2.0.x/src/Rules/Deprecations/RestrictedDeprecatedClassNameUsageExtension.php#L62"
        ]
    }
}

从该注册信息可以推断两层事实:

  1. 规则类归属:报告该错误的类是 PHPStan\Rules\Deprecations\RestrictedDeprecatedClassNameUsageExtension,它通过"受限的废弃类名使用扩展"机制,专门拦截在特定上下文中使用已被 @deprecated 标记的类名/类型名。
  2. 声明来源:该规则不属于 PHPStan 核心分析器,而是来自独立的 phpstan/phpstan-deprecation-rules 扩展包,因此默认不会启用——只有在项目 composer.json 中额外 require 该扩展(或通过 phpstan/extension-installer 自动注册)后,才会开始报告此类错误。

判定逻辑本身是清晰可复现的:只要 @phpstan-assert 标签中引用的枚举在其 PHPDoc 中带有 @deprecated 标记,即视为"废弃类型被用于断言标注"。文档中还强调,这类引用的语义是——该枚举已计划移除或替换,任何使用它的位置(包括断言类型注解)都应迁移到推荐的替代类型。由于同一规则类同时负责 class / enum / interface / trait 四种符号的检测,assert.deprecatedEnum 与 assert.deprecatedClass、assert.deprecatedInterface、assert.deprecatedTrait 共享同一套实现逻辑,区别仅在于被引用符号的类别,这一推断与 website/src/errorsIdentifiers.json 中四个标识符均指向同一规则类的事实完全吻合。

如何修复:替换为推荐的替代枚举

原文档给出的修复方案非常直接:把 @phpstan-assert 标签中的废弃枚举替换为推荐的替代枚举即可:

 <?php declare(strict_types = 1);

 class Foo
 {
     /**
-     * @phpstan-assert OldStatus $value
+     * @phpstan-assert NewStatus $value
      */
     public function assertStatus(mixed $value): void
     {
         // ...
     }
 }

修复时需要注意一个细节:迁移通常不能只改这一处注释。由于 @phpstan-assert 会驱动调用点的类型收窄,你还需要检查所有调用 assertStatus() 并依赖其收窄效果的位置,确认传入值的实际类型已切换到 NewStatus(以及上游对 OldStatus 的引用是否已全部清理)。否则即使 PHPStan 不再报告 assert.deprecatedEnum,断言建立在新类型上的下游逻辑仍可能因实际传值不匹配而产生新的类型错误。此外,如果代码中同时存在 @param OldStatus、@return OldStatus 等其他 PHPDoc 引用,它们会分别触发 deprecated 错误族中对应的其他标识符,建议在迁移时一并排查。

如何忽略:行内注释与配置文件两种方式

由于 assert.deprecatedEnum 的元数据中 ignorable 为 true,在确认误报或暂缓迁移时,可以按 errorIdentifierDetail.njk 模板(第 70–105 行)描述的两种标准方式进行忽略。

方式一:行内忽略注释,在产生错误的那一行代码上方(或同行)添加 // @phpstan-ignore assert.deprecatedEnum:

// @phpstan-ignore assert.deprecatedEnum
assertStatus($value); // 本行若触发 assert.deprecatedEnum,将被忽略

方式二:配置级整体忽略,在 PHPStan 配置文件(如 phpstan.neon)的 ignoreErrors 参数中仅使用 identifier 键,即可忽略项目中所有同类错误:

parameters:
	ignoreErrors:
		-
			identifier: assert.deprecatedEnum

两种方式的语义差异需要注意:行内注释只作用于单条语句,适合"此处确为误报"的定点豁免;配置级忽略则覆盖整个分析范围,适合"废弃枚举的迁移尚未开始、需要分阶段清理"的场景,但也会同时掩盖同标识符下真实存在的问题,建议配合 baseline 或限期清理策略使用。与之相对,若标识符元数据为 ignorable: false,则代表会引发运行时崩溃或致命错误的根本性问题,不允许以任何方式忽略——assert.deprecatedEnum 不属于这一类。

关联错误族速查

assert.deprecatedEnum 不是孤立存在的错误,它属于"废弃类型被断言引用"的错误族,仓库 website/errors 目录下还收录了语义完全对称的兄弟标识符:

标识符 触发条件 文档
assert.deprecatedClass @phpstan-assert 引用废弃类 assert.deprecatedClass.md
assert.deprecatedEnum @phpstan-assert 引用废弃枚举 assert.deprecatedEnum.md
assert.deprecatedInterface @phpstan-assert 引用废弃接口 assert.deprecatedInterface.md
assert.deprecatedTrait @phpstan-assert 引用废弃 trait assert.deprecatedTrait.md

这四个标识符由同一个规则类 RestrictedDeprecatedClassNameUsageExtension 驱动(见 website/src/errorsIdentifiers.json 第 1995–2022 行),因此它们的行为、修复思路与忽略方式完全一致:找到断言标签中废弃的类型名,替换为 @deprecated 注释中推荐的替代类型即可。在 PHP 8.1+ 引入枚举后,废弃枚举的断言引用成为一类高频出现的迁移告警,理解 assert.deprecatedEnum 的处理方式,即可举一反三地应对整个 assert.deprecated* 家族。

小结

  • assert.deprecatedEnum 由 phpstan-deprecation-rules 扩展包提供(需额外安装才生效),底层规则类为 PHPStan\Rules\Deprecations\RestrictedDeprecatedClassNameUsageExtension,并非 PHPStan 核心默认规则。
  • 触发条件单一明确:@phpstan-assert 标签中引用的枚举被 @deprecated 标记。
  • 修复方式:将断言标签中的废弃枚举替换为推荐的替代枚举,并同步检查调用点的类型收窄与其余 PHPDoc 引用。
  • 该错误 ignorable: true,既可用 // @phpstan-ignore assert.deprecatedEnum 行内豁免,也可在配置 ignoreErrors 中按 identifier 整体忽略,适合分阶段推进废弃类型迁移的场景。
登录后查看全文
phpstan