_deprecated_hook()
云策文档标注
概述
_deprecated_hook() 函数用于标记已弃用的动作或过滤器钩子，并在 WP_DEBUG 启用时触发弃用通知。它通常由 do_action_deprecated() 和 apply_filters_deprecated() 调用，无需直接使用。
关键要点
- 函数功能：标记弃用钩子，通过 'deprecated_hook_run' 动作提供调用回溯，并在 WP_DEBUG 为 true 时触发用户错误。
- 参数说明：$hook（必需，钩子名称）、$version（必需，弃用版本）、$replacement（可选，替代钩子）、$message（可选，附加消息）。
- 相关钩子：do_action('deprecated_hook_run') 在弃用钩子调用时触发；apply_filters('deprecated_hook_trigger_error') 过滤是否触发错误。
- 使用场景：主要用于 do_action_deprecated() 和 apply_filters_deprecated() 内部，帮助开发者管理钩子弃用过程。
代码示例
function _deprecated_hook( $hook, $version, $replacement = '', $message = '' ) {
do_action( 'deprecated_hook_run', $hook, $replacement, $version, $message );
if ( WP_DEBUG && apply_filters( 'deprecated_hook_trigger_error', true ) ) {
$message = empty( $message ) ? '' : ' ' . $message;
if ( $replacement ) {
$message = sprintf(
__( 'Hook %1$s is deprecated since version %2$s! Use %3$s instead.' ),
$hook,
$version,
$replacement
) . $message;
} else {
$message = sprintf(
__( 'Hook %1$s is deprecated since version %2$s with no alternative available.' ),
$hook,
$version
) . $message;
}
wp_trigger_error( '', $message, E_USER_DEPRECATED );
}
}注意事项
- 错误类型：自 WordPress 5.4.0 起，弃用错误类型为 E_USER_DEPRECATED（之前为 E_USER_NOTICE）。
- 调试依赖：仅在 WP_DEBUG 定义为 true 且 'deprecated_hook_trigger_error' 过滤器返回 true 时触发错误。
- 直接调用：通常不需要直接调用此函数，应通过 do_action_deprecated() 或 apply_filters_deprecated() 使用。
原文内容
Marks a deprecated action or filter hook as deprecated and throws a notice.
Description
Use the ‘deprecated_hook_run’ action to get the backtrace describing where the deprecated hook was called.
Default behavior is to trigger a user error if WP_DEBUG is true.
This function is called by the do_action_deprecated() and apply_filters_deprecated() functions, and so generally does not need to be called directly.
Parameters
$hookstringrequired-
The hook that was used.
$versionstringrequired-
The version of WordPress that deprecated the hook.
$replacementstringoptional-
The hook that should have been used. Default empty string.
$messagestringoptional-
A message regarding the change. Default empty.
Source
function _deprecated_hook( $hook, $version, $replacement = '', $message = '' ) {
/**
* Fires when a deprecated hook is called.
*
* @since 4.6.0
*
* @param string $hook The hook that was called.
* @param string $replacement The hook that should be used as a replacement.
* @param string $version The version of WordPress that deprecated the argument used.
* @param string $message A message regarding the change.
*/
do_action( 'deprecated_hook_run', $hook, $replacement, $version, $message );
/**
* Filters whether to trigger deprecated hook errors.
*
* @since 4.6.0
*
* @param bool $trigger Whether to trigger deprecated hook errors. Requires
* `WP_DEBUG` to be defined true.
*/
if ( WP_DEBUG && apply_filters( 'deprecated_hook_trigger_error', true ) ) {
$message = empty( $message ) ? '' : ' ' . $message;
if ( $replacement ) {
$message = sprintf(
/* translators: 1: WordPress hook name, 2: Version number, 3: Alternative hook name. */
__( 'Hook %1$s is <strong>deprecated</strong> since version %2$s! Use %3$s instead.' ),
$hook,
$version,
$replacement
) . $message;
} else {
$message = sprintf(
/* translators: 1: WordPress hook name, 2: Version number. */
__( 'Hook %1$s is <strong>deprecated</strong> since version %2$s with no alternative available.' ),
$hook,
$version
) . $message;
}
wp_trigger_error( '', $message, E_USER_DEPRECATED );
}
}
Hooks
- do_action( ‘deprecated_hook_run’, string $hook, string $replacement, string $version, string $message )
-
Fires when a deprecated hook is called.
- apply_filters( ‘deprecated_hook_trigger_error’, bool $trigger )
-
Filters whether to trigger deprecated hook errors.