深入理解 `_doing_it_wrong()` 和 `_deprecated_function()` 函数的源码，它们如何利用 `trigger_error` 来向开发者发出警告？

好吧，各位观众，欢迎来到今天的“代码考古学”讲座！今天我们要挖掘的主题是两个听起来有点“别扭”的函数：_doing_it_wrong() 和 _deprecated_function()。别害怕，它们的名字虽然自带嘲讽属性，但实际上是开发者工具箱里的好帮手，能帮助我们维护代码质量，避免掉进坑里。

我们今天的目标是：

搞清楚这两个函数的作用：它们是干嘛的？
深入源码，看看它们是如何利用 trigger_error 发出警告的。
了解 trigger_error 的工作原理，以及它对代码调试和维护的重要性。
探讨如何在实际项目中正确地使用它们，写出更健壮、更易维护的代码。

准备好了吗？让我们开始吧！

一、_doing_it_wrong()：当你“走错路”时的警钟

首先，我们来看看 _doing_it_wrong()。从名字就能猜到，它主要用于提示开发者“你可能用错了姿势”。它的核心作用是：当开发者以不推荐的方式使用某个函数、类或方法时，发出警告。

1. 应用场景举例

假设我们有一个名为 calculate_discount() 的函数，原本接收两个参数：商品原价和折扣百分比。后来，为了支持更复杂的折扣策略，我们修改了这个函数，允许它接收一个包含折扣规则的数组。

但是，为了兼容旧代码，我们仍然允许 calculate_discount() 接收两个参数，但同时使用 _doing_it_wrong() 发出警告，提示开发者应该使用新的参数格式。

2. 简化版源码示例

<?php

/**
 * 计算折扣价格
 *
 * @param float|array $price 商品原价或包含折扣规则的数组
 * @param float|null $discountPercentage 折扣百分比（可选，当 $price 为数组时忽略）
 *
 * @return float 折扣后的价格
 */
function calculate_discount($price, $discountPercentage = null) {
  if (is_array($price)) {
    // 使用新的折扣规则
    $discountedPrice = $price['original_price'] * (1 - $price['discount_rate']);
    return $discountedPrice;
  } elseif (is_numeric($price) && is_numeric($discountPercentage)) {
    // 使用旧的参数格式，发出警告
    _doing_it_wrong(
      'calculate_discount',
      '建议使用包含折扣规则的数组作为参数，而不是原价和折扣百分比。',
      '1.0.0' // 哪个版本开始建议更换
    );

    $discountedPrice = $price * (1 - $discountPercentage);
    return $discountedPrice;
  } else {
    throw new InvalidArgumentException('参数类型不正确');
  }
}

/**
 * 提示开发者“你可能用错了姿势”
 *
 * @param string $function 函数名
 * @param string $message  警告信息
 * @param string $version  哪个版本开始出现这个错误
 */
function _doing_it_wrong( $function, $message, $version ) {
  $message = sprintf( '%1$s 函数使用方式不正确。%2$s 版本: %3$s',
    $function,
    $message,
    $version
  );

  if ( defined( 'WP_DEBUG' ) && WP_DEBUG ) {
    trigger_error( $message, E_USER_WARNING );
  }
}

// 旧的调用方式，会触发警告
$finalPrice = calculate_discount(100, 0.2); // 商品原价100，折扣20%

// 新的调用方式，不会触发警告
$finalPrice = calculate_discount(['original_price' => 100, 'discount_rate' => 0.2]);

?>

3. 源码解读

calculate_discount() 函数首先检查传入的参数类型。如果第一个参数是数组，则认为使用了新的参数格式，直接进行计算。
如果第一个参数是数字，且第二个参数也是数字，则认为使用了旧的参数格式。
在这种情况下，calculate_discount() 函数会调用 _doing_it_wrong()，并传入函数名、警告信息和版本号。
_doing_it_wrong() 函数将传入的信息格式化成一条更友好的警告消息。
关键点： _doing_it_wrong() 函数会检查 WP_DEBUG 常量是否定义且为真。只有在调试模式下，才会调用 trigger_error() 函数发出警告。这意味着在生产环境中，这些警告不会显示给用户，只会在开发者调试时才会出现。
trigger_error() 函数接收两个参数：错误消息和错误类型。在这里，我们使用 E_USER_WARNING 作为错误类型，表示这是一个用户级别的警告。

二、_deprecated_function()：告诉你“这个函数过时了”

接下来，我们看看 _deprecated_function()。顾名思义，它的作用是标记某个函数、类或方法已经过时，不建议再使用。

1. 应用场景举例

假设我们有一个名为 old_function() 的函数，由于某些原因（例如性能问题、安全性问题或功能被更好的替代方案取代），我们决定不再使用它。

我们可以创建一个新的函数 new_function() 来替代 old_function()，并在 old_function() 中使用 _deprecated_function() 发出警告，提示开发者应该使用 new_function()。

2. 简化版源码示例

<?php

/**
 * 这是一个过时的函数，不建议使用
 *
 * @deprecated 1.0.0  请使用 new_function() 函数替代
 */
function old_function() {
  _deprecated_function( 'old_function', '1.0.0', 'new_function' );
  // ...  旧函数原本的逻辑
  echo "This is the old function.n";
}

/**
 * 替代 old_function() 的新函数
 */
function new_function() {
  echo "This is the new function.n";
}

/**
 * 标记某个函数已经过时
 *
 * @param string $function     函数名
 * @param string $version      哪个版本开始过时
 * @param string $replacement  替代函数（可选）
 */
function _deprecated_function( $function, $version, $replacement = null ) {
  if ( ! function_exists( '_deprecated_hook' ) ) {
    $message = sprintf( '%1$s 函数已过时。', $function );
    if ( ! is_null( $replacement ) ) {
      $message .= sprintf( '请使用 %2$s 替代。', $replacement );
    }
    $message .= sprintf( '版本: %3$s', $version );

    if ( defined( 'WP_DEBUG' ) && WP_DEBUG ) {
      trigger_error( $message, E_USER_DEPRECATED );
    }
  } else {
    _deprecated_hook( $function, $version, $replacement ); //这里是为了兼容钩子函数
  }
}

// 调用过时函数，会触发警告
old_function();

// 应该使用新函数
new_function();

?>

3. 源码解读

old_function() 函数调用 _deprecated_function()，并传入函数名、版本号和替代函数名。
_deprecated_function() 函数将传入的信息格式化成一条警告消息，提示开发者该函数已经过时，并建议使用替代函数。
关键点： 同样，_deprecated_function() 函数也会检查 WP_DEBUG 常量。只有在调试模式下，才会调用 trigger_error() 函数发出警告。
trigger_error() 函数在这里使用了 E_USER_DEPRECATED 作为错误类型，表示这是一个用户级别的“已弃用”警告。
注意，上面的代码中还判断_deprecated_hook是否存在，这是为了兼容Wordpress中的钩子函数。如果存在，则执行_deprecated_hook函数。这个函数我们就不深入研究了。

三、trigger_error()：发出警告的“喇叭”

现在，让我们深入了解一下 trigger_error() 函数。它才是真正发出警告的“喇叭”。

1. 函数原型

trigger_error ( string $error_msg [, int $error_type = E_USER_NOTICE ] ) : bool

error_msg：错误消息，也就是要显示的警告内容。
error_type：错误类型，决定了警告的严重程度。

2. 常见的错误类型

错误类型	描述
`E_USER_ERROR`	用户级别的错误。会导致脚本终止。
`E_USER_WARNING`	用户级别的警告。不会导致脚本终止。
`E_USER_NOTICE`	用户级别的注意。是最轻微的警告，通常用于提示一些潜在的问题。
`E_DEPRECATED`	表示使用了已弃用的特性。
`E_USER_DEPRECATED`	用户级别的已弃用警告。
`E_NOTICE`	运行时通知。表明代码可能存在问题，但不一定导致错误。
`E_WARNING`	运行时警告。比通知更严重，表明代码可能无法正常工作。
`E_ERROR`	致命的运行时错误。会导致脚本终止。

3. 如何处理 trigger_error() 发出的警告

默认情况下，trigger_error() 发出的警告会直接显示在页面上（如果在调试模式下）。但是，我们可以通过 set_error_handler() 函数来定义自己的错误处理函数，拦截这些警告，并进行自定义处理。

示例

<?php

// 自定义错误处理函数
function myErrorHandler($errno, $errstr, $errfile, $errline) {
  switch ($errno) {
    case E_USER_ERROR:
      echo "<b>我的错误</b> [$errno] $errstr<br>n";
      echo "  在第 $errline 行的 $errfile 中<br>n";
      echo "程序终止<br>n";
      exit(1);
      break;

    case E_USER_WARNING:
      echo "<b>我的警告</b> [$errno] $errstr<br>n";
      echo "  在第 $errline 行的 $errfile 中<br>n";
      break;

    case E_USER_NOTICE:
      echo "<b>我的注意</b> [$errno] $errstr<br>n";
      echo "  在第 $errline 行的 $errfile 中<br>n";
      break;

    default:
      echo "未知错误类型: [$errno] $errstr<br>n";
      echo "  在第 $errline 行的 $errfile 中<br>n";
      break;
  }

  /* 不要执行 PHP 内置的错误处理程序 */
  return true;
}

// 设置自定义错误处理函数
set_error_handler("myErrorHandler");

// 触发一个用户级别的警告
trigger_error("这是一个自定义警告", E_USER_WARNING);

// 触发一个用户级别的错误
trigger_error("这是一个自定义错误", E_USER_ERROR);

?>

四、如何在实际项目中使用 _doing_it_wrong() 和 _deprecated_function()

1. 逐步升级代码

当我们重构代码时，经常需要修改函数或类的接口。为了保证向后兼容性，我们可以先保留旧的接口，并使用 _doing_it_wrong() 提示开发者使用新的接口。

在后续的版本中，可以逐步移除对旧接口的支持，最终完全切换到新的接口。

2. 标记过时功能

当我们决定不再支持某个功能时，可以使用 _deprecated_function() 标记相关的函数或类。

这可以帮助开发者了解哪些功能已经过时，并及时迁移到新的替代方案。

3. 提供清晰的迁移指南

除了发出警告之外，我们还应该提供清晰的迁移指南，帮助开发者了解如何从旧的接口或功能迁移到新的接口或功能。

这可以减少开发者的迁移成本，提高代码的维护效率。

4. 只在调试模式下发出警告

正如我们前面提到的，_doing_it_wrong() 和 _deprecated_function() 函数通常只在调试模式下发出警告。

这可以避免在生产环境中显示不必要的警告信息，影响用户体验。

五、总结

_doing_it_wrong() 和 _deprecated_function() 函数是强大的代码维护工具，可以帮助我们逐步升级代码、标记过时功能，并提供清晰的迁移指南。

通过合理地使用这两个函数，我们可以提高代码的健壮性和可维护性，避免掉进坑里。

记住，代码维护就像考古一样，需要耐心和细致。希望今天的讲座能帮助你更好地理解这两个函数，并在你的代码考古之旅中有所收获！

六、一些补充说明

在实际项目中，你可能需要根据具体情况修改 _doing_it_wrong() 和 _deprecated_function() 函数的实现。例如，你可以添加更多的参数，或者修改警告信息的格式。
除了 trigger_error() 函数之外，你还可以使用其他的日志记录工具来记录警告信息。例如，你可以将警告信息写入日志文件，或者发送到监控系统。
在编写代码时，要始终保持代码的清晰性和可读性。这可以帮助你更容易地发现和修复问题。

希望这次的讲解对你有所帮助！下次再见！

发表回复 取消回复

发表回复取消回复