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 ) {
/**
* Always fires when the given function triggers a user-level error/warning/notice/deprecation message.
*
* Can be used to attach custom error handlers even if WP_DEBUG is not truthy.
*
* @since 7.0.0
*
* @param string $function_name The function that triggered the error.
* @param string $message The message explaining the error.
* @param int $error_level The designated error type for this error.
*/
do_action( 'wp_trigger_error_always_run', $function_name, $message, $error_level );
/**
* Filters whether to trigger an error.
*
* @since 7.0.0
*
* @param bool $trigger Whether to trigger the error. Default true.
* @param string $function_name The function that triggered the error.
* @param string $message The message explaining the error.
* @param int $error_level The designated error type for this error.
*/
if ( ! apply_filters( 'wp_trigger_error_trigger_error', true, $function_name, $message, $error_level ) ) {
return;
}
// 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 triggered the error.
* @param string $message The message explaining the error.
* @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_always_run’,
string $function_name ,string $message ,int $error_level ) Always fires when the given function triggers a user-level error/warning/notice/deprecation message.
- 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.
- apply_filters( ‘wp_trigger_error_trigger_error’,
bool $trigger ,string $function_name ,string $message ,int $error_level ) Filters whether to trigger an error.
Changelog
| Version | Description |
|---|---|
| 6.4.0 | Introduced. |
Deprecation and misuse notices are surfaced through
_deprecated_*or_doing_it_wrong()rather than this lower-level helper.wp_trigger_error()handles other user-level debug messages whenWP_DEBUGis true, andE_USER_ERRORis handled by throwingWP_Exception.