add_settings_error() │ WP 3.0.0

Регистрирует сообщение о проверке опции, чтобы позднее показать это сообщение пользователю. Обычно такое сообщение - это ошибка проверки данных.

Функция является частью API настроек.

Используйте, чтобы вывести сообщение пользователю, что проверка значение опции не была пройдена например, при: ошибки проверки поля или если не заполнено обязательное поле и т.д.

По умолчанию сообщение выводятся автоматически для всех подстраниц в разделе "Настройки". Но если изменение опций выводятся на других страницах, которые регистрируются функциями: add_menu_page() или add_submenu_page(), то сообщения об обновлении опций или ошибке, не будут показаны автоматически.

Чтобы их показать, нужно просто добавить в код вывода страницы настроек функцию settings_errors(), обычно её нужно добавлять сразу после вывода заголовка страницы:

<h2>Заголовок страницы настроек</h2>
<?php settings_errors(); ?>

add_settings_error() обычно используется внутри функции проверки значений опции: см. параметр $sanitize_callback в register_setting().

Хуков нет.

Возвращает

null. Ничего не возвращает.

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

add_settings_error( $setting, $code, $message, $type );
$setting(строка) (обязательный)
Название опции, к которой относиться текущая ошибка. Идентификатор, который должен совпадать с параметром $setting из settings_errors( $setting ) или get_settings_errors( $setting ).
По умолчанию: нет
$code(строка) (обязательный)
Идентификатор, название ошибки. Используется как часть id атрибута HTML тега. Префикс setting-error- будет добавлен к названию и id атрибуту оборачивающего сообщение html тега <div id="">.
По умолчанию: нет
$message(строка) (обязательный)
Отформатированный текст сообщения, который будет выведен на экран. Текст будет обернут в <div> и <p> теги.
По умолчанию: нет
$type(строка)
Какого типа это сообщение: error или updated. Указанное тут значение будет добавлено к классу оборачивающего тега <div>. Чтобы указать несколько классов разделите их запятыми.
По умолчанию: 'error'

Примеры

0

#1 Сохранение значения опции или вывод сообщения об ошибке

Предположим, мы зарегистрировали опцию функцией register_setting(), в параметре $sanitize_callback указали функцию проверки: sanitize_opt().

Ниже пример этой функции, в которой регистрируется сообщение о проверке и сохранении значения опции:

function sanitize_opt( $value ) {
	$option_name = 'my_option'; // название опции
	$message = 'Данные успешно обновлены.';
	$type = 'updated';

	if( empty($value) ) {
		$type = 'error';
		$message = 'Поле хххх не может быть пустым';
	}

	if( is_numeric($value) ){
		$type = 'error';
		$message = 'Поле хххх не может быть числом';
	}

	// Очистим опцию
	$value = sanitize_text_field( $value );

	add_settings_error( $option_name, 'settings_updated', $message, $type );

	if( $type === 'error' )
		return get_option( $option_name );
	else
		return $value;
}

Функция проверки sanitize_opt() должна всегда возвращать значение опции для сохранения его в БД и WordPress сам сохранит вернувшееся значение в опцию. Но что делать, если проверка некоторых опций не была пройдена и нужно зарегистрировать ошибку, чтобы её увидел пользователь, но не нужно обновлять значение опции в БД? В этом случае, функция sanitize_opt(), должна вернуть оригинальное значение опции. Дело в том, что отменить работу обновления опции никак не получится, поэтому чтобы не обновлять опцию, мы можем вернуть исходное значение опции, такой своего рода хак, который позволяет добиться нужного результата...

0

#2 Регистрация ошибок при проверке значений опции

Предположим мы создали страницу настроек с двумя полями формы: input и checkbox (смотрите второй пример на странице API настроек). Теперь, нам нужно проверить значения этих полей и если они не соответствуют нормам, зарегистрировать ошибки, которые WordPress при сохранении выведет автоматически:

/**
 * функция проверки значений опций и регистрации ошибок если нужно!
 * предполагается что мы регистрировали опцию так:
 * register_setting( 'primer_group', 'primer_option', 'primer_options_check' );
 */
function primer_options_check( $data ) {
	$option_name = 'my_option'; // название опции

	// проверяем поле input
	$message = $type = null;

	if ( empty( $data['input'] ) ) {
		$type = 'error';
		$message = 'Поле "Название опции" не может быть пустым';
	}
	elseif( preg_match( '~[0-9]~', $data['input'] ) ){
		$data['input'] = null;
		$type = 'error';
		$message = 'Поле "Название опции" не может содержать цифр';
	}

	if( $message ){
		add_settings_error( 'primer_input', 'input', $message, $type );
	}

	// проверяем поле checkbox
	$message = $type = null;

	if( empty( $data['checkbox'] ) ){
		$type = 'error';
		$message = 'Чекбокс нужно отметить!';
	}

	if( $message ){
		add_settings_error( 'primer_checkbox', 'checkbox', $message, $type );
	}

	if( $type === 'error' )
		return get_option( $option_name );
	else
		return $data;
}

Заметки

  • Global. Массив. $wp_settings_errors Storage array of errors registered during this pageload

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

С версии 3.0.0 Введена.
С версии 5.3.0 Added warning and info as possible values for $type.

Код add_settings_error() WP 5.9.3

wp-admin/includes/template.php 
function add_settings_error( $setting, $code, $message, $type = 'error' ) {
	global $wp_settings_errors;

	$wp_settings_errors[] = array(
		'setting' => $setting,
		'code'    => $code,
		'message' => $message,
		'type'    => $type,
	);
}

API Настроек