PHP 8.4 #[Deprecated] 属性如何管理弃用提示：从标注到 CI 检查

维护一个仍被多个项目调用的 PHP SDK 时，真正麻烦的不是写出新方法，而是让旧方法在继续可用的同时明确告诉调用方该迁移到哪里。PHP 8.4 的 #[\\Deprecated] 属性把这件事变成了运行时可见的契约：调用被标记的方法会触发弃用提示，消息里可以写替代方法和起始版本。

把弃用信息写在旧 API 的声明旁，再用反射和 CI 检查它是否完整，能让“以后再迁移”变成有证据的迁移清单。

先把旧调用和新入口放在同一条迁移路径上

示例设定是一个发消息的 SDK。旧客户端入口 LegacyClient::send 不能立刻删除，因为业务代码还在使用它；新入口 NewClient::send 负责承接后续参数。弃用标注的价值在于，它把“旧方法还在，但不应继续新增调用”表达给 IDE、运行日志和代码评审。

send($recipient, $body);
    }
}

(new LegacyClient())->send('ops@example.test', 'build passed');

这里的控制流很短：调用者进入 LegacyClient::send，PHP 先发出弃用提示，方法体再把请求转交给 NewClient::send。这意味着迁移可以分批完成，旧调用不会因为一次发布就全部中断。

message 和 since 要写成能推动行动的信息

message 不只是“这个方法旧了”。它应该给出替代入口；since 则说明团队从哪个版本开始把它视为弃用。PHP 手册明确指出，这两个值会被带进弃用消息，但内容本身不会由 PHP 校验，所以版本写错仍然是项目自己的责任。

例如，use NewClient::send() instead 比“请更新代码”更可执行。若替代方法需要改变参数顺序，也应在消息中说清楚，而不是让调用方再去翻提交记录。这个字段不会自动验证版本号，发布前最好由测试覆盖。

用反射把弃用标注变成可验证的检查点

运行时提示适合发现真实调用，但它无法证明每个旧入口都写了替代方案。可以用反射读取 LegacyClient::send 的属性，检查属性类名以及两个参数是否存在。

getAttributes(\\Deprecated::class);

if (count($attributes) !== 1) {
    throw new RuntimeException('LegacyClient::send must be deprecated');
}

$deprecated = $attributes[0]->newInstance();
assert($deprecated->message === 'use NewClient::send() instead');
assert($deprecated->since === '8.4');

图中的数据路径是 ReflectionMethod 读取声明，getAttributes() 返回属性实例描述，再由 newInstance() 得到 Deprecated 对象。把这个检查放入测试目录，就能在有人删除替代说明时立即失败。

在 CI 中同时检查调用提示和元数据完整性

项目可以分成两个检查：一组测试实际调用 LegacyClient::send，确认错误处理器收到 E_USER_DEPRECATED；另一组测试反射元数据，确认 message 和 since 没有空值。两组检查关注点不同，不能只留其中一组。

send('ops@example.test', 'build passed');
restore_error_handler();

assert(is_string($seen));
assert(str_contains($seen, 'NewClient::send()'));

当 CI 运行这段测试时，成功状态不是“命令有输出”，而是 $seen 捕获到 E_USER_DEPRECATED，且消息包含替代入口。若 PHP 配置或测试框架把弃用错误升级为异常，也应保持这个断言目标不变，只调整测试适配层。

几个容易把迁移信号做坏的细节

不要把替代方法写成尚未发布的名字

弃用消息会被复制到 issue、日志和 IDE 提示中。替代方法如果还没进入当前版本，调用方会得到无法执行的建议。先确认 NewClient::send 已经存在，再发布 LegacyClient::send 的标注。

不要把 since 当成自动版本校验器

since 是说明性字符串，不会替你判断项目版本。团队仍需在变更记录和 CI 中核对版本边界，尤其是多个维护分支同时发布时。

不要只依赖真实流量触发提示

低频接口可能很久都没有线上调用。反射检查可以在合并请求阶段发现标注缺失，调用测试则保证运行时行为没有被改坏。

把一次标注变成可持续的迁移规则

适合落地的最小规则是：旧入口旁必须有 #[\\Deprecated]，message 写明确替代方法，since 写当前弃用起点；测试目录同时覆盖运行时提示和反射字段。这样，删除旧入口之前，团队能从 CI 结果看到还有哪些代码路径没有迁移。

相关问题

PHP 8.4 的 Deprecated 属性会自动删除旧方法吗？

不会。它负责发出弃用信号，旧方法是否删除仍由库作者按兼容策略决定。

Deprecated 属性的 message 可以省略吗？

可以，但省略后调用方只能知道入口已弃用，无法直接看到替代方案。对公共 SDK，通常应保留可行动的 message。