add_settings_error() │ WP 3.0.0

Registers a message for option validation to later display this message to the user. Usually, such a message is a data validation error.

The function is part of the Settings API.

Use it to display a message to the user that the validation of the option value has not been passed, for example, in case of: field validation errors or if a required field is not filled in, etc.

By default, messages are automatically displayed for all subpages in the "Settings" section. However, if option changes are displayed on other pages registered by the functions: add_menu_page() or add_submenu_page(), then messages about option updates or errors will not be shown automatically.

To display them, you just need to add the function settings_errors() to the settings page output code, usually right after the page header output:

<h2>Settings Page Title</h2>
<?php settings_errors(); ?>

add_settings_error() is usually used within the option value validation function: see the $sanitize_callback parameter in register_setting().

No Hooks.

Returns

null. Does not return anything.

Usage

add_settings_error( $setting, $code, $message, $type );
$setting(string) (required)
The name of the option to which the current error relates. An identifier that must match the $setting parameter from settings_errors( $setting ) or get_settings_errors( $setting ).
$code(string) (required)
The identifier, name of the error. Used as part of the id attribute of the HTML tag. The prefix setting-error- will be added to the name and id attribute of the wrapping message HTML tag <div id="">.
$message(string) (required)
The formatted text of the message that will be displayed on the screen. The text will be wrapped in <div> and <p> tags.
$type(string)
The type of this message: error or updated. The value specified here will be added to the class of the wrapping <div> tag. To specify multiple classes, separate them with commas.
Default: 'error'

Examples

0

#1 Saving the option value or displaying an error message

Suppose we registered an option with function register_setting(), and specified the check function sanitize_opt() in parameter $sanitize_callback.

Below is an example of this function, which registers a message about checking and saving an option value:

function sanitize_opt( $value ) {

	$option_name = 'my_option'; // option name
	$message = 'The data was successfully updated.';
	$type = 'updated';

	if( empty( $value ) ){
		$type = 'error';
		$message = 'Field xxxx cannot be empty';
	}

	if( is_numeric( $value ) ){
		$type = 'error';
		$message = 'Field xxxx cannot be a number';
	}

	// Clean up the option
	$value = sanitize_text_field( $value );

	add_settings_error( $option_name, 'settings_updated', $message, $type );

	if( $type === 'error' ){
		return get_option( $option_name );
	}

	return $value;
}

The check function sanitize_opt() should always return the option value to save it to the database and WordPress itself will save the returned value to the option. But what if some options have not been checked and an error needs to be logged, but there is no need to update the option value in the database? In this case, the function sanitize_opt(), should return the original option value. The thing is, there is no way to undo the work of updating an option, so in order not to update an option, we can return the original value of the option, a kind of hack which allows to achieve the desired result.

0

#2 Error logging when checking option values

Suppose we created a settings page with two form fields: input and checkbox (see second example on settings API page). Now, we need to check the values of these fields and if they do not comply with the norms, register errors that WordPress will automatically display when saving:

/**
 * function to check option values and error logging if necessary!
 * It is assumed that we have registered the option as follows:
 * register_setting( 'primer_group', 'primer_option', 'primer_options_check' );
 */
function primer_options_check( $data ) {

	$option_name = 'my_option'; // option name

	// check the input field
	$message = $type = null;

	if( empty( $data['input'] ) ){
		$type = 'error';
		$message = 'The option name field cannot be empty';
	}
	elseif( preg_match( '~[0-9]~', $data['input'] ) ){
		$data['input'] = null;
		$type = 'error';
		$message = 'The option name field cannot contain numbers';
	}

	if( $message ){
		add_settings_error( 'primer_input', 'input', $message, $type );
	}

	// check the checkbox field
	$message = $type = null;

	if( empty( $data['checkbox'] ) ){
		$type = 'error';
		$message = 'Checkbox must be checked!';
	}

	if( $message ){
		add_settings_error( 'primer_checkbox', 'checkbox', $message, $type );
	}

	if( $type === 'error' ){
		return get_option( $option_name );
	}

	return $data;
}

Notes

  • Global. Array[]. $wp_settings_errors Storage array of errors registered during this pageload

Changelog

Since 3.0.0 Introduced.
Since 5.3.0 Added warning and info as possible values for $type.

add_settings_error() code WP 6.8.3

wp-admin/includes/template.php 
function add_settings_error( $setting, $code, $message, $type = 'error' ) {
	global $wp_settings_errors;

	$wp_settings_errors[] = array(
		'setting' => $setting,
		'code'    => $code,
		'message' => $message,
		'type'    => $type,
	);
}

Settings API