PHPStan 错误标识符 `return.deprecatedClass` 全解析:返回类型引用已弃用类时的检测与修复
PHPStan 错误标识符 return.deprecatedClass 全解析:返回类型引用已弃用类时的检测与修复
导读
return.deprecatedClass 是 PHPStan 在启用 phpstan/phpstan-deprecation-rules 扩展后报告的静态分析错误标识符,用于捕捉函数或方法的原生返回类型声明引用了被 @deprecated 标记的类这一弃用依赖问题。本文以 website/errors/return.deprecatedClass.md 文档为主体,结合当前仓库中错误标识符映射表、同类文档与 e2e 依赖锁定文件,系统讲解该错误的触发场景、底层规则来源、两种标准修复方案以及同类标识符家族,帮助你在弃用迁移中彻底清理返回类型层面的过期依赖。
一、错误标识符速览
该文档的 frontmatter 定义了错误标识符的基本元数据:
---
title: "return.deprecatedClass"
shortDescription: "Return type declaration references a deprecated class."
ignorable: true
---
title:错误标识符全名,即return.deprecatedClass;shortDescription:一句话概括触发条件——"返回类型声明引用了已弃用的类";ignorable:值为true,表示该错误可以被忽略,既可以在分析配置中通过ignoreErrors定向排除,也可以写入 baseline 文件固化豁免。
从标识符命名规则看(参见 website/errors/CLAUDE.md 的前缀参考表),return 前缀专门对应 PHP 原生返回类型声明(Native return type declaration),与 parameter(原生参数类型)、property(原生属性类型)等前缀并列。因此 return.deprecatedClass 只针对 function foo(): OldClass 这种原生类型声明写法,而不涉及 @return PHPDoc 标签的检查。
二、触发场景:最小复现示例
以下代码会在 PHPStan 分析时报告 return.deprecatedClass:
<?php declare(strict_types = 1);
namespace App;
/** @deprecated Use NewService instead */
class OldService
{
}
function createService(): OldService
{
return new OldService();
}
关键点在于:
OldService类通过 PHPDoc 标签@deprecated被标记为弃用;- 函数
createService()的原生返回类型写作: OldService; - 尽管函数体内部
new OldService()也会触发同类问题(对应new.deprecatedClass标识符,见 website/errors/new.deprecatedClass.md),但本错误聚焦的是返回类型声明本身对弃用类的引用。
三、为什么会报告这个错误
3.1 规则来源:phpstan-deprecation-rules 扩展
文档明确指出,该错误由 phpstan/phpstan-deprecation-rules 包报告,并非 PHPStan 核心自带的规则。当前仓库的标识符映射表 website/src/errorsIdentifiers.json 中可以看到精确的归属关系:
- 标识符
return.deprecatedClass被映射到规则类PHPStan\Rules\Deprecations\RestrictedDeprecatedClassNameUsageExtension; - 该规则类隶属于
phpstan/phpstan-deprecation-rules扩展包(2.0.x 分支)。
e2e 集成测试的依赖锁定文件(如 e2e/composer.lock)也印证了该扩展在生态中的实际使用版本为 ^2.0(如 2.0.4、2.0.5),说明这是一个持续维护的官方扩展。
3.2 语言语义层面的原因
从 PHP 语言语义看,原生返回类型声明引用一个 @deprecated 的类,意味着:
- 对外契约绑定已弃用符号:该函数公开承诺返回
OldService,而OldService已被标注"计划移除或替换"; - 依赖被传播:所有调用
createService()的调用方都会间接依赖OldService,即使它们自己从未直接引用过这个类; - 替换成本被放大:弃用类一旦移除,函数签名与全部调用点都要联动修改,而不是单个点位的替换。
这正是 deprecation-rules 扩展要在静态分析阶段提前暴露该问题的原因——让弃用依赖在代码层面"可视化"。
四、如何修复
方案一:替换返回类型中的弃用类(推荐)
将返回类型改为官方推荐的替代类,并同步修改函数体内部:
<?php declare(strict_types = 1);
namespace App;
-function createService(): OldService
+function createService(): NewService
{
- return new OldService();
+ return new NewService();
}
这是最彻底的修复方式:既消除了返回类型的弃用引用,也顺带移除了函数体内部的弃用实例化。实践中应注意 NewService 必须与 OldService 保持接口兼容(或满足调用方的类型期望),否则需要同步调整调用点。
方案二:函数本身弃用时标记为弃用以抑制报告
如果函数本身就是弃用迁移流程的一部分(例如旧接口保留一个版本供过渡期调用),可以把函数也标记为 @deprecated。文档明确说明:当函数自身已弃用时,该错误不会被报告:
<?php declare(strict_types = 1);
namespace App;
+/** @deprecated Use createNewService() instead */
function createService(): OldService
{
return new OldService();
}
其原理是:RestrictedDeprecatedClassNameUsageExtension 这类规则遵循"弃用代码中使用弃用符号不再重复告警"的设计哲学——既然整个函数都已进入弃用生命周期,调用方本就不应再新增对它的依赖,再在返回类型层面重复报错只会增加噪声。
方案三:通过配置忽略该错误
由于该标识符的 ignorable 为 true,当确实无法立即修复(如第三方库尚未发布替代版本)时,可以在 PHPStan 配置中定向忽略,或在 baseline 中固化:
parameters:
ignoreErrors:
-
identifier: return.deprecatedClass
path: src/Legacy/Api.php
注意:忽略应作为临时过渡手段,长期维护仍应回归方案一或方案二。
五、同类标识符家族与差异化
return.* 前缀下存在一组结构完全对称的标识符,区别仅在于返回类型引用的符号种类:
| 标识符 | 触发场景 | 对应文档 |
|---|---|---|
return.deprecatedClass |
返回类型引用弃用的类 | return.deprecatedClass.md |
return.deprecatedInterface |
返回类型引用弃用的接口 | return.deprecatedInterface.md |
return.deprecatedTrait |
返回类型引用弃用的 trait | return.deprecatedTrait.md |
return.deprecatedEnum |
返回类型引用弃用的枚举 | 同族文档(见 website/errors 目录) |
其中 return.deprecatedInterface 文档同样提供了"替换为替代接口"和"函数自身弃用则标记弃用以抑制"两种修复方案,规则类同样指向 RestrictedDeprecatedClassNameUsageExtension。也就是说,这一组标识符共享同一个底层规则类,仅按被引用符号的类型(类/接口/trait/枚举)区分标识符名。
从 website/errors/CLAUDE.md 的前缀参考表可以进一步看到,该规则类还覆盖了其他使用位置的弃用类检测,例如:
new.deprecatedClass:new OldService()实例化;parameter.deprecatedClass:原生参数类型声明;property.deprecatedClass:原生属性类型声明;instanceof.deprecatedClass:$x instanceof OldClass表达式;catch.deprecatedClass:catch (OldException $e)块;classConstant.deprecatedClass:OldClass::CONSTANT访问。
这说明弃用类检测是一套按使用位置细分的标识符体系,return 只是其中一类。同一份弃用代码可能同时触发多个不同前缀的标识符,修复时应一并处理。
六、在项目中使用 deprecation-rules 的实践建议
- 安装扩展:通过 Composer 引入
phpstan/phpstan-deprecation-rules(当前仓库 e2e 锁定文件中可见其版本约束为^2.0),并在phpstan.neon中includes对应的 rules 配置文件; - 渐进式清理:将 deprecation-rules 与 baseline 配合使用——先扫描全量报告生成 baseline,再按标识符(如
return.deprecatedClass)分批修复并逐步从 baseline 移除,避免一次性整改压力过大; - 优先处理返回类型:返回类型是类的公共 API 契约,
return.deprecatedClass的修复优先级应高于函数体内的弃用使用,因为它影响调用方; - 与
@deprecated标注规范配合:确保每个弃用类都写明@deprecated注释并推荐替代符号(如@deprecated Use NewService instead),这既是本错误触发的前提,也是方案二中文档要求"标记函数弃用"时的信息基础。
七、深入阅读
- return.deprecatedClass.md:本文主题文档原文
- website/errors/CLAUDE.md:错误标识符文档的生成规范与标识符前缀体系说明
- website/src/errorsIdentifiers.json:标识符到规则类与源码位置的完整映射表(含
return.deprecatedClass的归属信息) - return.deprecatedInterface.md 与 return.deprecatedTrait.md:同族标识符的对照文档
- new.deprecatedClass.md:函数体内部实例化弃用类的对应标识符文档
- e2e/composer.lock:deprecation-rules 扩展在集成环境中的实际版本约束(
^2.0)