企业官网建设流程全解析

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）错误标识符，其官方一句话描述为：

Tag@phpstan-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 self<DeprecatedClass> */ 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 self<DeprecatedClass> + * @phpstan-self-out self<NewClass> */ - public function filterDeprecated(): void + public function filterNew(): void { // ... } }

如果NewClass与Collection之间满足泛型约束（例如通过@template定义类型参数），也可以写成self<NewClass>的完整泛型形式。需要注意，替换后的类型必须是声明该方法的类的子类型，否则会触发另一个同族标识符selfOut.type（参见 website/errors/selfOut.type.md：@phpstan-self-out指定的类型必须是声明类的一个子类型）。

深入理解@phpstan-self-out标签

要彻底避免这类错误，需要先理解@phpstan-self-out的作用。根据 PHPStan 官方 PHPDoc 基础文档 website/src/writing-php-code/phpdocs-basics.md：

PHPDoc tags@phpstan-self-outor@phpstan-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 self<TValue|TItemValue> */ public function add($item): void { // ... } } /** @param Collection<int> $c */ function foo(Collection $c, string $s): void { $c->add($s); \PHPStan\dumpType($c); // Collection<int|string> }

在这个例子里，向Collection<int>添加一个string后，PHPStan 借助@phpstan-self-out self<TValue|TItemValue>把$c的类型更新为Collection<int|string>——这正是“方法调用后类型收窄”能力的价值所在。而@deprecated则用于标记声明为废弃（见同一文档的 Deprecations 小节），安装 phpstan-deprecation-rules 扩展后，所有对废弃符号的使用都会被报告。

当这两种能力在同一处相遇——即@phpstan-self-out的泛型参数里填入废弃类——就会产生selfOut.deprecatedClass这条错误。它本质上是在告诉你：这条类型收窄声明依赖了一个即将消失的符号。

相关错误标识符

selfOut.deprecatedClass属于selfOut.*标识符家族，理解这一家族有助于你诊断同一类问题。以下是仓库 website/errors 中存在的同族文档：

其中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