PHP 弃用 API 发布前怎么做版本验收：8.4/8.5 的 Deprecated、trait 与常量

维护 PHP 组件的时候，最容易漏处理的不是直接删掉旧函数，而是明确告诉所有调用方「现在还能用，但该换方案了」。以前大家习惯直接在注释里写 @deprecated，IDE 和静态分析工具确实能识别到，但没法让用户态函数、trait 或者常量统一在运行时触发弃用检查。PHP 8.4 引入 #[\\Deprecated] 之后，PHP 8.5 又把可标记的范围扩展到了 trait 和常量，整套迁移提示终于能和代码本身一起用 Reflection 做合规校验了。

如果项目要同时兼容 PHP 8.4 与 PHP 8.5，先把函数、方法和类常量的弃用标记落地；需要标记 trait 或全局常量时，再把最低运行版本抬到 PHP 8.5，并用 Reflection 校验标记是否真的生效。

先复现一个「注释写了但运行时不认」的旧 API 场景

假设你手里的组件有个旧的格式化入口，团队之前已经在 DocBlock 里写好了替代方法的提示。开发者打开编辑器能看到 IDE 标黄提醒，但服务启动时没有统一的识别信号，版本升级检查流程也没法从 Reflection 拿到对应的弃用结论。

这里的注释还是值得保留，毕竟不少静态分析工具还会读取它的内容；但它不等于 PHP 引擎原生支持的弃用标记，迁移工具如果只读取 Reflection 接口，会直接把这个函数当成正常可用的公开 API。

PHP 8.4 阶段先覆盖函数、方法和类常量场景

PHP 8.4 的 #[\\Deprecated] 是官方内置的原生属性，它可以直接挂载在用户态函数、方法和类常量上；调用被标记的函数或方法、访问被标记的常量时，就会自动触发弃用提示，Reflection 接口也能直接识别函数和方法的弃用状态。

message 字段适合写对应的替代 API 指引，since 可以标注对应的版本号或者发布日期。PHP 引擎不会替你校验 since 的格式，别直接拿它做自动升级逻辑；真正的版本门槛校验还是要靠 Composer 配置、CI 流水线或者运行时环境检查来实现。

PHP 8.5 的改动：trait 和全局常量也能当成迁移信号

PHP 8.5 的调整核心不是重新设计弃用属性，而是扩展了这个属性的允许挂载目标。trait 可以直接加弃用标记，类外部用 const 声明的编译期常量也可以加弃用标记；这对正在替换整套旧 trait 体系或者兼容常量集的开源库来说实用性很强。

这段代码的兼容边界要单独记录清楚：函数、方法和类常量的弃用标记能力来自 PHP 8.4；trait 和非类常量的标记能力扩展属于 PHP 8.5 新增范围。别看到项目已经用了 8.4 支持的弃用属性，就默认所有标记目标都能在 8.4 环境下正常解析。

用 Reflection 把「标记成功」变成可自动化检查的结果

发版前可以把弃用标记校验写成一段轻量的验收脚本。函数和方法通过 isDeprecated() 读取弃用状态；类常量则直接读取 ReflectionClassConstant 对应的弃用标识。下面的断言逻辑对应的就是迁移契约要求：所有旧入口必须被识别为弃用状态，新入口不能被误判为已弃用。

isDeprecated() === true);

$method = new ReflectionMethod(OrderFormatter::class, 'formatLegacy');
assert($method->isDeprecated() === true);

$constant = new ReflectionClassConstant(OrderFormatter::class, 'LEGACY_FORMAT');
assert($constant->isDeprecated() === true);

assert((new ReflectionClassConstant(OrderFormatter::class, 'CURRENT_FORMAT'))
    ->isDeprecated() === false);

验收脚本要放在对应目标 PHP 版本的 CI 镜像里跑。如果当前本地 CLI 是 PHP 8.2，不能把本地环境没有对应语义的结果当成 PHP 8.5 的运行结论；更稳妥的做法是分开保留 PHP 8.4 检查和 PHP 8.5 检查两条流水线，CI 报错的时候就能直接定位是代码标记写错了还是运行时版本不符合要求。

迁移时最容易踩到的四个边界坑

• 把注释完全等同于运行时属性。 @deprecated 还是服务于静态分析场景，不会自动让用户态函数进入运行时弃用状态。
• 误把 message 字段当成安全拦截策略。 弃用提示不会主动阻止代码调用，旧入口的真正移除要靠下一个主版本迭代、兼容层逻辑或者显式抛出异常实现。
• 忽略属性目标的版本差异。 PHP 8.4 可以正常处理函数、方法和类常量的弃用标记；trait 与全局常量的标记要按 PHP 8.5 的最低版本要求规划。
• 只测「有没有抛出警告」，不测 Reflection 结果。 线上环境的日志可能被错误级别配置过滤，基于 Reflection 的验收可以让迁移契约在 CI 环节就暴露出来，不会藏到线上运行才被发现。

常见问题

#[\\Deprecated] 会自动禁止旧函数调用吗？

不会。它的作用是发出弃用信号并提供迁移指引信息，要不要彻底删掉旧入口还是由库本身的版本策略决定。

since 可以写成日期格式吗？

可以。PHP 本身不会校验这个字符串的格式，项目里可以写版本号、日期或者内部发布标识，建议团队内部统一格式规则就行。

PHP 8.4 能不能标记 trait？

不能按 PHP 8.5 的扩展范围直接做规划。要标记 trait 或者全局常量的时候，要把语法解析和 CI 运行环境切换到 PHP 8.5。

为什么还要保留 @deprecated 注释？

静态分析工具、IDE 和低版本兼容工具仍然可能依赖 DocBlock 里的标记。迁移过渡期间保留原有注释，再补充原生属性，比一次性删掉注释的过渡过程要平稳很多。

把弃用标记接入版本发布检查流程

一套可直接落地的操作顺序是：先在兼容版本里给函数、方法和类常量加上弃用属性；再用 Reflection 写断言校验旧入口的弃用状态；确定可以把最低运行版本升到 PHP 8.5 之后，再给 trait 和全局常量加弃用标记；最后在文档和变更日志里写清楚替代 API 和预计删除的版本。这样弃用提示就不是散落在代码里的装饰，而是能被 CI 流水线和所有使用者共同识别的明确迁移信号。