get_settings_errors()

Функция является частью Settings API в WordPress и возвращает массив уведомлений и ошибок для страниц настроек в админке.

Уведомления и ошибки она получает из транзитного кэша, а добавлены они туда функцией add_settings_error(). В случае, если вызывается при успешном сохранении настроек (задана переменная $_GET['settings-updated']), то все ошибки записываются в глобальную переменную $wp_settings_errors, а транзитный кэш очищается. Сохранение в транзиты позволяет получить значения ошибок при повторном заходе на страницу или при её перезагрузке.

Результат возвращается в формате:

Array
(
    [0] => Array
        (
            [setting] => true_option_group_errors
            [code] => test2
            [message] => Какая-то ошибка
            [type] => error
        )
 
    [1] => Array
        (
            [setting] => true_option_group_errors
            [code] => test2
            [message] => Какой-то успех
            [type] => success
        )
 
)

Кстати, обратите внимание, что код ошибки [code], который мы задаём в функциях add_settings_error() может дублироваться и он не является ключом массива, как могло бы показаться.

get_settings_errors( $setting = '', $sanitize = false )

Параметры

$setting

(строка) Ярлык группы сообщений об ошибках. Этот ярлык мы также указываем в функции add_settings_error(), когда добавляем сообщение об ошибке. А если передать в этом параметре пустую строку, то будут выведены все добавленные сообщения.

$sanitize

(логический) Использовать этот параметр имеет смысл, только если в качестве первого значения функции вы указали ключ одной из стандартных опций WordPress.
 
Потому что при значении true WordPress попытается получить значение опции из первого параметра функцией get_option(), а именно get_option( $setting ) и применить к нему очистку функцией sanitize_option(), которая работает только для стандартных опций WordPress, если только вы не хукнули фильтр sanitize_option_{$option} и, да, добавляет сообщение об ошибке функцией add_settings_error() внутри.

Примеры

1. Использование функции

В этом примере мы попробуем использовать функцию в хуке admin_notices, для того, чтобы получить все уведомления и ошибки в виде массива и преобразовать их в обычный HTML-код. Но разумеется, это лишь пример и в реальной жизни я бы всё-таки порекомендовал для этой цели использовать функцию settings_errors().

add_action( 'admin_notices', 'true_print_notices' );
 
function true_print_notices() {
 
	if( $errors = get_settings_errors() ) {
		foreach( $errors as $error ) {
			// напоминаю, что доступные элементы массива это:
			// $error[ 'setting' ]
			// $error[ 'code' ]
			// $error[ 'type' ]
			echo '<p>' . $error[ 'message' ] . '</p>';
		}
	}
 
}

Интереснейший результат ниже на скриншоте:

2. Общая картина, как всё это работает, последовательно

Давайте, пожалуй, ещё раз пошагово вам расскажу, как работает вся эта система в рамках Settings API в WordPress.

Конечно, нет смысла вставлять целиком код для создания какой-либо страницы настроек, потому что это много кода и потому что есть отдельный гайд. Но зато я могу выделить некоторые моменты.

Итак, самый первый шаг, который происходит, это (капитанство, да) сабмитится форма с полями страницы настроек на файл options.php.

Затем происходит очистка каждой зарегистрированной функцией register_setting() опции. Очистка производится функцией, указанной в параметрах при регистрации опции. И как раз во время очистки опций, если вдруг что-то не валидируется, то мы не сохраняем опцию в базу данных, а берём её старое значение из бд, если оно там имеется, и записываем ошибку в транзитный кэш при помощи add_settings_error(). Валидация может выглядет например так:

if( ! is_email( $value ) ) { 
	// создаём ошибку и регистрируем её (сохраняем в транзитный кэш)
	add_settings_error( 'true_options', 'notemail', 'Это явно не email!', 'error' );
	// если ошибка возникала, то мы должны вернуть старое значение из БД
	// если оно конечно существует
	$value = get_option( 'true_email' );
}

Затем происходит редирект из файла options.php обратно на страницу настроек с параметром $_GET['settings-updated'].

Затем, при выводе ошибок функциями settings_error() и get_settings_error() (одна является частью другой), транзитный кэш очищается, а ошибки становятся доступны внутри глобальной переменной $wp_settings_errors, ну и затем они выводятся.