add_settings_error() │ WP 3.0.0

Register a settings error to be displayed to the user

Part of the Settings API. Use this to show messages to users about settings validation problems, missing settings or anything else.

Settings errors should be added inside the $sanitize_callback function defined in register_setting() for a given setting to give feedback about the submission.

By default messages will show immediately after the submission that generated the error. Additional calls to settings_errors() can be used to show errors even when the settings page is first accessed.

No Hooks.

Return

null. Nothing (null).

Usage

add_settings_error( $setting, $code, $message, $type );
$setting(string) (required)
Slug title of the setting to which this error applies.
$code(string) (required)
Slug-name to identify the error. Used as part of 'id' attribute in HTML output.
$message(string) (required)
The formatted message text to display to the user (will be shown inside styled <div> and <p> tags).
$type(string)
Message type, controls HTML class. Possible values include 'error', 'success', 'warning', 'info'.
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.5.2

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