PHP 怎么PHP 弃用

本文目录导读：

1. 使用 trigger_error() 手动触发弃用通知（最常用）
2. 使用 错误抑制符（不推荐用于弃用标记）
3. 结合 error_reporting 控制显示
4. 在 PHPDoc 中标记弃用（文档提示 + 静态分析工具）
5. 使用 #[Deprecated] 属性（PHP 8.4+）
6. 总结对比

在 PHP 中，弃用（Deprecation） 是指某个功能、函数或特性虽然仍然可用，但官方不再推荐使用，并会在未来的大版本中被移除，当你使用已弃用的代码时，PHP 会抛出一个 E_DEPRECATED 或 E_USER_DEPRECATED 级别的警告。

如果你希望主动让 PHP 代码抛出一个弃用通知（比如标记你自己的旧接口或函数已过时）,可以使用以下几种方法：

---

使用 trigger_error() 手动触发弃用通知（最常用）

function oldFunction() {
    trigger_error('oldFunction() 已弃用，请使用 newFunction() 替代', E_USER_DEPRECATED);
    // 原有逻辑
}
// 调用时：
oldFunction();  // 输出: PHP Deprecated:  oldFunction() 已弃用...

• E_USER_DEPRECATED 是用户级弃用错误常量，不会中断脚本执行,但会在日志或标准输出中显示。

---

使用 错误抑制符（不推荐用于弃用标记）

@oldFunction(); // 会抑制所有错误，包括弃用通知

但这样会隐藏该函数内部的所有错误，不符合最佳实践,仅用于临时跳过。

---

结合 error_reporting 控制显示

如果你希望在生产环境中隐藏弃用通知,可以在代码中调整错误报告级别：

// 隐藏所有弃用通知
error_reporting(E_ALL & ~E_DEPRECATED & ~E_USER_DEPRECATED);

或者仅在开发环境显示：

if (defined('ENVIRONMENT') && ENVIRONMENT === 'development') {
    error_reporting(E_ALL);
} else {
    error_reporting(E_ALL & ~E_DEPRECATED & ~E_USER_DEPRECATED);
}

---

在 PHPDoc 中标记弃用（文档提示 + 静态分析工具）

/**
 * @deprecated 从 2.0 版本起弃用，请使用 newFunction() 替代
 * @see newFunction()
 */
function oldFunction() {
    // ...
}

• 这纯属文档标注，不会主动触发运行时错误，但像 PhpStorm、PHPStan、Psalm 等工具会在代码分析时给出警告。

---

使用 #[Deprecated] 属性（PHP 8.4+）

从 PHP 8.4 开始，官方提供了内置的 #[Deprecated] 属性,用于更优雅地标记弃用：

use Deprecated;
#[Deprecated('since 3.0, use newFunction instead', 'newFunction')]
function oldFunction() {
    // ...
}

• 调用时会自动触发 E_USER_DEPRECATED 通知。
• 第二个参数 newFunction 是可选的替代函数名，IDE 会利用它提供自动修复提示。

---

总结对比

方法	触发运行时错误？	适用于	PHP 版本要求
trigger_error()	所有 PHP 版本	任何版本
PHPDoc @deprecated	静态分析 / IDE 提示	任何版本
#[Deprecated] 属性	代码即文档	PHP 8.4+

推荐做法：

• 如果你仍在使用旧版本 PHP（< 8.4），使用 trigger_error() + @deprecated 文档注释。
• 如果已升级到 PHP 8.4+，优先使用 #[Deprecated] 属性，更现代且 IDE 支持更好。

---

如果你是想处理 PHP 内置的弃用（比如老函数被弃用）,通常的做法是：

• 升级代码，使用替代函数（mysql_* → mysqli_* 或 PDO）。
• 在升级完成前，通过 error_reporting 临时屏蔽弃用通知。