PHPStan 错误标识符 `return.deprecatedClass` 全解析:返回类型引用已弃用类时的检测与修复

原创2026-09-23 19:28:331,668 阅读
文章标签:开发工具代码质量静态分析

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();
}

关键点在于:

  1. OldService 类通过 PHPDoc 标签 @deprecated 被标记为弃用;
  2. 函数 createService() 的原生返回类型写作 : OldService;
  3. 尽管函数体内部 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 的实践建议

  1. 安装扩展:通过 Composer 引入 phpstan/phpstan-deprecation-rules(当前仓库 e2e 锁定文件中可见其版本约束为 ^2.0),并在 phpstan.neon 中 includes 对应的 rules 配置文件;
  2. 渐进式清理:将 deprecation-rules 与 baseline 配合使用——先扫描全量报告生成 baseline,再按标识符(如 return.deprecatedClass)分批修复并逐步从 baseline 移除,避免一次性整改压力过大;
  3. 优先处理返回类型:返回类型是类的公共 API 契约,return.deprecatedClass 的修复优先级应高于函数体内的弃用使用,因为它影响调用方;
  4. 与 @deprecated 标注规范配合:确保每个弃用类都写明 @deprecated 注释并推荐替代符号(如 @deprecated Use NewService instead),这既是本错误触发的前提,也是方案二中文档要求"标记函数弃用"时的信息基础。

七、深入阅读

登录后查看全文
phpstan