深入研究 _doing_it_wrong 函数的内部调试机制

深入研究 _doing_it_wrong 函数的内部调试机制

今天我们来深入探讨 WordPress 核心代码中一个经常被忽视但非常重要的函数：_doing_it_wrong。 它的主要作用是在开发者使用了过时、不推荐或者错误的方式使用 WordPress API 时，发出警告通知。 这对于维护代码质量，避免潜在问题，以及促进最佳实践至关重要。

_doing_it_wrong 的基本结构和功能

_doing_it_wrong 函数的定义如下（基于 WordPress 最新版本）：

function _doing_it_wrong( $function, $message, $version ) {
    /**
     * Fires when a function is being called in a way that is incorrect.
     *
     * @since 3.1.0
     *
     * @param string $function The function that was called.
     * @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 );

    $deprecated_message = sprintf(
        /* translators: 1: Function name, 2: Message explaining the problem, 3: Version number. */
        __( '%1$s was called incorrectly. %2$s. Please see <a href="%3$s">Debugging in WordPress</a> for more information.' ),
        $function,
        $message,
        'https://wordpress.org/documentation/article/debugging-in-wordpress/'
    );

    if ( WP_DEBUG && apply_filters( 'doing_it_wrong_trigger_error', true ) ) {
        if ( WP_DEBUG_LOG ) {
            error_log( $deprecated_message );
        }

        /* translators: %s: Deprecated message. */
        trigger_error( sprintf( __('%s'), $deprecated_message ), E_USER_NOTICE );
    }
}

让我们逐行分解这个函数：

1. do_action( 'doing_it_wrong_run', $function, $message, $version );

   • 这是一个 WordPress action hook。它允许开发者监听 _doing_it_wrong 函数的执行，并执行自定义代码。 例如，你可以记录所有 _doing_it_wrong 的调用到数据库，或者发送邮件通知。
   • $function：被错误调用的函数名。
   • $message：解释错误原因的消息。
   • $version：引入警告信息的 WordPress 版本。

2. $deprecated_message = sprintf(...);

   • 这一行构建了最终显示的错误消息。 它使用 sprintf 函数和 __() 函数进行本地化和格式化。
   • 消息内容包括：
     • 函数名 ($function)
     • 解释问题的信息 ($message)
     • 一个指向 WordPress 调试文档的链接。

3. if ( WP_DEBUG && apply_filters( 'doing_it_wrong_trigger_error', true ) ) { ... }

   • 这是一个条件判断。 _doing_it_wrong 函数的行为取决于 WP_DEBUG 常量和 doing_it_wrong_trigger_error 过滤器。
   • WP_DEBUG：如果 WP_DEBUG 为 true（通常在开发环境中设置），则会触发错误。
   • apply_filters( 'doing_it_wrong_trigger_error', true )：这个过滤器允许开发者控制是否实际触发 PHP 错误。 默认情况下，它返回 true，表示会触发错误。 如果你想阻止 _doing_it_wrong 触发错误，你可以使用这个过滤器。

4. if ( WP_DEBUG_LOG ) { error_log( $deprecated_message ); }

   • 如果 WP_DEBUG_LOG 为 true，错误消息会被记录到 wp-content/debug.log 文件中。 这对于在生产环境中调试问题非常有用，因为你不会在页面上看到错误信息，而是可以稍后查看日志文件。

5. trigger_error( sprintf( __('%s'), $deprecated_message ), E_USER_NOTICE );

   • 这是核心部分。 trigger_error 函数会触发一个 PHP 错误。
   • E_USER_NOTICE：这是一个错误级别。 它表示这是一个用户级别的通知。 错误信息将显示在页面上（如果 WP_DEBUG 为 true 并且错误显示已启用）。

使用示例

以下是一些 _doing_it_wrong 函数的使用示例：

1. 使用过时的函数参数:

function my_deprecated_function( $arg1, $arg2, $deprecated_arg = null ) {
    if ( ! is_null( $deprecated_arg ) ) {
        _doing_it_wrong(
            'my_deprecated_function',
            'The `$deprecated_arg` argument is deprecated and will be removed in a future version.',
            '5.8'
        );
    }

    // ... 函数逻辑 ...
}

在这个例子中，如果 my_deprecated_function 函数的第三个参数被使用，_doing_it_wrong 函数会被调用，警告开发者该参数已被弃用。

2. 不推荐使用的操作：

function my_plugin_function() {
    if ( ! defined( 'DOING_AJAX' ) || ! DOING_AJAX ) {
        _doing_it_wrong(
            'my_plugin_function',
            'This function should only be called during AJAX requests.',
            '6.0'
        );
    }

    // ... 函数逻辑 ...
}

这个例子说明了函数 my_plugin_function 只能在 AJAX 请求期间被调用。 如果在其他地方调用，_doing_it_wrong 函数会发出警告。

3. 错误使用 API:

function my_theme_function( $post_id ) {
    if ( ! is_numeric( $post_id ) ) {
        _doing_it_wrong(
            'my_theme_function',
            'The `$post_id` argument must be an integer.',
            '6.1'
        );
        return; // 重要：阻止函数继续执行，避免潜在问题。
    }

    // ... 函数逻辑 ...
}

这里，my_theme_function 函数期望 $post_id 参数是一个整数。 如果传入的不是整数，_doing_it_wrong 函数会被调用，并且函数会立即返回。

_doing_it_wrong 的作用和重要性

_doing_it_wrong 函数在 WordPress 开发中扮演着重要的角色：

• 提高代码质量： 通过警告开发者使用过时或错误的方法，_doing_it_wrong 函数鼓励开发者编写更健壮、更符合最佳实践的代码。
• 减少潜在问题： 尽早发现问题可以避免将来出现更严重的错误。
• 促进最佳实践： _doing_it_wrong 函数可以引导开发者使用推荐的方法，并了解最新的 API。
• 简化调试： 当出现错误时，_doing_it_wrong 函数提供的错误信息可以帮助开发者快速定位问题。
• 平滑升级体验： 当 WordPress 版本更新时，_doing_it_wrong 函数可以帮助开发者识别需要更新的代码，以确保他们的插件和主题与新版本兼容。

如何处理 _doing_it_wrong 警告

当你在开发环境中看到 _doing_it_wrong 警告时，你应该采取以下步骤：

1. 阅读错误信息： 错误信息会告诉你哪个函数被错误调用，以及错误的原因。
2. 查找替代方案： 根据错误信息，查找推荐的替代方案。WordPress 文档通常会提供相关信息。
3. 更新你的代码： 使用替代方案替换过时或错误的代码。
4. 测试你的代码： 确保你的代码在更新后仍然正常工作。
5. 查看 WordPress 调试文档： 错误信息通常会包含一个指向 WordPress 调试文档的链接，其中包含更多信息和帮助。

使用 doing_it_wrong_run Action Hook 进行自定义处理

doing_it_wrong_run action hook 允许你自定义 _doing_it_wrong 函数的行为。 你可以使用它来：

• 记录所有 _doing_it_wrong 的调用到数据库。
• 发送邮件通知。
• 在页面上显示自定义错误信息。
• 阻止 _doing_it_wrong 触发 PHP 错误（虽然不推荐）。

以下是一个使用 doing_it_wrong_run action hook 的示例：

add_action( 'doing_it_wrong_run', 'my_custom_doing_it_wrong_handler', 10, 3 );

function my_custom_doing_it_wrong_handler( $function, $message, $version ) {
    // 记录到数据库
    global $wpdb;
    $wpdb->insert(
        'wp_doing_it_wrong_log',
        array(
            'function' => $function,
            'message'  => $message,
            'version'  => $version,
            'timestamp' => current_time( 'mysql' ),
        )
    );

    // 发送邮件通知 (仅在特定条件下)
    if ( defined( 'MY_PLUGIN_SEND_EMAIL_ON_DOING_IT_WRONG' ) && MY_PLUGIN_SEND_EMAIL_ON_DOING_IT_WRONG ) {
        wp_mail(
            '[email protected]',
            'Doing It Wrong Alert',
            sprintf(
                'Function: %snMessage: %snVersion: %s',
                $function,
                $message,
                $version
            )
        );
    }

    //  阻止触发错误 (不推荐，仅用于特殊情况)
    // remove_filter( 'doing_it_wrong_trigger_error', '__return_true' ); // 移除默认的过滤器，导致触发错误
}

这个例子展示了如何使用 doing_it_wrong_run action hook 将 _doing_it_wrong 的调用记录到数据库，并发送邮件通知。 同时代码中也展示了如何移除默认的 doing_it_wrong_trigger_error 过滤器，这将阻止 _doing_it_wrong 函数触发 PHP 错误。 注意：通常不建议这样做，除非你有充分的理由。

如何修改是否触发错误

你可以使用 doing_it_wrong_trigger_error 过滤器来控制是否触发 PHP 错误。 默认情况下，这个过滤器返回 true，表示会触发错误。 如果你想阻止 _doing_it_wrong 触发错误，你可以使用这个过滤器返回 false。

add_filter( 'doing_it_wrong_trigger_error', '__return_false' ); // 永远不触发错误

或者，你可以根据某些条件来决定是否触发错误：

add_filter( 'doing_it_wrong_trigger_error', 'my_custom_doing_it_wrong_trigger_error' );

function my_custom_doing_it_wrong_trigger_error() {
    if ( defined( 'MY_PLUGIN_SUPPRESS_DOING_IT_WRONG' ) && MY_PLUGIN_SUPPRESS_DOING_IT_WRONG ) {
        return false; // 阻止触发错误
    } else {
        return true; // 默认触发错误
    }
}

与其他调试函数的比较： _deprecated_function 和 _deprecated_argument

WordPress 提供了其他类似的调试函数，如 _deprecated_function 和 _deprecated_argument。 了解它们之间的区别很重要。

函数	描述	适用场景
_doing_it_wrong	用于标记函数被错误地调用，即使该函数本身没有被弃用。	函数被错误地使用，例如，在错误的上下文中调用，或者传递了无效的参数。
_deprecated_function	用于标记整个函数已被弃用，并在调用时发出警告。	函数不再推荐使用，并且可能会在未来的版本中被移除。
_deprecated_argument	用于标记函数的某个参数已被弃用，并在使用该参数时发出警告。	函数的某个参数不再推荐使用，并且可能会在未来的版本中被移除。

例如：

function my_old_function() {
    _deprecated_function( 'my_old_function', '3.0', 'my_new_function' );
    my_new_function();
}

function my_function( $arg1, $arg2, $deprecated_arg = null ) {
    if ( ! is_null( $deprecated_arg ) ) {
        _deprecated_argument( 'my_function', '3.0', '$deprecated_arg' );
    }
    // ... 函数逻辑 ...
}

_doing_it_wrong 和 WP_DEBUG 的关系

WP_DEBUG 常量是控制 _doing_it_wrong 函数行为的关键。 只有当 WP_DEBUG 为 true 时，_doing_it_wrong 函数才会触发 PHP 错误。 这意味着在生产环境中，默认情况下，_doing_it_wrong 警告不会显示给用户。

然而，即使在生产环境中，你仍然可以使用 WP_DEBUG_LOG 常量将 _doing_it_wrong 警告记录到 wp-content/debug.log 文件中。 这对于在生产环境中调试问题非常有用。

_doing_it_wrong 的局限性

虽然 _doing_it_wrong 函数非常有用，但它也有一些局限性：

• 依赖于开发者自觉： _doing_it_wrong 函数只有在开发者主动调用时才会起作用。 如果开发者没有意识到他们正在使用错误的方法，_doing_it_wrong 函数就无法发挥作用。
• 只提供警告： _doing_it_wrong 函数只提供警告，并不能阻止错误发生。 如果开发者忽略了警告，错误仍然会发生。
• 可能影响性能： 在某些情况下，频繁调用 _doing_it_wrong 函数可能会对性能产生轻微的影响。 因此，应该谨慎使用。

_doing_it_wrong 的最佳实践

以下是一些使用 _doing_it_wrong 函数的最佳实践：

• 只在开发环境中使用 WP_DEBUG： 不要在生产环境中启用 WP_DEBUG，因为它可能会显示敏感信息给用户。
• 仔细阅读错误信息： 错误信息会告诉你哪个函数被错误调用，以及错误的原因。
• 查找替代方案： 根据错误信息，查找推荐的替代方案。
• 更新你的代码： 使用替代方案替换过时或错误的代码。
• 测试你的代码： 确保你的代码在更新后仍然正常工作。
• 谨慎使用 doing_it_wrong_run action hook： 只在必要时使用 doing_it_wrong_run action hook，并确保你的自定义处理程序不会影响性能。
• 避免过度使用 _doing_it_wrong： 只在确实需要警告开发者时才使用 _doing_it_wrong 函数。

总结

_doing_it_wrong 是一个强大的调试工具，可以帮助开发者编写更健壮、更符合最佳实践的 WordPress 代码。 通过理解 _doing_it_wrong 函数的工作原理，并遵循最佳实践，你可以提高你的代码质量，减少潜在问题，并简化调试过程。

最后说几句

_doing_it_wrong 函数是WordPress开发中保证代码质量和规范的重要工具。 深入理解其内部机制，能够帮助开发者更好地识别和解决潜在问题。 积极响应_doing_it_wrong 警告，并及时更新代码，是保证WordPress应用稳定性和长期可维护性的关键。