settings_errors() │ WP 3.0.0

Displays on the screen messages (notices and errors) registered by the function add_settings_error().

This function is one of the group of functions of the Settings API.

settings_errors() is called by WordPress automatically when any settings page is loaded (the "Settings" section page of the admin panel). If there are registered messages in the errors array (global $wp_settings_errors) they will be output in admin_notice.

Messages about the results of validation of option values should be registered at the time those values are processed - this is the $sanitize_callback parameter in the function register_setting( $option_group, $option_name, $sanitize_callback ).

WordPress automatically outputs all registered messages on settings pages, so there is usually no need to call this function - it is called automatically. However, if you display settings for example in a plugin, then you need to output errors using this function.

Uses: get_settings_errors()

No Hooks.

Returns

null. Outputs the HTML code of the error messages to the screen.

Usage

settings_errors( $setting, $sanitize, $hide_on_update );
$setting(string)
Identifier of the group of messages, usually the option name. Must match the $setting parameter from add_settings_error( $setting ). If nothing is specified, then all registered errors will be returned.
Default: ''
$sanitize(boolean)
Specify true to trigger the sanitize_option() function - it sanitizes the option using the filter specified in sanitize_option() (each option has its own filter). If the option fails validation, the corresponding error message is automatically registered.
Default: false
$hide_on_update(boolean)
Specify true to hide all messages when updating options. Validation messages should be displayed on the first visit to the settings page. If the user has saved new values, error messages will be hidden to avoid repeating messages that were already shown before saving the settings. This is useful when you need to show important errors when returning to the settings page, for example: an option cannot be empty.
Default: false

Examples

0

#1 Display all messages registered for our option my_setting_error: 

add_action( 'admin_notices', 'your_admin_notices_action' );

function your_admin_notices_action() {
	settings_errors( 'my_setting_error' );
}

Changelog

Since 3.0.0 Introduced.
Since 5.3.0 Legacy error and updated CSS classes are mapped to notice-error and notice-success.

settings_errors() code WP 6.9

wp-admin/includes/template.php 
function settings_errors( $setting = '', $sanitize = false, $hide_on_update = false ) {

	if ( $hide_on_update && ! empty( $_GET['settings-updated'] ) ) {
		return;
	}

	$settings_errors = get_settings_errors( $setting, $sanitize );

	if ( empty( $settings_errors ) ) {
		return;
	}

	$output = '';

	foreach ( $settings_errors as $key => $details ) {
		if ( 'updated' === $details['type'] ) {
			$details['type'] = 'success';
		}

		if ( in_array( $details['type'], array( 'error', 'success', 'warning', 'info' ), true ) ) {
			$details['type'] = 'notice-' . $details['type'];
		}

		$css_id    = sprintf(
			'setting-error-%s',
			esc_attr( $details['code'] )
		);
		$css_class = sprintf(
			'notice %s settings-error is-dismissible',
			esc_attr( $details['type'] )
		);

		$output .= "<div id='$css_id' class='$css_class'> \n";
		$output .= "<p><strong>{$details['message']}</strong></p>";
		$output .= "</div> \n";
	}

	echo $output;
}

Settings API