add_settings_error() WP 3.0

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

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

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

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

Хуков нет.

Возвращает

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

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

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'

Примеры

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

# 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

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

Код add settings error: wp-admin/includes/template.php ^{WP 5.4.2}

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

Cвязанные функции

Из раздела: API Настроек