PHPStan 错误标识符 selfOut.deprecatedClass：当 `@phpstan-self-out` 引用了已废弃类

PHPStan 错误标识符 selfOut.deprecatedClass当phpstan-self-out引用了已废弃类【免费下载链接】phpstanPHP Static Analysis Tool - discover bugs in your code without running it!项目地址: https://gitcode.com/gh_mirrors/ph/phpstan本篇技术指南围绕 PHPStan 官方错误标识符selfOut.deprecatedClass展开讲解phpstan-self-outPHPDoc 标签引用deprecated废弃类时为何会被报告以及如何通过替换为新类型完成修复。读完本文你将掌握该标识符的触发条件、底层规则来源以及phpstan-self-out标签在类型收窄中的正确用法并能在自己的项目中熟练规避此类错误。错误标识符selfOut.deprecatedClass是什么selfOut.deprecatedClass是 PHPStan 定义的一个可忽略ignorable: true错误标识符其官方一句话描述为Tagphpstan-self-outreferences a deprecated class.即phpstan-self-outPHPDoc 标签中引用了一个已被标记为deprecated的类。该标识符的官方文档位于 website/errors/selfOut.deprecatedClass.md属于 website/errors 目录下按标识符组织的错误文档体系生成与格式规范参见 website/errors/CLAUDE.md。从标识符命名可以拆解出两层含义前缀selfOut根据 website/errors/CLAUDE.md 中的前缀参考表selfOut对应phpstan-self-outPHPDoc 标签后缀deprecatedClass表示该标签中引用的符号是废弃类deprecatedclass。同类标识符还包括selfOut.deprecatedEnum废弃枚举、selfOut.deprecatedInterface废弃接口、selfOut.deprecatedTrait废弃 Trait等它们共享同一套检测规则只是针对不同种类的符号。触发该错误的代码示例以下最小化示例会触发selfOut.deprecatedClass取自官方文档原文?php declare(strict_types 1); /** deprecated Use NewClass instead */ class DeprecatedClass {} class Collection { /** * phpstan-self-out selfDeprecatedClass */ public function filterDeprecated(): void { // ... } }这里DeprecatedClass通过deprecated注解被标记为废弃而Collection::filterDeprecated()方法的phpstan-self-out标签却把它写进了类型参数中于是 PHPStan 报出selfOut.deprecatedClass。为什么会报告该错误官方文档的解释是phpstan-self-out标签用于在方法调用后收窄$this的类型。当这个标签引用了已被deprecated标记的类时代码就产生了对一个“计划被移除或替换”的符号的依赖。这通常意味着你正在把新的调用链建立在即将消亡的类型之上未来废弃类被删除后phpstan-self-out中的类型引用会失效进而破坏类型推断该标签是类型层面的“使用点”usage location它和new DeprecatedClass()、instanceof DeprecatedClass一样都会构成对废弃符号的引用。从仓库证据看该错误并非 PHPStan 核心规则phpstan-src直接产出而是由官方扩展包 phpstan-deprecation-rules 中selfOut.deprecatedClass被映射到规则类selfOut.deprecatedClass: { 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 ] } }也就是说检测逻辑由RestrictedDeprecatedClassNameUsageExtension这一规则类实现位于 phpstan-deprecation-rules 扩展包的src/Rules/Deprecations/目录它负责收集各类“废弃类名使用位置”phpstan-self-out中的类引用正是其中之一。这也解释了为什么错误文档末尾会注明“This error is reported by the phpstan-deprecation-rules extension”如果你没有安装该扩展PHPStan 不会报告这条错误。如何修复修复思路非常直接把phpstan-self-out标签中的废弃类替换为其非废弃的替代类同时建议同步更新方法名避免方法语义与旧类型继续绑定?php declare(strict_types 1); class Collection { /** - * phpstan-self-out selfDeprecatedClass * phpstan-self-out selfNewClass */ - public function filterDeprecated(): void public function filterNew(): void { // ... } }如果NewClass与Collection之间满足泛型约束例如通过template定义类型参数也可以写成selfNewClass的完整泛型形式。需要注意替换后的类型必须是声明该方法的类的子类型否则会触发另一个同族标识符selfOut.type参见 website/errors/selfOut.type.mdphpstan-self-out指定的类型必须是声明类的一个子类型。深入理解phpstan-self-out标签要彻底避免这类错误需要先理解phpstan-self-out的作用。根据 PHPStan 官方 PHPDoc 基础文档 website/src/writing-php-code/phpdocs-basics.mdPHPDoc tagsphpstan-self-outorphpstan-this-outcan be used to change the type of the current object after calling a method on it. This is useful for generic mutable objects.即phpstan-self-out别名phpstan-this-out可以在方法调用之后改变当前对象$this的类型非常适合描述可变泛型对象的类型演化。官方给出的典型用法如下/** * template TValue */ class Collection { // ... /** * template TItemValue * param TItemValue $item * phpstan-self-out selfTValue|TItemValue */ public function add($item): void { // ... } } /** param Collectionint $c */ function foo(Collection $c, string $s): void { $c-add($s); \PHPStan\dumpType($c); // Collectionint|string }在这个例子里向Collectionint添加一个string后PHPStan 借助phpstan-self-out selfTValue|TItemValue把$c的类型更新为Collectionint|string——这正是“方法调用后类型收窄”能力的价值所在。而deprecated则用于标记声明为废弃见同一文档的 Deprecations 小节安装 phpstan-deprecation-rules 扩展后所有对废弃符号的使用都会被报告。当这两种能力在同一处相遇——即phpstan-self-out的泛型参数里填入废弃类——就会产生selfOut.deprecatedClass这条错误。它本质上是在告诉你这条类型收窄声明依赖了一个即将消失的符号。相关错误标识符selfOut.deprecatedClass属于selfOut.*标识符家族理解这一家族有助于你诊断同一类问题。以下是仓库 website/errors 中存在的同族文档标识符触发场景文档路径selfOut.deprecatedClass引用废弃类website/errors/selfOut.deprecatedClass.mdselfOut.deprecatedEnum引用废弃枚举website/errors/selfOut.deprecatedEnum.mdselfOut.deprecatedInterface引用废弃接口website/errors/selfOut.deprecatedInterface.mdselfOut.deprecatedTrait引用废弃 Traitwebsite/errors/selfOut.deprecatedTrait.mdselfOut.internalClass跨包引用internal类website/errors/selfOut.internalClass.mdselfOut.type类型不是声明类的子类型website/errors/selfOut.type.mdselfOut.unresolvableType类型无法解析website/errors/selfOut.unresolvableType.md其中selfOut.internalClass与本文主题最接近同样是phpstan-self-out引用了受限符号但限制原因是internal内部类不属于包的公开 API可能随时变更或移除且该限制只对跨包使用生效同一包内使用不会报错。该错误能否忽略可以。该标识符在 frontmatter 中声明为ignorable: true与绝大多数错误标识符一致仅-nonIgnorable()或phpstan./phpstanPlayground.前缀的标识符不可忽略见 website/errors/CLAUDE.md。如果你暂时无法替换废弃类可以通过 PHPStan 的ignoreErrors配置按标识符忽略例如parameters: ignoreErrors: - identifier: selfOut.deprecatedClass path: src/Collection.php不过更推荐的做法是尽快迁移到替代类——毕竟忽略只会掩盖依赖关系而phpstan-self-out中失效的类型引用最终会在废弃类被删除时破坏整个类型推断链。小结selfOut.deprecatedClass是 phpstan-deprecation-rules 扩展针对phpstan-self-out标签引用废弃类而报告的标识符。修复的核心动作只有一步将标签中的废弃类替换为其非废弃替代类。在使用phpstan-self-out收窄$this类型时请始终确认其中引用的类型既满足子类型约束也不依赖任何被deprecated或internal标记的符号。相关官方文档与源码依据可直接查阅 website/errors/selfOut.deprecatedClass.md、website/src/writing-php-code/phpdocs-basics.md 与 website/src/errorsIdentifiers.json。【免费下载链接】phpstanPHP Static Analysis Tool - discover bugs in your code without running it!项目地址: https://gitcode.com/gh_mirrors/ph/phpstan创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考