wp_trigger_error() │ WP 6.4.0

Создаёт кастомное сообщение об ошибке / предупреждении / уведомлении / устаревшем коде.

Функция работает только при включенном WP_DEBUG:

  • Если WP_DEBUG включён, функция создаёт PHP-ошибку через trigger_error().

  • Если WP_DEBUG отключен, PHP-ошибка не создаётся. Но срабатывает хук wp_trigger_error_always_run, поэтому через него можно самостоятельно записать сообщение в лог или обработать другим способом.
Работает на основе: wp_kses()
Хуки из функции

Возвращает

null.

  • void - ничего не возвращает.

Использование

wp_trigger_error( $function_name, $message, $error_level );
$function_name(string) (обязательный)
Название функции или метода, вызвавшего ошибку. Если указано, будет добавлено в начало сообщения в формате function_name(): сообщение.
$message(string) (обязательный)
Описание ошибки. Разрешены HTML-теги <a href="">, <code>, <br>, <em> и <strong>, а также протоколы http и https. Остальные теги и протоколы удаляются функцией wp_kses().
$error_level(int)

Уровень ошибки. Поддерживаются только константы семейства E_USER: E_USER_NOTICE, E_USER_WARNING, E_USER_ERROR и E_USER_DEPRECATED.

При уровне E_USER_ERROR функция выбрасывает исключение WP_Exception вместо вызова стандартной PHP-функции trigger_error().

По умолчанию: E_USER_NOTICE

Примеры

#1 Вывести предупреждение о неправильной конфигурации

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
		);
	}
}

#2 Перехватить сообщение независимо от WP_DEBUG

Хук wp_trigger_error_always_run срабатывает даже при отключённой отладке.

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
		)
	);
}

Список изменений

С версии 6.4.0 Введена.

Код wp_trigger_error() WP 7.1

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 );
}

Вспомогательные