企业官网建设流程全解析

• 开发工具
• 代码质量
• 静态分析

本文围绕 PHPStan 错误标识符requireExtends.deprecatedTrait展开，讲解其触发条件、底层规则来源以及修复方案。该标识符由phpstan-deprecation-rules扩展提供，用于在@phpstan-require-extendsPHPDoc 标签引用了已被@deprecated标记的 trait 时发出提示。读完本文，你将掌握该标识符的完整语义、它与requireExtends.trait的联动关系，以及如何用类引用替代 trait 引用完成修复。

标识符概述与文档元数据

该错误标识符的官方文档位于 website/errors/requireExtends.deprecatedTrait.md，其 frontmatter 记录了如下元数据：

按照 website/errors/CLAUDE.md 中的标识符前缀参考表，requireExtends前缀对应@phpstan-require-extendsPHPDoc 标签。在 website/src/errorsIdentifiers.json 中（约第 15431 行），该标识符被映射到规则类PHPStan\Rules\Deprecations\RestrictedDeprecatedClassNameUsageExtension，来源扩展为phpstan/phpstan-deprecation-rules。

触发该错误的代码示例

以下最小化示例可以触发requireExtends.deprecatedTrait：

<?php declare(strict_types = 1); /** @deprecated Use NewHelper instead */ trait OldHelper { } /** * @phpstan-require-extends OldHelper */ trait MyTrait { }

这里有两处关键点：

1. OldHelper是一个 trait，并且通过@deprecatedPHPDoc 标记为已弃用；
2. MyTrait（本身也是一个 trait）通过@phpstan-require-extends OldHelper声明了"使用本 trait 的类必须继承OldHelper"的约束。

由于约束目标指向了一个已弃用的 trait，PHPStan 的弃用规则扩展便报告该问题。

为什么会被报告

规则来源：phpstan-deprecation-rules 扩展

该错误不是 PHPStan 核心规则，而是由 phpstan-deprecation-rules 扩展报告。从 website/src/errorsIdentifiers.json 可以确认其规则实现为RestrictedDeprecatedClassNameUsageExtension（对应 phpstan-deprecation-rules 2.0.x 分支 src/Rules/Deprecations/ 目录下的同名类，位于第 62 行附近）。

因此，要实际启用该检测，项目必须额外安装并配置该扩展（通过 Composer 引入phpstan/phpstan-deprecation-rules并在phpstan.neon中包含其规则集），仅安装 PHPStan 本体不会报告此标识符。

语言层面的语义问题

@phpstan-require-extends标签的本意是约束继承关系：当一个接口被实现、或一个 trait 被某个类使用时，使用它的类必须extends标签所声明的父类。而 trait 在 PHP 中是通过use关键字引入的，并不能作为extends的目标（PHP 类只能继承另一个类，不能继承 trait）。

因此，@phpstan-require-extends OldHelper这类写法本身在语义上就是无效的——把 trait 写进了只应放类名的位置。deprecation-rules 扩展在此基础上进一步检查：如果这个（本就不该出现的）trait 引用还指向了一个@deprecated标记的实体，就额外报告弃用问题，因为被弃用的 trait 计划在未来版本中移除，任何围绕它的约束都将随之失效。

关键注意点：实践中该标识符几乎不会被单独报告

原文档特别指出一个重要的工程事实：

触发该标识符的前提是@phpstan-require-extends引用了 trait，但该标签期望的是类。因此 PHPStan 总是会同时报告requireExtends.trait错误，而 deprecation 标识符在实践中并不会被报告。

也就是说，两者之间存在"永远成对出现"的关系：

• requireExtends.trait（见 website/errors/requireExtends.trait.md）：@phpstan-require-extends引用了 trait 而非类，属于核心 PHPStan 立即报告的结构性错误；
• requireExtends.deprecatedTrait：仅在上述结构性错误成立的前提下，进一步检查该 trait 是否被弃用。

由于requireExtends.trait必然先于（或伴随）deprecation 检查被报告，且修复方向一致——把 trait 引用改成类引用——所以从使用者视角看，你实际看到的通常是requireExtends.trait，而requireExtends.deprecatedTrait更多是一个理论路径上的标识符（这也解释了 frontmatter 中unlikely: true的标记）。

如何修复

修复思路很直接：用合适的类引用替换被弃用的 trait 引用。既然@phpstan-require-extends只接受类，就把约束目标换成真正可被继承的类：

/** - * @phpstan-require-extends OldHelper + * @phpstan-require-extends NewBaseClass */ trait MyTrait { }

如果该 trait 的功能确实需要被"使用"（而非"继承"），可参考 website/errors/requireExtends.trait.md 提供的两种替代方案：

方案一：引入一个使用该 trait 的基类，并约束继承这个基类

<?php declare(strict_types = 1); +class BaseWithLogging +{ + use OldHelper; +} + /** - * @phpstan-require-extends OldHelper + * @phpstan-require-extends BaseWithLogging */ trait MyTrait { }

方案二：若原 trait 的职责本质是"能力约定"，将其改为接口并用@phpstan-require-implements约束

@phpstan-require-implements是与之互补的标签，可放在 trait 上方，要求使用该 trait 的类必须实现指定接口（详见 website/src/writing-php-code/phpdocs-basics.md#L646-L674）：

<?php declare(strict_types = 1); -trait OldHelper +interface OldHelper { } /** - * @phpstan-require-extends OldHelper + * @phpstan-require-implements OldHelper */ trait MyTrait { }

如何豁免该错误

由于 frontmatter 标记ignorable: true，该标识符同样支持 PHPStan 标准的 ignore 机制。在phpstan.neon的ignoreErrors中按标识符名豁免即可：

parameters: ignoreErrors: - identifier: requireExtends.deprecatedTrait

不过如前所述，实践中伴随的requireExtends.trait是核心规则错误，且ignorable: true同样适用，真正的修复应当落在把 trait 引用改写成类引用上，豁免只是临时手段。

关联标识符与扩展阅读

该标识符并非孤立存在，它属于requireExtends.*家族，同一命名空间下还包括：

• requireExtends.trait：标签引用 trait 而非类（核心规则，与之成对报告）；
• requireExtends.deprecatedClass：标签引用已弃用的类；
• requireExtends.deprecatedEnum、requireExtends.deprecatedInterface：标签引用已弃用的枚举/接口；
• requireExtends.finalClass、requireExtends.interface 等：约束目标不符合"可被继承的类"的其他情况。

@phpstan-require-extends与@phpstan-require-implements的完整用法（含"何时使用、约束如何传导到使用类"的示例）可参考 website/src/writing-php-code/phpdocs-basics.md#L615-L674；全部requireExtends.*标识符及其规则类映射可在 website/src/errorsIdentifiers.json 中检索。

小结

requireExtends.deprecatedTrait是一个由 phpstan-deprecation-rules 扩展提供的弃用检测标识符，它的存在价值更多在于完善错误标识符体系——实际触发时必然伴随requireExtends.trait，因为@phpstan-require-extends只接受类而不接受 trait。修复时只需记住一条原则：把 trait 引用替换为可继承的类引用（或改用@phpstan-require-implements约束接口），同时消除弃用引用与结构错误两个问题。

• 开发工具
• 代码质量
• 静态分析