wp_trigger_error()
云策文档标注
概述
wp_trigger_error() 是 WordPress 中用于生成用户级错误、警告、通知或弃用消息的函数。它仅在 WP_DEBUG 启用时触发，并支持自定义消息和错误级别。
关键要点
- 函数仅在 WP_DEBUG 为 true 时执行，否则直接返回。
- 接受三个参数：$function_name（触发错误的函数名）、$message（错误消息，可包含特定 HTML 标签和协议）、$error_level（错误级别，默认为 E_USER_NOTICE）。
- 内部使用 wp_kses() 过滤消息，仅允许 'a'、'code'、'br'、'em'、'strong' 标签和 http/https 协议。
- 当 $error_level 为 E_USER_ERROR 时，会抛出 WP_Exception 异常。
- 触发一个可用的 Hook：wp_trigger_error_run，用于调试回溯。
- 自 WordPress 6.4.0 版本引入。
代码示例
function wp_trigger_error( $function_name, $message, $error_level = E_USER_NOTICE ) {
// Bail out if WP_DEBUG is not turned on.
if ( ! WP_DEBUG ) {
return;
}
/**
* Fires when the given function triggers a user-level error/warning/notice/deprecation message.
*
* Can be used for debug backtracking.
*
* @since 6.4.0
*
* @param string $function_name The function that was called.
* @param string $message A message explaining what has been done incorrectly.
* @param int $error_level The designated error type for this error.
*/
do_action( 'wp_trigger_error_run', $function_name, $message, $error_level );
if ( ! empty( $function_name ) ) {
$message = sprintf( '%s(): %s', $function_name, $message );
}
$message = wp_kses(
$message,
array(
'a' => array( 'href' => true ),
'br' => array(),
'code' => array(),
'em' => array(),
'strong' => array(),
),
array( 'http', 'https' )
);
if ( E_USER_ERROR === $error_level ) {
throw new WP_Exception( $message );
}
trigger_error( $message, $error_level );
}注意事项
消息中若包含其他 HTML 标签或协议，应在传递给函数前进行转义，以避免被 wp_kses() 剥离。
原文内容
Generates a user-level error/warning/notice/deprecation message.
Description
Generates the message when WP_DEBUG is true.
Parameters
$function_namestringrequired-
The function that triggered the error.
$messagestringrequired-
The message explaining the error.
The message can contain allowed HTML'a'(with href),'code','br','em', and'strong'tags and http or https protocols.
If it contains other HTML tags or protocols, the message should be escaped before passing to this function to avoid being stripped wp_kses(). $error_levelintoptional-
The designated error type for this error.
Only works with E_USER family of constants.Default:
E_USER_NOTICE
Source
function wp_trigger_error( $function_name, $message, $error_level = E_USER_NOTICE ) {
// Bail out if WP_DEBUG is not turned on.
if ( ! WP_DEBUG ) {
return;
}
/**
* Fires when the given function triggers a user-level error/warning/notice/deprecation message.
*
* Can be used for debug backtracking.
*
* @since 6.4.0
*
* @param string $function_name The function that was called.
* @param string $message A message explaining what has been done incorrectly.
* @param int $error_level The designated error type for this error.
*/
do_action( 'wp_trigger_error_run', $function_name, $message, $error_level );
if ( ! empty( $function_name ) ) {
$message = sprintf( '%s(): %s', $function_name, $message );
}
$message = wp_kses(
$message,
array(
'a' => array( 'href' => true ),
'br' => array(),
'code' => array(),
'em' => array(),
'strong' => array(),
),
array( 'http', 'https' )
);
if ( E_USER_ERROR === $error_level ) {
throw new WP_Exception( $message );
}
trigger_error( $message, $error_level );
}
Hooks
- do_action( ‘wp_trigger_error_run’, string $function_name, string $message, int $error_level )
-
Fires when the given function triggers a user-level error/warning/notice/deprecation message.
Changelog
| Version | Description |
|---|---|
| 6.4.0 | Introduced. |