wp_trigger_error() │ WP 6.4.0

Creates a custom error, warning, notice, or deprecation message.

The function works only when WP_DEBUG is enabled. With debugging enabled it creates a PHP error through trigger_error(). When debugging is disabled, no PHP error is created, but the wp_trigger_error_always_run action still fires.

Uses: wp_kses()
Hooks from the function

Returns

null.

  • void - returns nothing.

Usage

wp_trigger_error( $function_name, $message, $error_level );
$function_name(string) (required)
Name of the function or method that triggered the error. It is prepended to the message as function_name(): message.
$message(string) (required)
Error description. The tags <a href="">, <code>, <br>, <em>, and <strong>, plus HTTP and HTTPS protocols, are allowed.
$error_level(int)

Error level. Only E_USER_NOTICE, E_USER_WARNING, E_USER_ERROR, and E_USER_DEPRECATED are supported. At E_USER_ERROR, the function throws WP_Exception.

Default: E_USER_NOTICE

Examples

0

#1 Display a configuration warning 

function my_plugin_validate_config( array $config ): void {
	if ( empty( $config['api_key'] ) ) {
		wp_trigger_error(
			__FUNCTION__,
			'The API key is not configured.',
			E_USER_WARNING
		);
	}
}
0

#2 Intercept the message regardless of WP_DEBUG

The wp_trigger_error_always_run hook runs even when debugging is disabled.

add_action( 'wp_trigger_error_always_run', 'my_plugin_log_wp_error', 10, 3 );

function my_plugin_log_wp_error( string $function_name, string $message, int $error_level ): void {
	error_log(
		sprintf(
			'[%d] %s(): %s',
			$error_level,
			$function_name,
			$message
		)
	);
}

Changelog

Since 6.4.0 Introduced.

wp_trigger_error() code WP 7.0.4

wp-includes/functions.php 
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 );
}

Helper Functions