PHPStan 错误标识符 sealed.deprecatedClass 完全指南：@phpstan-sealed 引用废弃类时的检测与修复

开发工具代码质量静态分析【免费下载链接】phpstanPHP Static Analysis Tool - discover bugs in your code without running it!项目地址https://gitcode.com/gh_mirrors/ph/phpstan点击查看免费下载PHPStan 的sealed.deprecatedClass是phpstan/phpstan-deprecation-rules扩展提供的错误标识符error identifier用于在phpstan-sealed密封类型标签引用了被deprecated标记的类时发出告警。本文以 PHPStan 官方错误文档库website/errors/sealed.deprecatedClass.md为骨架结合仓库内的同族标识符文档与密封类语法说明系统讲解该错误的触发场景、底层原理、修复方案及同族错误对照帮助你在使用 PHPStan 密封类型sealed classes特性时避免对即将移除的废弃符号形成隐性依赖。一、错误概览一句话理解 sealed.deprecatedClass属性说明错误标识符sealed.deprecatedClass短描述phpstan-sealed标签引用了被标记为deprecated的类所属扩展phpstan/phpstan-deprecation-rules是否可忽略是ignorable: true可在基线或忽略规则中处理对应语法特性phpstan-sealedPHPDoc 密封类型标签按 PHPStan 错误文档的前缀约定见 website/errors/CLAUDE.mdsealed前缀专门对应phpstan-sealedPHPDoc 标签与attribute、mixin、requireExtends等前缀一样属于基于ClassNameUsageLocation的规则分类。二、完整触发示例以下代码会触发sealed.deprecatedClass错误示例取自官方文档?php declare(strict_types 1); namespace App; /** deprecated Use NewHandler instead */ class OldHandler { } /** * phpstan-sealed OldHandler */ interface HandlerProvider { }触发条件可拆解为三点存在一个类OldHandler其 PHPDoc 中带有deprecated标记存在一个密封声明此处为接口HandlerProvider其phpstan-sealed标签中列出了该废弃类该密封声明本身没有被标记为deprecated若声明自身已废弃则不会报错详见下文第六节。三、为什么会被报告原理剖析官方文档给出了明确的原因说明phpstan-sealed标签用于限制哪些类型允许实现或继承被密封的类型。当该标签引用了一个被标记为deprecated的类时实际上是在密封约束中建立了一个对即将被移除符号的依赖。3.1 密封类型机制回顾密封类型sealed classes是 PHPStan 2.1.18 起提供的能力见 website/src/writing-php-code/phpdocs-basics.md在类或接口上使用phpstan-sealed即可将允许扩展/实现它的类型限制为标签中列出的白名单/** phpstan-sealed FooClass|BarClass */ class BaseClass {} class FooClass extends BaseClass {} class BarClass extends BaseClass {} class BazClass extends BaseClass {} // Error: Type BazClass is not allowed to be a subtype of BaseClass.phpstan-sealed标签接受一个或多个类/接口名用|分隔被密封的类型在定义可扩展子类型集合的同时也承担了唯一合法依赖者的角色。3.2 密封约束与废弃符号的冲突当白名单中的符号已被deprecated标记时就产生了语义冲突废弃标记的语义deprecated表示该符号已计划在未来的版本中被移除新代码不应再依赖它密封标签的语义phpstan-sealed OldHandler意味着本类型的合法子类型中必须包含 OldHandler这等于把废弃类重新钉死在类型层级中两者的矛盾密封约束本质上是在声明这个废弃类依然是我们类型体系的一部分与移除计划背道而驰会阻碍后续的符号清理工作。因此phpstan-deprecation-rules 扩展将这种引用视为需要修复的废弃用法并报告错误。四、如何修复标准修复方案官方文档给出的首选修复方式是将phpstan-sealed标签中的废弃类替换为其推荐的替代类。?php declare(strict_types 1); namespace App; /** - * phpstan-sealed OldHandler * phpstan-sealed NewHandler */ interface HandlerProvider { }如果OldHandler的deprecated注释中已标明推荐替代如示例中的Use NewHandler instead直接按提示替换即可。替换后密封约束不再引用废弃符号类型层级对NewHandler开放依赖方向与新代码保持一致。五、同族错误对照sealed.* 系列标识符sealed.deprecatedClass并非孤立存在PHPStan 错误文档库中还有一组同族标识符覆盖了phpstan-sealed引用各类废弃/受限符号的场景标识符触发场景对应文档sealed.deprecatedClass引用废弃类sealed.deprecatedClass.mdsealed.deprecatedEnum引用废弃枚举sealed.deprecatedEnum.mdsealed.deprecatedInterface引用废弃接口sealed.deprecatedInterface.mdsealed.deprecatedTrait引用废弃 traitsealed.deprecatedTrait.mdsealed.internalClass/sealed.internalEnum/sealed.internalInterface/sealed.internalTrait引用internal符号sealed.internalClass.md 等sealed.nonObject标签中包含int、string、array等非对象类型sealed.nonObject.mdsealed.onTrait/sealed.onEnum在 trait 或 enum 上使用密封标签sealed.onTrait.md 等5.1 废弃枚举、接口与 trait 的同类问题与类的场景完全对称phpstan-deprecation-rules 同样会报告phpstan-sealed引用废弃枚举、接口或 trait 的情况。以废弃枚举为例见 sealed.deprecatedEnum.md?php declare(strict_types 1); namespace App; /** deprecated Use NewStatus instead */ enum OldStatus { case Active; case Inactive; } /** * phpstan-sealed OldStatus */ interface StatusProvider { }修复方式与类一致替换标签中的枚举即可/** - * phpstan-sealed OldStatus * phpstan-sealed NewStatus */ interface StatusProvider { }废弃 trait 的变体则允许直接用在类的密封标签中见 sealed.deprecatedTrait.md修复方式同样是替换为未废弃的替代/** - * phpstan-sealed DeprecatedTrait * phpstan-sealed NewTrait */ class Foo { }5.2 非对象类型的非法用法作为对照sealed.nonObject见 sealed.nonObject.md提示了密封标签的另一个约束由于只有对象才能被继承或实现phpstan-sealed中只能出现类/接口名int、string、array等标量类型均非法/** * phpstan-sealed int */ class Foo { }正确写法应使用类/接口名多个类型用|分隔?php declare(strict_types 1); /** * phpstan-sealed ChildA|ChildB */ class Foo { }六、重要边界什么情况下不会报错官方文档明确了一个关键豁免规则如果包含phpstan-sealed标签的声明本身也被标记为deprecated则不会报告该错误。?php declare(strict_types 1); namespace App; /** deprecated Use NewHandler instead */ class OldHandler { } /** * deprecated Use NewProvider instead * phpstan-sealed OldHandler */ interface HandlerProvider { }这里的逻辑是当整个声明都已废弃时其内部的密封约束只是废弃代码的一部分引用废弃类不再产生额外的新增依赖因此 phpstan-deprecation-rules 选择保持沉默避免在已经废弃的代码上叠加噪音告警。这体现了废弃规则设计中的级联废弃思想——废弃的容器不再单独追究其内部内容。七、实践中如何排查与处理7.1 定位错误运行 PHPStan 分析时错误信息中会携带标识符sealed.deprecatedClassvendor/bin/phpstan analyse --error-formattable在输出中找到形如下方的行------ ------------------------------------------------------------------ Line HandlerProvider ------ ------------------------------------------------------------------ 21 Tag phpstan-sealed references a deprecated class OldHandler. You can ignore this error by ... (sealed.deprecatedClass) ------ ------------------------------------------------------------------7.2 处理优先级按照 PHPStan 错误文档的修复优先级约定见 website/errors/CLAUDE.md建议按以下顺序处理修复实质问题替换phpstan-sealed中的废弃类为其替代类如第四节所示若声明整体已废弃给声明本身加上deprecated错误自然消失见第六节临时忽略该标识符ignorable: true可作为最后手段加入忽略规则或基线parameters: ignoreErrors: - identifier: sealed.deprecatedClass path: src/Legacy/*八、总结sealed.deprecatedClass是 PHPStan 密封类型特性phpstan-sealed自 PHPStan 2.1.18 起与废弃检测规则phpstan-deprecation-rules交汇处的产物。它确保开发者不会在密封类型白名单中引入已被标记移除的废弃类从而保持类型层级与代码演进方向一致。掌握它的触发条件、同族标识符废弃枚举/接口/trait、非对象类型以及声明自身废弃即豁免的边界规则就能在使用密封类型时写出既严谨又整洁的 PHPDoc 约束。赞分享开发工具代码质量静态分析【免费下载链接】phpstanPHP Static Analysis Tool - discover bugs in your code without running it!项目地址https://gitcode.com/gh_mirrors/ph/phpstan点击查看免费下载相关推荐PHPStan 错误标识符 sealed.deprecatedInterface 详解phpstan-sealed 引用已废弃接口的检测与修复PHPStan 错误标识符 sealed.deprecatedInterface 详解phpstan sealed 引用已废弃接口的检测与修复 sealed开发工具代码质量静态分析PHPStan 错误标识符 assert.deprecatedTrait 完全指南phpstan-assert 断言引用已废弃 Trait 的检测与修复PHPStan 错误标识符 assert.deprecatedTrait 完全指南 phpstan assert 断言引用已废弃 Trait 的检测与修复开发工具代码质量静态分析PHPStan 错误标识符 sealed.deprecatedEnum 详解phpstan-sealed 标签引用已弃用枚举的检测与修复PHPStan 错误标识符 sealed.deprecatedEnum 详解 phpstan sealed 标签引用已弃用枚举的检测与修复 导读 seale开发工具代码质量静态分析上一篇Understat用Python轻松获取专业足球数据分析的终极指南 下一篇终极指南5步在Windows上安装安卓APK文件告别笨重模拟器创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考