get_settings_errors() │ WP 3.0.0

Получает сообщения зарегистрированные функцией add_settings_error().

Эта функция является одной из группы функций API настроек. И является вспомогательной функцией для settings_errors().

Проверяет массив $wp_settings_errors на наличие в нем добавленных при загрузке страницы сообщений (ошибок) и возвращает их.

Мы можем сохранять сообщения во временную опцию: set_transient( 'settings_errors' ), чтобы, используя get_transient(), при перезагрузке страницы или новом заходе на страницу настроек, мы могли получить ошибки предыдущих проверок данных. WordPress понимает эту временную опцию и если в параметре GET запроса будет установлен параметр ?settings-updated=true (он устанавливается автоматически при удачном сохранении опций, то наша временная опция с сохраненными в ней сообщениями будет слита с текущем массивом сообщений и временная опция settings_errors будет удалена. Вот часть кода функции get_settings_errors() отвечающая за эти действия:

// If settings were passed back from options.php then use them
if (
	isset( $_GET['settings-updated'] ) &&
	$_GET['settings-updated'] &&
	get_transient( 'settings_errors' )
)
{
	$wp_settings_errors = array_merge(
		(array) $wp_settings_errors,
		get_transient( 'settings_errors' )
	);

	delete_transient( 'settings_errors' );
}
Основа для: settings_errors()

Хуков нет.

Возвращает

Массив[]. Массив содержащий данные о сообщениях:

array(
	'setting' =>  $setting,
	'code'    =>  $code,
	'message' =>  $message,
	'type'    =>  $type
);

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

get_settings_errors( $setting, $sanitize );
$setting(строка)
Идентификатор, который должен совпадать с параметром $setting из add_settings_error(). Будет получена указанная группа ошибок. Если не указать никакой идентификатор, то функция получит все зарегистрированные ошибки.
По умолчанию: ''
$sanitize(логический)
Нужно ли очистить значение опции указанной опции: true (да, очистить еще раз) или false (нет, очищать не надо).Укажите параметр $sanitaze = true, чтобы активировать функцию sanitize_option() - очищает опцию по фильтру указанному в sanitize_option (очистку для неизвестных функции опций нужно регистрировать отдельно. см. описание sanitize_option()). При этом, если опция не проходит проверку, автоматически регистрируется сообщение об ошибке. Это может пригодится, когда нужно проверить данные формы до того, как они будут сохраняться, например, при простом заходе на страницу настроек. Сообщения выводятся всякий раз когда в массиве ошибок есть зарегистрированные сообщения.
По умолчанию: false

Примеры

0

#1 Пример работы функции

Выведем сообщения для поля опции "my_option_name", которые были зарегистрированы, при попытке сохранить опцию. Если значения полей опции не прошли проверку, сообщения об ошибке были зарегистрированы функцией add_settings_error() при проверке данных формы, при сохранении опций. После того, как данные формы были отправлены мы можем получить эти сообщения функцией get_settings_errors() и вывести их через хук admin_notices. Для этого напишем свою функцию обрабатывающую результат get_settings_errors() и выводящую все сообщения на экран:

function your_admin_notices_action() {

	$settings_errors = get_settings_errors( 'my_option_name' );

	if ( empty( $settings_errors ) )
		return;

	$output = '';
	foreach ( $settings_errors as $key => $details ) {
		$css_id = 'setting-error-' . $details['code'];
		$css_class = $details['type'] . ' settings-error';
		$output .= "<div id='$css_id' class='$css_class'> n";
		$output .= "<p><strong>{$details['message']}</strong></p>";
		$output .= "</div> n";
	}
	echo $output;
}

add_action( 'admin_notices', 'your_admin_notices_action' );

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

Заметки

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

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

С версии 3.0.0 Введена.

Код get_settings_errors() WP 6.5.2

wp-admin/includes/template.php 
function get_settings_errors( $setting = '', $sanitize = false ) {
	global $wp_settings_errors;

	/*
	 * If $sanitize is true, manually re-run the sanitization for this option
	 * This allows the $sanitize_callback from register_setting() to run, adding
	 * any settings errors you want to show by default.
	 */
	if ( $sanitize ) {
		sanitize_option( $setting, get_option( $setting ) );
	}

	// If settings were passed back from options.php then use them.
	if ( isset( $_GET['settings-updated'] ) && $_GET['settings-updated'] && get_transient( 'settings_errors' ) ) {
		$wp_settings_errors = array_merge( (array) $wp_settings_errors, get_transient( 'settings_errors' ) );
		delete_transient( 'settings_errors' );
	}

	// Check global in case errors have been added on this pageload.
	if ( empty( $wp_settings_errors ) ) {
		return array();
	}

	// Filter the results to those of a specific setting if one was set.
	if ( $setting ) {
		$setting_errors = array();

		foreach ( (array) $wp_settings_errors as $key => $details ) {
			if ( $setting === $details['setting'] ) {
				$setting_errors[] = $wp_settings_errors[ $key ];
			}
		}

		return $setting_errors;
	}

	return $wp_settings_errors;
}

API Настроек