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

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

Пример использования функции get_settings_errors() на странице настроек WordPress
На скриншоте можно заметить, что ошибки, которые мы выводили кодом чуть выше, добавились перед заголовком страницы настроек. Это потому, что хук admin_notices срабатывает раньше заголовка. А ошибки, которые имеют необходимые CSS-классы, которые в этом примере добавились автоматически, потому что мы находимся в разделе Настройки, так вот, их WordPress двигает под заголовок через JS.

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, ну и затем они выводятся.

Миша

Впервые познакомился с WordPress в 2009 году. Организатор и спикер на конференциях WordCamp. Преподаватель в школе Нетология.

Пишите, если нужна помощь с сайтом или разработка с нуля.

Чтобы оставить комментарий, пожалуйста, зарегистрируйтесь или войдите.

Миша Рудрастых и WordPress

Полезности из мира WordPress и жизни студии.

Мой телеграм-канал