当前位置:首页 > 文章列表 > 文章 > php教程 > PHP 8.4 #[Deprecated] 怎样标记待移除 API

PHP 8.4 #[Deprecated] 怎样标记待移除 API

来源:17golang原创 2026-11-20 10:14:38 0浏览 收藏

PHP 8.4 可以在函数、方法或类常量声明前使用 #[\Deprecated] 标记弃用,并通过 message 写明替代方案,通过 since 标明从哪个库版本开始弃用。使用被标记的用户态功能会产生 E_USER_DEPRECATED 诊断;这个标记不负责自动删除或禁用 API。

官方地址:https://www.php.net/

先区分弃用提醒与禁止调用

整理一个旧库接口时,我会先问:现在需要的是提醒迁移,还是立即停止旧行为?这两件事需要不同措施。下面以虚构的运费计算接口为例,重点是让旧调用可发现,同时给调用方明确的新入口;不代表实际运行记录。

从风险角度看,要保护的是兼容性和迁移信息。如果某个旧接口必须立即停止提供敏感能力,应单独修改业务实现或访问控制,不能依赖弃用提醒来阻止调用。这里的 Deprecated 是迁移信号。

在旧函数上提供替代入口

以下为 PHP 8.4 及以上环境中的最小示例。旧函数保留委托,新函数承接计算与参数检查;属性中的信息只用于解释迁移方向。

默认错误处理下,调用旧入口会产生弃用诊断,函数仍可继续返回。示例计算值为 18;完整诊断中的文件、行号和格式取决于执行环境。若应用错误处理器主动抛出异常,程序也可能在进入函数体前中断,应把这种应用策略与属性自身行为分开。

弃用属性旧函数替代函数与迁移信息的静态关系
图1:声明关系结构图;属性绑定旧函数,message 指向替代入口,since 描述库的弃用起点。

把 since 当作库的迁移说明

构造参数 message 和 since 都是可空字符串,默认值为 null。message 适合说明替代 API 或弃用原因;since 可以填写项目版本、日期等文本,PHP 不会校验其内容。

示例的 since: '3.2' 表示这个示例库从 3.2 开始弃用旧入口,不是要求 PHP 3.2,也不是运行时倒计时。实际移除时间应另写在库的迁移文档和发布说明里,不要让调用方靠猜测理解版本含义。

限定 PHP 8.4 支持的声明目标

声明对象PHP 8.4 中的本文范围
函数支持弃用标记
方法支持弃用标记
类常量支持弃用标记
trait、类外编译期常量不要套用后续版本能力到 8.4

当前手册记录了 PHP 8.5 对 trait 和类外编译期常量的扩展。因此,维护一个明确支持 PHP 8.4 的库时,应根据最低运行环境选择声明目标。普通类与属性也不能因为名字相近就随意套用这个属性。

用错误处理记录旧调用

可以在受控测试或迁移统计中接管 E_USER_DEPRECATED,把旧调用整理为内部记录。以下片段与前面的函数定义配合使用,不是独立文件;它没有调用外部接口,也不更改全局错误级别。

错误处理器返回 true 表示本次诊断已处理,finally 则负责恢复处理器。这个写法适用于局部示例;在框架已有统一错误处理时,应接入原有机制,避免覆盖后影响其他模块。诊断文本可能包含内部路径,不宜直接显示给终端用户。

用户态弃用诊断与局部错误处理记录的静态关系
图2:诊断职责结构图;E_USER_DEPRECATED、记录容器与处理器恢复各有独立作用,不是执行截图。

移除 API 前还要处理哪些问题

对调用方,最有价值的提醒通常包含替代入口、参数差异和计划移除的版本。对维护方,可以关注旧入口仍被哪些业务使用、替代接口是否保持所需语义,以及移除后有没有恢复策略。这里列出的是迁移工作建议,属性不会自动完成这些事项。

写了 since 会在指定版本自动移除吗?不会。它只是说明文本。

弃用标记等于访问限制吗?不等于。访问控制与业务禁用需要单独实现。

为什么要写成 \Deprecated?全限定类名能避免在命名空间内解析到同名的自定义属性。

官方属性说明:https://www.php.net/manual/en/class.deprecated.php

PHP 8.4 设计背景:https://wiki.php.net/rfc/deprecated_attribute

错误处理说明:https://www.php.net/manual/en/function.set-error-handler.php

版本声明
本文转载于:17golang原创 如有侵犯,请联系study_golang@163.com删除
Kubernetes Gateway API HTTPRoute 怎样用 parentRefs 绑定 GatewayKubernetes Gateway API HTTPRoute 怎样用 parentRefs 绑定 Gateway
上一篇
Kubernetes Gateway API HTTPRoute 怎样用 parentRefs 绑定 Gateway
PHP 8.4 Property Hooks 怎样避免重复访问器代码
下一篇
PHP 8.4 Property Hooks 怎样避免重复访问器代码
查看更多
最新文章
查看更多
课程推荐
  • 前端进阶之JavaScript设计模式
    前端进阶之JavaScript设计模式
    设计模式是开发人员在软件开发过程中面临一般问题时的解决方案,代表了最佳的实践。本课程的主打内容包括JS常见设计模式以及具体应用场景,打造一站式知识长龙服务,适合有JS基础的同学学习。
    543次学习
  • GO语言核心编程课程
    GO语言核心编程课程
    本课程采用真实案例,全面具体可落地,从理论到实践,一步一步将GO核心编程技术、编程思想、底层实现融会贯通,使学习者贴近时代脉搏,做IT互联网时代的弄潮儿。
    516次学习
  • 简单聊聊mysql8与网络通信
    简单聊聊mysql8与网络通信
    如有问题加微信:Le-studyg;在课程中,我们将首先介绍MySQL8的新特性,包括性能优化、安全增强、新数据类型等,帮助学生快速熟悉MySQL8的最新功能。接着,我们将深入解析MySQL的网络通信机制,包括协议、连接管理、数据传输等,让
    500次学习
  • JavaScript正则表达式基础与实战
    JavaScript正则表达式基础与实战
    在任何一门编程语言中,正则表达式,都是一项重要的知识,它提供了高效的字符串匹配与捕获机制,可以极大的简化程序设计。
    487次学习
  • 从零制作响应式网站—Grid布局
    从零制作响应式网站—Grid布局
    本系列教程将展示从零制作一个假想的网络科技公司官网,分为导航,轮播,关于我们,成功案例,服务流程,团队介绍,数据部分,公司动态,底部信息等内容区块。网站整体采用CSSGrid布局,支持响应式,有流畅过渡和展现动画。
    485次学习
查看更多
AI推荐
  • PubMedQA数据集详解:生物医学问答基准、功能与应用指南
    PubMedQA
    深入了解PubMedQA生物医学问答数据集,涵盖其核心功能、使用方法及在临床决策、药物研发等场景的应用,助力提升NLP模型性能。
    1140次使用
  • H2O EvalGPT:开源LLM大模型评估与排行榜工具
    H2O EvalGPT
    H2O EvalGPT是H2O.ai推出的开源LLM评估平台,提供详细的大模型性能排行榜、行业特定基准测试及A/B测试功能,助您快速选择最适合项目的高性能大语言模型。
    1124次使用
  • LMArena是什么?伯克利AI模型评估平台使用指南与功能解析
    LMArena
    LMArena是加州大学伯克利分校推出的AI模型匿名评测平台。通过盲测投票机制,用户可对比不同大模型回答并生成实时排行榜,助力开发者优化模型及用户选择最佳AI工具。
    1300次使用
  • 斯坦福HELM:大语言模型Holistic Evaluation整体评估框架详解
    HELM
    深入了解斯坦福推出的HELM(Holistic Evaluation of Language Models)大模型评测体系。本文解析其核心功能、安装配置步骤及应用场景,涵盖准确性、公平性、鲁棒性等多维度指标,助力开发者全面优化语言模型性能。
    1238次使用
  • MMBench详解:多模态大模型基准测试、功能特点与使用指南
    MMBench
    MMBench是由上海人工智能实验室等机构联合推出的多模态基准测试平台,提供细粒度能力评估、大规模数据集及VLMEvalKit工具。本文详细介绍其核心功能、安装使用方法及应用场景,助力开发者全面评估多模态模型性能。
    1091次使用
微信登录更方便
  • 密码登录
  • 注册账号
登录即同意 用户协议 和 隐私政策
返回登录
  • 重置密码