企业官网建设流程全解析

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

PHPStan 的parameter.internalClass错误标识（error identifier）用于报告这样一种代码模式：某个函数或方法的参数类型声明，使用了带有@internal标记、且来自其他命名空间/包的内部类。本文以 parameter.internalClass.md 为骨架，结合 PHPStan 仓库中该标识的规则来源（RestrictedInternalClassNameUsageExtension）与配套的同类标识文档（parameter.internalEnum/parameter.internalInterface/parameter.internalTrait），完整讲解该错误的触发条件、底层原理、修复方式与忽略方法，帮助读者在集成第三方包时识别并消除对不稳定内部 API 的依赖。

错误速览：何时触发parameter.internalClass

该标识对应的触发场景可概括为一句话：

函数或方法参数的类型声明使用了某个带有@internal标记的类，而这个类定义在**另一个命名空间（或包）**中。

其典型的最小复现代码如下（直接取自 parameter.internalClass.md）：

<?php declare(strict_types = 1); namespace Vendor { /** @internal */ class InternalType {} } namespace App { function process(\Vendor\InternalType $param): void {} }

在这个例子中：

• Vendor命名空间中定义了一个被@internal标记的类InternalType；
• App命名空间（可理解为使用方/下游代码）中的函数process()把它当作参数类型声明\Vendor\InternalType $param使用；
• PHPStan 检测到这种跨命名空间的内部类引用，报告错误标识parameter.internalClass。

需要注意的是，该错误面向的是类型声明位置（native type declaration on function/method parameter）。PHPStan 的 website/errors/CLAUDE.md 中的标识前缀参考表明确给出了parameter前缀的含义：

也就是说，parameter.*系列标识专门针对参数类型声明这一处引用位置；内部类被引用在其他位置（如new、instanceof、@property、静态调用等）时，会分别得到new.internalClass、instanceof.internalClass、propertyTag.internalClass、staticMethod.internalClass等其他标识，它们共享相同的底层规则但拥有独立的前缀。

为什么会被报告：@internal与不稳定 API

在 PHP 生态中，@internal是一个被广泛认可的文档约定（docblock annotation）：类、接口、枚举或 trait 一旦被标记为@internal，就表示它是库/包的实现细节（implementation detail），不属于对外公开的 API 面。

正如文档 parameter.internalClass.md 所解释的：

• 内部类是库的实现细节，不属于其公共 API；
• 它们可能在未来的版本中不经通知地变更或被删除（may change or be removed in future versions without notice）；
• 把内部类用作参数类型，会创建一个对不稳定 API的依赖（creates a dependency on an unstable API）。

从下游使用者的视角看，这种依赖是脆弱的：一旦上游库在某个次版本中重命名、移动或删除了这个内部类，你的函数签名就会静默失效——轻则类型检查失真，重则直接引发运行时错误。PHPStan 在静态分析阶段就提前暴露这类隐患，帮助你把耦合消灭在写代码的时候。

底层的规则实现：RestrictedInternalClassNameUsageExtension

从 errorsIdentifiers.json 中可以看到，parameter.internalClass标识由 PHPStan 源码仓库（phpstan-src，2.3.x 分支）中的PHPStan\Rules\InternalTag\RestrictedInternalClassNameUsageExtension规则产生：

"parameter.internalClass": { "PHPStan\\Rules\\InternalTag\\RestrictedInternalClassNameUsageExtension": { "phpstan/phpstan-src": [ "https://github.com/phpstan/phpstan-src/blob/2.3.x/src/Rules/InternalTag/RestrictedInternalClassNameUsageExtension.php#L65" ] } }

同类标识parameter.internalEnum、parameter.internalInterface、parameter.internalTrait也都由同一个规则类产生（参见 errorsIdentifiers.json），说明该规则统一负责检测“类名被引用”这一行为，再依据引用位置（此处为参数类型声明）生成不同前缀的标识。

这一规则实际上构建在 PHPStan 的Restricted Usage 扩展机制之上。根据 restricted-usage-extensions.md 的说明，RestrictedClassNameUsageExtension会在超过 25 处类名引用位置被调用（包括 class extends、implements、各类参数/返回类型、PHPDoc 引用、静态调用、静态属性与类常量访问等），其接口签名如下：

namespace PHPStan\Rules\RestrictedUsage; use PHPStan\Analyser\Scope; use PHPStan\Reflection\ClassReflection; use PHPStan\Rules\ClassNameUsageLocation; interface RestrictedClassNameUsageExtension { public function isRestrictedClassNameUsage( ClassReflection $classReflection, Scope $scope, ClassNameUsageLocation $location, ): ?RestrictedUsage; }

其中ClassNameUsageLocation对象提供createMessage()与createIdentifier()两个方法，负责把“内部类 Foo”这种描述加上位置前缀，生成形如propertyTag.internalClass、new.internalClass、class.implementsInternalClass等不同的标识——parameter.internalClass正是参数类型声明这一位置对应的产物。错误消息的典型形式为internal class Foo，标识部分则为internalClass。

如何修复：改用公共 API 类型

文档给出的修复建议非常直接：把内部类替换为公共 API 类型（如公开的接口或非内部类）：

namespace App { - function process(\Vendor\InternalType $param): void {} + function process(\Vendor\PublicType $param): void {} }

除此之外，结合该系列文档的通用修复策略，还可以考虑以下做法：

• 优先使用接口：如果上游包为内部类提供了公开接口，应优先以接口作为参数类型，这既能解耦实现细节，也符合面向接口编程的习惯；
• 联系上游维护者：如果该功能没有公开替代品，可以向包维护者提出需求，请求将所需能力暴露为公共 API；
• 在自己的代码中解除对内部类的直接引用：不要在业务签名里“借用”上游内部类型，必要时通过组合或适配层（adapter）封装。

同一规则的变体：parameter.internalEnum/parameter.internalInterface/parameter.internalTrait

parameter.internalClass并非孤例。同一规则类还产生了三个内容结构完全一致的兄弟标识，它们与internalClass的触发逻辑、修复思路完全相同，只是目标类型不同：

parameter.internalEnum—— 参数类型声明使用了来自其他包的@internal枚举：

namespace Vendor { /** @internal */ enum InternalStatus: string { case Active = 'active'; } } namespace App { function process(\Vendor\InternalStatus $status): void {} }

parameter.internalInterface—— 参数类型声明使用了来自其他包的@internal接口：

namespace Vendor { /** @internal */ interface InternalInterface {} } namespace App { function process(\Vendor\InternalInterface $handler): void {} }

parameter.internalTrait—— 参数类型声明（这里是 PHPDoc 形式的@param）引用了来自其他包的@internaltrait：

namespace Vendor { /** @internal */ trait InternalTrait { public function doSomething(): void {} } class Foo { use InternalTrait; } } namespace App { /** @param \Vendor\InternalTrait $x */ function process($x): void {} }

parameter.internalTrait的例子还揭示了一个额外的要点：PHP 本身并不支持把 trait 用作原生类型提示，因此该例中参数类型只能以 PHPDoc 的@param形式出现；即便抛开@internal的问题，把 trait 当作类型使用本身也是一种不合理的模式（参见 parameter.internalTrait.md）。

四个标识的修复方式完全一致，即替换为公共 API 类型：

namespace App { - function process(\Vendor\InternalStatus $status): void {} + function process(\Vendor\PublicStatus $status): void {} }

namespace App { - /** @param \Vendor\InternalTrait $x */ + /** @param \Vendor\PublicInterface $x */ function process($x): void {} }

如何忽略该错误（ignorable: true）

parameter.internalClass的文档 frontmatter 中标明了ignorable: true，意味着该错误属于“可忽略”类别——在确认无法替换类型、或确实需要临时引用内部类的情况下，你可以通过 PHPStan 的忽略机制压制它：

• 使用@phpstan-ignore-next-line行内注释忽略下一行的报告；
• 使用@phpstan-ignore parameter.internalClass指定标识进行精确忽略；
• 在phpstan.neon的ignoreErrors中按标识或消息模式全局忽略。

不过需要再次强调：PHPStan 官网对错误详情页的说明（参见 website/errors/CLAUDE.md）中明确建议，修复错误本身优先于忽略错误——只有当代码确实无法避免该模式时，才应诉诸忽略手段，否则@internal所暴露的不稳定 API 依赖依然存在。

小结

parameter.internalClass是 PHPStan 2.x 中由RestrictedInternalClassNameUsageExtension规则产出的错误标识，用于在函数/方法参数类型声明处拦截对跨命名空间@internal内部类的引用。它与parameter.internalEnum、parameter.internalInterface、parameter.internalTrait共同构成parameter.internal*家族，底层基于 PHPStan 的 Restricted Usage 扩展机制与ClassNameUsageLocation位置识别：

• 触发条件：参数类型声明引用了带@internal标记的外部类/接口/枚举/trait；
• 风险本质：对上游不稳定实现细节形成脆弱依赖，未来版本可能无通知变更或删除；
• 推荐修复：改用公共 API 类型（接口或公开类）；
• 可忽略性：该标识ignorable: true，可被ignoreErrors与行内忽略注释压制，但应优先修复。

对于任何以 PHPStan 做 CI 静态检查、并深度集成第三方包的团队来说，尽早发现并消除parameter.internalClass这类内部 API 耦合，是保持代码库长期可维护、可升级的关键一环。

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