_deprecated_argument()
云策文档标注
概述
_deprecated_argument() 函数用于标记函数参数已弃用，并在使用时发出通知。它通常与 WP_DEBUG 配合，在调试模式下触发用户错误，帮助开发者识别和更新代码。
关键要点
- 函数用于处理已弃用的函数参数，需在调用前检查参数是否被使用（如与默认值比较或判断是否为空）。
- 参数包括 $function_name（函数名）、$version（弃用版本）和 $message（可选消息）。
- 触发 deprecated_argument_run 钩子，可用于获取使用弃用参数的文件和函数回溯信息。
- 当 WP_DEBUG 为 true 且 deprecated_argument_trigger_error 过滤器允许时，会触发 E_USER_DEPRECATED 错误。
- 错误消息根据 $message 是否提供而不同，支持国际化（通过 __() 函数）。
代码示例
if ( ! empty( $deprecated ) ) {
_deprecated_argument( __FUNCTION__, '3.0.0' );
}注意事项
- 在 WordPress 5.4.0 中，错误类型从 E_USER_NOTICE 更改为 E_USER_DEPRECATED。
- 函数自 WordPress 3.0.0 引入，广泛用于核心函数中处理参数弃用。
原文内容
Marks a function argument as deprecated and inform when it has been used.
Description
This function is to be used whenever a deprecated function argument is used.
Before this function is called, the argument must be checked for whether it was used by comparing it to its default value or evaluating whether it is empty.
For example:
if ( ! empty( $deprecated ) ) {
_deprecated_argument( __FUNCTION__, '3.0.0' );
}There is a ‘deprecated_argument_run’ hook that will be called that can be used to get the backtrace up to what file and function used the deprecated argument.
The current behavior is to trigger a user error if WP_DEBUG is true.
Parameters
$function_namestringrequired-
The function that was called.
$versionstringrequired-
The version of WordPress that deprecated the argument used.
$messagestringoptional-
A message regarding the change. Default empty string.
Source
function _deprecated_argument( $function_name, $version, $message = '' ) {
/**
* Fires when a deprecated argument is called.
*
* @since 3.0.0
*
* @param string $function_name The function that was called.
* @param string $message A message regarding the change.
* @param string $version The version of WordPress that deprecated the argument used.
*/
do_action( 'deprecated_argument_run', $function_name, $message, $version );
/**
* Filters whether to trigger an error for deprecated arguments.
*
* @since 3.0.0
*
* @param bool $trigger Whether to trigger the error for deprecated arguments. Default true.
*/
if ( WP_DEBUG && apply_filters( 'deprecated_argument_trigger_error', true ) ) {
if ( function_exists( '__' ) ) {
if ( $message ) {
$message = sprintf(
/* translators: 1: PHP function name, 2: Version number, 3: Optional message regarding the change. */
__( 'Function %1$s was called with an argument that is <strong>deprecated</strong> since version %2$s! %3$s' ),
$function_name,
$version,
$message
);
} else {
$message = sprintf(
/* translators: 1: PHP function name, 2: Version number. */
__( 'Function %1$s was called with an argument that is <strong>deprecated</strong> since version %2$s with no alternative available.' ),
$function_name,
$version
);
}
} else {
if ( $message ) {
$message = sprintf(
'Function %1$s was called with an argument that is <strong>deprecated</strong> since version %2$s! %3$s',
$function_name,
$version,
$message
);
} else {
$message = sprintf(
'Function %1$s was called with an argument that is <strong>deprecated</strong> since version %2$s with no alternative available.',
$function_name,
$version
);
}
}
wp_trigger_error( '', $message, E_USER_DEPRECATED );
}
}
Hooks
- do_action( ‘deprecated_argument_run’, string $function_name, string $message, string $version )
-
Fires when a deprecated argument is called.
- apply_filters( ‘deprecated_argument_trigger_error’, bool $trigger )
-
Filters whether to trigger an error for deprecated arguments.