PHP 8.5 常量怎样使用 Deprecated 属性标记弃用风险

PHP 8.5 给“类外编译期常量”增加了属性标记能力，内置的 Deprecated 属性也可以用于这类常量。迁移旧配置名时，可以把替代建议和起始版本写在常量声明上；调用方继续读取旧常量时会得到弃用提示，扫描脚本则可以用 ReflectionConstant 找出仍需处理的项。

这个能力适合做兼容迁移提醒，不等于自动替换常量，也不会替业务代码决定新旧配置的切换时机。下面按“变更范围、最小写法、盘点方式、兼容清单”展开。

官方资料：https://www.php.net/manual/en/class.deprecated.php

PHP 8.5 改变了哪类常量

PHP 8.5 的变化点不是“所有常量都能随意加任意属性”，而是把属性目标扩展到了类外的编译期常量。官方文档把这个目标称为 Attribute::TARGET_CONSTANT；Deprecated 的目标列表因此可以覆盖函数、方法、类常量、类、Trait，以及类外常量。

要先分清两个边界：

用 Deprecated 标记类外常量

最小写法是在 const 前放置 #[\Deprecated]。建议同时填写 message 和 since：前者告诉调用方应该换成什么，后者帮助迁移脚本和版本说明建立时间边界。

message 和 since 是 Deprecated 构造函数的可选参数。PHP 会把它们放进弃用提示，但不会替你修改 $ttl 的值，也不会把旧常量重定向到新常量。

把弃用提示当成迁移信号

使用被标记的常量时，PHP 会产生 E_USER_DEPRECATED 级别的提示。生产项目不要把它直接当成业务异常捕获；更稳妥的做法是让开发、测试和升级扫描阶段记录它，再根据调用位置逐步改成新常量。

这里的处理器只是说明迁移观察点。实际项目中，日志级别、去重策略和是否让提示继续冒泡，要按现有错误处理规范决定；不要为了“让日志变干净”而全局屏蔽 E_USER_DEPRECATED。

用 ReflectionConstant 盘点旧常量

PHP 8.4 已提供 ReflectionConstant，PHP 8.5 的常量属性能力让它更适合做全局常量迁移扫描。isDeprecated() 判断是否已标记弃用，getAttributes() 可以读取属性对象，getValue() 则读取当前值。

isDeprecated()) {
    // 只实例化目标属性，避免把无关属性混入迁移记录。
    $attributes = $reflection->getAttributes(Deprecated::class);
    $deprecated = $attributes[0]->newInstance();

    printf(
        "常量=%s，值=%s，since=%s，建议=%s\n",
        $reflection->getName(),
        (string) $reflection->getValue(),
        $deprecated->since ?? '未填写',
        $deprecated->message ?? '未填写'
    );
}

反射扫描的输出可以进入迁移清单，但它只回答“这个常量有没有弃用元数据”。它不能证明所有调用点已经被替换，也不能代替静态分析、测试和代码审查。

升级前后怎样安排兼容清单

如果项目还要支持 PHP 8.4 或更早版本，不要把带有 #[\Deprecated] 的声明直接下发到所有环境。可以把兼容工作拆成下面四项：

1. 声明门槛：先确认生产和 CI 的 PHP 版本，只有能解析该属性目标的环境才启用新声明。
2. 替代关系：为每个旧常量填写明确的替代常量，不要只写“请升级”。
3. 调用清单：通过弃用日志、代码搜索和测试覆盖收集旧常量调用点。
4. 删除时机：等调用方完成迁移后再删除旧常量，避免把“标记弃用”和“移除符号”放在同一次发布中。

还要注意 Deprecated 的作用是产生可读的迁移信号。它不是类型约束、权限控制，也不是配置值校验器；常量的值、作用域和业务语义仍然由原有代码负责。

常见问题

给常量加 Deprecated 后会自动使用新常量吗？

不会。它只提供弃用元数据并发出提示，替代关系需要由开发者在调用点完成。

可以用 ReflectionClassConstant 检查全局常量吗？

不可以。全局常量使用 ReflectionConstant；类常量才使用 ReflectionClassConstant。

没有填写 message 和 since 还能标记吗？

可以，两个参数都是可选的，但迁移信息会变得不完整。团队协作时建议至少写替代项和起始版本。

应该在生产环境屏蔽弃用提示吗？

不要用全局屏蔽代替迁移。生产日志可以按环境和采样策略降噪，但升级阶段仍应保留可追踪的提示来源。

总结

PHP 8.5 的关键变化是允许 Deprecated 作用于类外编译期常量。实际迁移可以遵循“声明中写替代建议、使用时记录提示、反射时生成清单、删除前分阶段”的顺序，把新语法变成可执行的兼容工作。