settings_errors()

Является частью Settings API в WordPress. Позволяет вывести на страницах в админке уведомления и ошибки (в виде HTML), которые были добавлены функцией add_settings_error().

Вообще мы обычно используем эту функцию при создании каких-либо страниц настроек в админке, но тут есть важный момент, про который не нужно забывать – функция вызывается автоматически, если ваша страница настроек находится в разделе Настройки в меню админ-панели. Т.е. например Настройки > Дополнительно. Также эта функция автоматически вызывается для всех групп настроек и на стандартных страницах настроек, находящихся в этом разделе, например Настройки > Общие, Настройки > Написание и т.д.

settings_errors( $setting = '', $sanitize = false, $hide_on_update = false )

Параметры

$setting

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

$sanitize

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

$hide_on_update

(логический) Если указать в true, то сообщения об ошибках отображаться не будут, если в URL присутствует параметр $_GET['settings-updated'] с любым значением, который, как вы знаете, добавляется при сохранении страницы настройки (хоть и сразу скрывается оттуда).

Примеры

1.Добавляем прямо на страницу настроек

add_pages_page( 'Какие-то настройки', 'Какие-то', 'manage_options', 'truesettings', 'display_page_html' );

function display_page_html() {
 
	echo '<div class="wrap">';
	echo '<h1>Какие-то настройки</h1>'
	echo '<form method="post" action="options.php">';
 
	settings_errors( 'truesettings_errors', '', false );
	settings_fields( 'truesettings' );

Лишний раз напомню, что если бы вместо функции add_pages_page() была бы например add_options_page(), то ничего бы делать было не нужно.

2. Добавляем в хук admin_notices

add_action( 'admin_notices', 'true_add_settings_errors' );
 
function true_add_settings_errors() {
 
	settings_errors( 'truesettings_errors' );
 
}

Но в этом случае, вам также придётся ещё и добавить проверки того, что код срабатывает на нужной нам странице, например дописать строчку:

$screen = get_current_screen();
 
if ( 'true_settings_page' === $screen->id ) {

Особенно это будет необходимо в том случае, если вы захотите использовать settings_errors() без параметров, ведь тогда она выполнится через хук admin_notices на страницах настроек WordPress, там, где ошибки/уведомления и так выводятся автоматически! Тогда мы получим дублирующиеся сообщения об ошибках, типа того:

3. Как, вероятно, делать не следует

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

add_action( 'admin_notices', 'nottrue_add_settings_errors' );
 
function nottrue_add_settings_errors() {
 
	if( ! empty( $_GET[ 'something' ] ) ) {
		add_settings_error( 'nottruesettings_errors', 'err', 'Ошибка' );
	}
	settings_errors( 'nottruesettings_errors' );
 
}

В таком случае думаю можно скипнуть лишние действия и не работать лишний раз с транзитнымм кэшем, а сразу выводить ошибки тогда:

	if( ! empty( $_GET[ 'something' ] ) ) {
		echo '<div class="notice notice-error"><p><strong>Ошибка</strong></p></div>';
	}

Миша

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

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