嘿，各位代码探险家们，欢迎来到今天的“WordPress考古学”讲座！今天我们要深挖的，是WordPress中一个默默守护着代码规范的小卫士——_doing_it_wrong()函数。别看名字长，它可是在你犯错的时候，第一个跳出来提醒你的家伙。
准备好了吗？让我们开始吧！
一、_doing_it_wrong()：你的代码警察
_doing_it_wrong()，顾名思义，就是“你做错了”的意思。这个函数的作用很简单，就是在你以不正确的方式使用WordPress的钩子（hooks）时，发出警告。但别小看这个警告，它能帮你及早发现代码中的潜在问题，避免将来出现更严重的bug。
想想看，你辛辛苦苦写的代码，结果因为一个小小的钩子使用错误，导致整个网站崩溃，那得多扎心啊！_doing_it_wrong()就像是一位经验丰富的代码审查员，在你提交代码之前，就帮你揪出这些小错误。
二、源码解剖：_doing_it_wrong() 的核心逻辑
好了，废话不多说，让我们直接钻进_doing_it_wrong()的源码，看看它到底是怎么工作的。
function _doing_it_wrong( $function, $message, $version ) {
/**
* Fires when a function is being used incorrectly.
*
* @since 3.1.0
*
* @param string $function The function that was called incorrectly.
* @param string $message A message explaining what went wrong.
* @param string $version The version of WordPress where the message was added.
*/
do_action( 'doing_it_wrong_run', $function, $message, $version );
$message .= sprintf( ' 请参阅 %s 获取更多信息。',
'https://developer.wordpress.org/reference/functions/' . str_replace( '_', '-', $function )
);
if ( WP_DEBUG && apply_filters( 'doing_it_wrong_trigger_error', true ) ) {
if ( function_exists( '__' ) ) {
$function_name = __($function, 'default');
$message = __($message, 'default');
} else {
$function_name = $function;
}
trigger_error( sprintf( '%s 函数使用不当。%s 版本中新增。%s',
$function_name,
$version,
$message
), E_USER_WARNING );
}
}乍一看，代码好像有点长，但实际上逻辑非常清晰：
-
触发
doing_it_wrong_run动作钩子：do_action( 'doing_it_wrong_run', $function, $message, $version );首先，它会触发一个名为
doing_it_wrong_run的动作钩子。这意味着你可以通过这个钩子，在_doing_it_wrong()被调用时执行一些自定义的操作。比如，你可以将错误信息记录到日志文件中，或者发送邮件通知管理员。这提供了一个扩展点，让你可以根据自己的需求，定制错误处理的方式。 -
添加文档链接：
$message .= sprintf( ' 请参阅 %s 获取更多信息。', 'https://developer.wordpress.org/reference/functions/' . str_replace( '_', '-', $function ) );这行代码非常贴心，它会在错误信息后面添加一个链接，指向WordPress开发者文档中关于该函数的说明页面。这样，当你看到错误信息时，就可以直接点击链接，了解函数的正确使用方法。这个链接的生成方式也很巧妙，它会将函数名中的下划线替换成短横线，从而生成正确的URL。
-
检查
WP_DEBUG和doing_it_wrong_trigger_error：if ( WP_DEBUG && apply_filters( 'doing_it_wrong_trigger_error', true ) ) { // ... }这段代码是整个函数的关键。它首先会检查
WP_DEBUG常量是否为真。WP_DEBUG是WordPress的调试模式开关，只有在开启调试模式时，才会显示错误信息。然后，它会通过
apply_filters()函数，应用一个名为doing_it_wrong_trigger_error的过滤器。这个过滤器允许你控制是否触发trigger_error()函数。默认情况下，这个过滤器返回true，也就是会触发trigger_error()函数。但是，你可以通过自定义插件或主题，将这个过滤器设置为false，从而禁用_doing_it_wrong()的错误提示。 -
国际化处理 (可选)：
if ( function_exists( '__' ) ) { $function_name = __($function, 'default'); $message = __($message, 'default'); } else { $function_name = $function; }如果你的WordPress安装了翻译支持，这段代码会尝试对函数名和错误信息进行国际化处理，以便用不同的语言显示。
-
触发
trigger_error()函数：trigger_error( sprintf( '%s 函数使用不当。%s 版本中新增。%s', $function_name, $version, $message ), E_USER_WARNING );最后，如果
WP_DEBUG为真，并且doing_it_wrong_trigger_error过滤器返回true，那么_doing_it_wrong()函数会调用trigger_error()函数，触发一个E_USER_WARNING级别的错误。这个错误信息会显示在WordPress的调试日志中，或者直接显示在网页上（如果开启了WP_DEBUG_DISPLAY）。
三、trigger_error()：错误信息的发射器
现在，让我们把目光聚焦到trigger_error()函数上。这个函数是PHP内置的，它的作用是触发一个用户级别的错误。_doing_it_wrong()函数正是利用trigger_error()，来发出警告信息。
trigger_error()函数的语法如下：
trigger_error(string $error_msg, int $error_type = E_USER_NOTICE): bool$error_msg：要显示的错误信息。$error_type：错误类型。常见的错误类型有：E_USER_ERROR：用户级别的致命错误。E_USER_WARNING：用户级别的警告错误。E_USER_NOTICE：用户级别的提示错误。E_USER_DEPRECATED：用户级别的废弃错误。
在_doing_it_wrong()函数中，我们看到trigger_error()的第二个参数被设置为E_USER_WARNING，这意味着它会触发一个用户级别的警告错误。
四、实战演练：模拟一个错误场景
光说不练假把式。现在，让我们来模拟一个错误场景，看看_doing_it_wrong()函数是如何工作的。
假设我们错误地使用了get_permalink()函数，没有传递文章ID作为参数。get_permalink()函数要求必须传递文章ID，否则会返回false。
<?php
// 错误的使用方式
$permalink = get_permalink();
if (WP_DEBUG) {
echo "Permalink: " . $permalink; // 输出 Permalink:
}
// 正确的使用方式，假设文章ID为 123
$permalink = get_permalink(123);
if (WP_DEBUG) {
echo "Permalink: " . $permalink; // 输出正确的链接
}
?>WordPress会检查这种用法，如果检测到错误，它会调用_doing_it_wrong()函数，发出警告。
以下是一个模拟_doing_it_wrong()被调用的场景，展示了错误信息：
<?php
// 模拟 _doing_it_wrong 函数的调用
_doing_it_wrong(
'get_permalink',
'没有传递文章ID作为参数。',
'3.0'
);
?>如果你开启了WP_DEBUG，你会在页面上看到类似这样的错误信息：
get_permalink 函数使用不当。3.0 版本中新增。没有传递文章ID作为参数。 请参阅 https://developer.wordpress.org/reference/functions/get-permalink/ 获取更多信息。这个错误信息非常清晰地告诉你：
- 哪个函数被错误使用了（
get_permalink）。 - 错误的原因是什么（没有传递文章ID作为参数）。
- 哪个版本的WordPress引入了这个错误提示（
3.0）。 - 在哪里可以找到更多信息（WordPress开发者文档）。
五、常见错误场景：_doing_it_wrong() 的用武之地
_doing_it_wrong()函数通常会在以下几种情况下被调用：
-
废弃的函数： 当你使用了一个已经被废弃的函数时，WordPress会调用
_doing_it_wrong()函数，发出警告。_deprecated_function( 'old_function', '3.0', 'new_function' ); -
不正确的参数： 当你传递给一个函数的参数类型或数量不正确时，WordPress会调用
_doing_it_wrong()函数，发出警告。例如，get_permalink()函数缺少文章ID参数的情况。 -
不推荐的使用方式： 当你使用了一个不推荐的使用方式时，WordPress会调用
_doing_it_wrong()函数，发出警告。例如，直接访问全局变量而不是使用函数。 -
不兼容的用法： 当你使用的函数或方法与当前版本的WordPress不兼容时，WordPress会调用
_doing_it_wrong()函数，发出警告。
六、如何避免触发 _doing_it_wrong()
避免触发_doing_it_wrong()的最好方法，就是遵循WordPress的编码规范，仔细阅读官方文档，确保你正确地使用了每一个函数和钩子。
以下是一些建议：
- 阅读文档： 在使用任何函数之前，先阅读WordPress开发者文档，了解函数的参数、返回值和使用方法。
- 使用IDE： 使用支持WordPress代码提示的IDE，可以帮助你避免一些常见的错误。
- 开启
WP_DEBUG： 在开发环境中，始终开启WP_DEBUG，以便及时发现错误。 - Code Review： 定期进行代码审查，让其他开发者帮助你找出潜在的问题。
- 单元测试： 为你的代码编写单元测试，可以帮助你验证代码的正确性。
七、自定义 doing_it_wrong_trigger_error 过滤器
如果你想禁用_doing_it_wrong()的错误提示，你可以通过自定义doing_it_wrong_trigger_error过滤器来实现。
例如，你可以在你的主题的functions.php文件中，添加以下代码：
<?php
add_filter( 'doing_it_wrong_trigger_error', '__return_false' );
?>这段代码会将doing_it_wrong_trigger_error过滤器设置为false，从而禁用_doing_it_wrong()的错误提示。
请注意，禁用_doing_it_wrong()的错误提示可能会隐藏一些潜在的问题，因此不建议在生产环境中使用。
八、_doing_it_wrong() 与 _deprecated_function() 的区别
你可能会好奇，_doing_it_wrong()和_deprecated_function()这两个函数有什么区别呢？
简单来说，_doing_it_wrong()用于提示函数使用方式不正确，而_deprecated_function()用于提示函数已经被废弃。
| 函数名 | 作用 | 触发条件 |
|---|---|---|
_doing_it_wrong() |
提示函数使用方式不正确 | 函数使用方式不符合规范，例如缺少参数、参数类型错误等。 |
_deprecated_function() |
提示函数已经被废弃 | 使用了已经被标记为废弃的函数。 |
九、总结：_doing_it_wrong() 的价值
_doing_it_wrong()函数是WordPress代码库中一个非常重要的组成部分。它通过发出警告，帮助开发者避免一些常见的错误，从而提高代码质量和网站的稳定性。
虽然_doing_it_wrong()函数只是一个简单的函数，但它体现了WordPress对代码质量的重视，以及对开发者友好的态度。它就像一位默默守护着代码规范的小卫士，在你犯错的时候，及时地提醒你。
希望今天的讲座能让你对_doing_it_wrong()函数有更深入的了解。记住，写代码就像盖房子，基础一定要打牢。_doing_it_wrong()就是帮你检查地基是否稳固的工具。
下次再见！祝大家代码无bug！