PHPStan 错误标识符 sealed.internalTrait:当 `@phpstan-sealed` 引用了跨包的 `@internal` Trait
PHPStan 错误标识符 sealed.internalTrait:当 @phpstan-sealed 引用了跨包的 @internal Trait
sealed.internalTrait 是 PHPStan 在分析 @phpstan-sealed PHPDoc 标签时抛出的一类错误标识符:当该标签引用了一个来自其他包(vendor 依赖)、且被标记为 @internal 的 trait 时触发。本文基于 PHPStan 仓库中该错误标识符的官方文档 sealed.internalTrait.md,结合错误标识符注册表 errorsIdentifiers.json 与 phpdocs-basics.md 中的 @phpstan-sealed 语法说明,完整讲解它的触发条件、成因、修复方法及同族错误,帮助你理解"密封(sealed)类型层次"与"内部 API 约束"交叉时的 PHPStan 静态分析规则。
错误标识符速览
该文档的 front matter 提供了两个关键元信息:
title: "sealed.internalTrait":这是你在 PHPStan 输出中看到的稳定错误标识符(error identifier),可用于ignoreErrors配置、基线(baseline)以及 CI 中的按标识符过滤;ignorable: true:表明该错误属于可忽略类别——你可以在 PHPStan 配置文件中通过该标识符精确忽略或纳入基线,而无需放弃整条规则。
从命名约定看,sealed 前缀对应 @phpstan-sealed PHPDoc 标签(见 website/errors/CLAUDE.md 中"Prefixes"一节),internalTrait 后缀表示问题出在"内部 trait"上。整个 sealed.internal* 家族还包括 sealed.internalClass、sealed.internalInterface、sealed.internalEnum 三个同构标识符,它们的文档结构完全一致(可对照 sealed.internalClass.md 与 sealed.internalInterface.md)。
触发场景:完整代码示例
以下代码来自官方文档 sealed.internalTrait.md,会在分析时报告 sealed.internalTrait:
<?php declare(strict_types = 1);
namespace ThirdParty {
/** @internal */
trait InternalTrait {}
}
namespace App {
/**
* @phpstan-sealed \ThirdParty\InternalTrait
*/
interface HandlerProvider
{
}
}
拆解这段代码的要素:
ThirdParty命名空间中定义了一个 trait,并用/** @internal */标注为内部实现细节;App(你的业务代码所在包)中有一个接口HandlerProvider,通过@phpstan-sealed \ThirdParty\InternalTrait将该 trait 声明为密封类型层次的合法成员;- 由于该 trait 不属于当前包,PHPStan 判定这是一次跨包引用内部 API 的行为,于是报告
sealed.internalTrait。
为什么会报告这个错误
文档原文给出的原因非常明确:
@phpstan-sealed标签引用了一个在其他包中被标记为@internal的 trait。内部 trait 不属于其所在包的公共 API,随时可能被修改或移除。在@phpstan-sealed标签中引用它们,等于依赖了一个实现细节,该依赖可能在毫无通知的情况下被破坏。
结合 @phpstan-sealed 的语义可以更透彻地理解这一点。根据 phpdocs-basics.md 中的 "Sealed classes" 一节(PHPStan 2.1.18 起可用):
/** @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 通过枚举"允许的子类型白名单"来限制一个类或接口可以被谁继承/实现,PHP 语言本身没有 sealed class 概念,所以这套约束完全由 PHPStan 静态分析保证。当白名单中出现一个来自第三方包的 @internal trait 时,意味着你的密封层次把"别人随时可能删掉的内部实现"当成了契约的一部分——一旦上游包升级并移除该 trait,你的 HandlerProvider 密封约束就会失效,属于典型的脆弱依赖。
从源码映射角度看,仓库中的 errorsIdentifiers.json 记录了该标识符与底层规则的关系:sealed.internalTrait 以及 sealed.internalClass、sealed.internalEnum、sealed.internalInterface 四个标识符均由 PHPStan\Rules\InternalTag\RestrictedInternalClassNameUsageExtension 这一扩展规则负责产生(对应 phpstan/phpstan-src 2.3.x 分支中 src/Rules/InternalTag/RestrictedInternalClassNameUsageExtension.php 的实现)。也就是说,这个错误并不是单独的密封规则抛出的,而是"密封标签中对类的引用"被送入内部标签(@internal)使用限制规则检查后得到的结果——PHPStan 对密封标签引用的符号,与对普通代码中使用的符号一样,执行了跨包 @internal 访问约束。
如何修复:只引用公共(非 internal)类型
官方文档给出的修复方式很直接:在 @phpstan-sealed 标签中只引用公共(非 internal)类型。
<?php declare(strict_types = 1);
namespace App;
-use ThirdParty\InternalTrait;
+use ThirdParty\PublicClass;
/**
- * @phpstan-sealed InternalTrait
+ * @phpstan-sealed PublicClass
*/
interface HandlerProvider
{
}
修复要点:
- 将白名单中的
InternalTrait替换为该包真正公开、稳定且允许作为子类型的类(示例中为PublicClass); - 如果第三方包提供了替代的公共接口或基类,优先引用那些公共符号;
- 若该 trait 只是被临时用于类型约束,且没有公共替代品,则需要重新设计密封层次,避免依赖上游实现细节。
重要边界:同包内的 @internal 不会触发
文档在结尾特别强调了一条关键规则:
如果该 trait 与当前代码属于同一个包,错误不会被报告。
@internal限制只适用于跨包(cross-package)使用。
这一点与 PHPStan 处理 @internal 的整体策略一致:@internal 标记的意义在于对外部消费者隐藏实现细节,同一个包内的代码访问自己的内部符号是正常且必要的(框架内部组件之间互相依赖内部实现是常态)。因此:
- 在你自己包内的类、接口、trait、enum 上标注
@internal,并在同一包的其他密封定义中引用它——安全,不报告; - 只要引用跨越了包边界(例如你的业务包引用了 vendor 依赖包中的
@internal符号)——报告。
这也解释了为什么修复示例中只需把引用目标换成公共类型,而不需要删掉整个 @phpstan-sealed 标签:密封约束本身没有问题,问题只在于白名单中出现了不该出现的跨包内部符号。
同族错误与排查建议
sealed.internalTrait 只是 sealed.internal* 家族的一员,其余三个标识符的触发逻辑与修复方式一一对应:
| 标识符 | 被引用的符号 | 官方文档 |
|---|---|---|
sealed.internalTrait |
@internal trait |
sealed.internalTrait.md |
sealed.internalClass |
@internal class |
sealed.internalClass.md |
sealed.internalInterface |
@internal interface |
sealed.internalInterface.md |
sealed.internalEnum |
@internal enum |
同上族结构(注册于 errorsIdentifiers.json) |
与之相邻的还有 sealed.deprecatedClass / sealed.deprecatedInterface / sealed.deprecatedTrait / sealed.deprecatedEnum——当密封标签引用被标记为 @deprecated 的符号时触发(见 sealed.deprecatedTrait.md)。如果你的密封标签同时引用了"内部 + 即将废弃"的符号,PHPStan 会分别给出对应标识符,建议逐一替换为公共、稳定的替代类型。
排查实战建议:
- 在 CI 日志或
phpstan analyse输出中,按sealed.internalTrait关键字过滤定位到具体文件与行号; - 打开报错位置的
@phpstan-sealed标签,逐一核对白名单中的每个符号是否属于当前包; - 对属于 vendor 包的符号,检查其是否带有
@internal标注(可在 IDE 中查看依赖源码的 PHPDoc); - 若确实需要保留该依赖,可在
phpstan.neon的ignoreErrors中使用identifier: sealed.internalTrait精确忽略,但这会掩盖真实的上游变更风险,不推荐作为长期方案; - 更稳妥的做法是联系上游包作者,请求提供公共替代类型,或在自己的包中定义可接受的公共类型放入白名单。
小结
sealed.internalTrait 是 PHPStan 对"密封类型层次"与"跨包内部 API 约束"两条规则交叉检查的产物:@phpstan-sealed 标签要求白名单符号稳定、公共、可被外部引用,而 @internal 符号恰恰是"不应被外部引用"的。两者的冲突意味着你的密封契约依赖了上游实现细节。修复的核心原则只有一个——让 @phpstan-sealed 白名单中的每一个符号都来自公共 API,且最好与当前代码同包;这样既能享受密封类型带来的可控继承,又不会把代码的稳定性建立在别人随时可能移除的内部实现之上。