PHPStan 错误标识 requireExtends.deprecatedClass 全解析：当 @phpstan-require-extends 引用了已废弃的类

开发工具代码质量静态分析【免费下载链接】phpstanPHP Static Analysis Tool - discover bugs in your code without running it!项目地址https://gitcode.com/gh_mirrors/ph/phpstan点击查看免费下载requireExtends.deprecatedClass是 PHPStan 在phpstan-require-extendsPHPDoc 标签引用了已被deprecated标记的类时所报告的错误标识。本文以 官网错误文档 为主体结合本仓库的标识注册表与文档生成规范讲解该错误的触发条件、底层规则来源、典型修复方式以及与之同族的系列标识帮助你在实际项目中快速定位并消除这类废弃依赖隐患。错误标识是什么该错误的官方 shortDescription 为phpstan-require-extendsreferences a deprecated class.即phpstan-require-extends标签引用了一个已废弃的类。在错误标识文档体系详见 website/errors/CLAUDE.md中requireExtends前缀对应的正是phpstan-require-extends这个 PHPStan 专有 PHPDoc 标签。根据 errorsIdentifiers.json 中的注册信息requireExtends.deprecatedClass条目该标识由phpstan/phpstan-deprecation-rules扩展包中的PHPStan\Rules\Deprecations\RestrictedDeprecatedClassNameUsageExtension规则报告并声明ignorable: true——也就是说它可以通过 ignoreErrors 配置或 baseline 机制被显式忽略。值得注意的一点与requireExtends.class、requireExtends.finalClass等由 PHPStan 核心phpstan-src中的RequireExtendsCheck报告的标识不同requireExtends.deprecatedClass属于扩展包规则只有当你安装了phpstan-deprecation-rules扩展并启用 deprecation 相关规则时才会被触发。这也是它报告的是废弃类引用这一语义的原因。触发该错误的代码示例原文档给出的最小复现代码如下?php declare(strict_types 1); /** deprecated Use NewBase instead */ class OldBase { } /** * phpstan-require-extends OldBase */ interface HasOldBase { }这里的核心结构包含两个要素OldBase类通过deprecatedPHPDoc 标签被标记为废弃并给出了迁移提示Use NewBase instead。HasOldBase接口通过phpstan-require-extends OldBase声明了一个约束任何实现该接口的类都必须继承自OldBase。当 deprecation-rules 扫描到这一约束时就会报告requireExtends.deprecatedClass。从 PHP 语言语义上讲deprecated标记意味着该符号计划在未来的版本中被移除而phpstan-require-extends却把它固化为一种强制继承约束——这会让所有基于该接口扩展的类在未来不得不面对一个即将消失的基类属于典型的把废弃符号写进公共契约的坏味道。为什么会被报告原文档对这一点的解释可以概括为phpstan-require-extends标签引用的类已被标记为废弃。在require-extends约束中使用废弃类意味着任何实现该接口、或使用该 trait 的类都会被强制要求继承一个废弃类——这在工程上应当避免。从规则实现角度可以进一步印证依据 errorsIdentifiers.json 的注册条目该规则属于RestrictedDeprecatedClassNameUsageExtension它是 deprecation-rules 扩展中负责检测受约束的废弃类名使用的扩展点RestrictedDeprecatedClassNameUsageExtension在phpstan/phpstan-deprecation-rules2.0.x 分支的src/Rules/Deprecations/RestrictedDeprecatedClassNameUsageExtension.php中定义同一扩展点还负责requireExtends.deprecatedEnum、requireExtends.deprecatedInterface、requireExtends.deprecatedTrait等同族标识的检测。也就是说这一系列requireExtends.deprecated*标识共享同一套检测逻辑差异仅在于被引用的符号是类、枚举、接口还是 trait。这一点与本仓库中 requireExtends.deprecatedEnum.md、requireExtends.deprecatedInterface.md、requireExtends.deprecatedTrait.md 等文档一一对应。从工程语义看报告此错误的价值在于phpstan-require-extends是一种强约束它把基类选择写死在接口/trait 的契约中。若该基类已废弃则新增实现方会被迫继承废弃类无法直接切换到替代类未来移除废弃类时会牵动所有实现方造成连锁重构代码库中会持续出现新代码依赖旧契约的累积。PHPStan 在静态分析阶段提前发现这一点正是为了避免废弃依赖在运行时扩散。如何修复修复的核心思路是将phpstan-require-extends指向的非废弃替代类替换进去。原文档给出的修复方式是更新标签引用?php declare(strict_types 1); /** - * phpstan-require-extends OldBase * phpstan-require-extends NewBase */ interface HasOldBase { }修复前的完整操作清单在实际项目中建议按以下顺序处理确认替代类确实存在且 API 兼容NewBase应是OldBase的非废弃替代且提供HasOldBase实现方所依赖的全部公共 API同步更新实现方如果仓库中已有实现HasOldBase的类它们继承的基类也需要从OldBase迁移到NewBase或将基类替换为NewBase的子类重新运行 PHPStan确认requireExtends.deprecatedClass不再出现同时检查是否引入了其他错误如class.extendsDeprecatedClass、属性/方法签名不兼容等。其他相关修复路径如果phpstan-require-extends的目标实际上不该是某个具体类还可以参考同族的 requireExtends.class 文档中的思路——把约束迁移到 trait 或接口上。不过对于废弃类这一特定标识最直接的修复永远是替换为替代类。关于 PHPDoc 标签的书写基础可参阅 PHPDocs Basics有效的 PHPDoc 必须以/**开头/*或//形式不会被解析PHPStan 正是基于T_DOC_COMMENT词法标记解析这些标签的。phpstan-require-extends属于 PHPStan 专有标签与phpstan-require-implements参见 requireImplements.deprecatedClass.md同为约束型标签前者限定必须继承自后者限定必须实现某接口。同族标识速查phpstan-require-extends标签相关的错误标识集中注册在 errorsIdentifiers.json 的requireExtends.*命名空间下本仓库website/errors/目录中对应的文档包括标识触发场景requireExtends.class标签被用在类上仅 trait/interface 上合法requireExtends.deprecatedClass标签引用了废弃的类本文主题requireExtends.deprecatedEnum标签引用了废弃的枚举requireExtends.deprecatedInterface标签引用了废弃的接口requireExtends.deprecatedTrait标签引用了废弃的 traitrequireExtends.duplicate标签重复声明requireExtends.enum标签目标为枚举需要的是类requireExtends.finalClass标签引用了 final 类无法被继承requireExtends.interface标签目标为接口需要的是类requireExtends.internalClass等标签引用了internal的符号requireExtends.nonObject标签目标不是对象类型requireExtends.onClass/onEnum/onInterface/onTrait标签被用在错误的声明位置上requireExtends.trait标签目标为 trait需要的是类与之对应的phpstan-require-implements标签也有一套平行的requireImplements.*标识。当你在报告中看到requireExtends.*前缀时可以立即确认问题出在phpstan-require-extends标签的声明或引用上而不是类继承关系本身。如何忽略该错误基线化由于该标识声明了ignorable: true如果你确实需要在迁移完成前保留现状可以通过 PHPStan 的 ignoreErrors 配置将其加入基线。但需要注意该标识由phpstan-deprecation-rules扩展报告所以忽略配置同样需要在启用了该扩展的项目中生效。官方文档见 CLAUDE.md 中的说明对错误详情页的约定是不主动建议忽略错误因此请仅在你有明确迁移计划、并已将废弃依赖登记在待办中时才考虑基线化切勿用它掩盖新引入的废弃依赖。小结requireExtends.deprecatedClass是phpstan-deprecation-rules扩展在phpstan-require-extends约束指向废弃类时给出的早期预警。它把废弃符号与强约束契约两个风险因素叠加在一起提示你尽快将约束迁移到非废弃的替代类上。修复本身很简单——替换标签引用并同步更新实现方但它的价值在于阻止废弃依赖通过接口/trait 契约在新代码中持续扩散。配合 errorsIdentifiers.json 中的标识注册信息和website/errors/目录下的同族文档你可以系统性地治理整个代码库中的phpstan-require-extends约束质量。赞分享开发工具代码质量静态分析【免费下载链接】phpstanPHP Static Analysis Tool - discover bugs in your code without running it!项目地址https://gitcode.com/gh_mirrors/ph/phpstan点击查看免费下载相关推荐PHPStan 错误标识符解析requireExtends.deprecatedEnum——phpstan-require-extends 引用已废弃枚举PHPStan 错误标识符解析requireExtends.deprecatedEnum——phpstan require extends 引用已废弃枚举开发工具代码质量静态分析PHPStan 错误标识符 requireExtends.deprecatedInterfacephpstan-require-extends 引用已弃用接口的检测与修复PHPStan 错误标识符 requireExtends.deprecatedInterface phpstan require extends 引用已弃用开发工具代码质量静态分析PHPStan 错误标识符解析selfOut.deprecatedTrait —— 当 phpstan-self-out 引用了已弃用的 TraitPHPStan 错误标识符解析 selfOut.deprecatedTrait —— 当 phpstan self out 引用了已弃用的 Trait se开发工具代码质量静态分析上一篇抖音无水印下载终极指南如何3步保存高清视频到本地下一篇抖音批量下载终极指南5分钟快速掌握免费无水印视频获取技巧创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考