The add_settings_error() WordPress PHP function is used to register a settings error to be displayed to the user. This function is part of the Settings API and primarily used to show messages about settings validation problems, missing settings, or any other issues.
Usage
To use this function, you call it within the $sanitize_callback function defined in register_setting(). This is how you provide feedback about the submission of a particular setting. By default, the error messages will show right after the submission that caused the error.
function handle_settings($input) {
// Suppose we want to validate an input for being non-empty
if(empty($input)) {
add_settings_error(
'my_setting',
'my_setting_error',
'The input cannot be empty',
'error'
);
}
return $input;
}
In this example, handle_settings is our sanitize callback. If the input is empty, we add a settings error with the slug-name ‘my_setting’, an error code of ‘my_setting_error’, a message ‘The input cannot be empty’, and type ‘error’.
Parameters
$setting (string): Slug title of the setting to which this error applies.$code (string): Slug-name to identify the error. Used as part of ‘id’ attribute in HTML output.$message (string): 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’.
More information
See WordPress Developer Resources: add_settings_error()
Examples
Display a success message
In this example, we are saving an option and we want to show a success message when the option is successfully saved.
function save_my_option($value) {
add_option('my_option', $value);
add_settings_error('my_option', 'my_option_updated', 'Successfully saved', 'success');
}
Display an error message
In this example, we show an error message when a certain condition is not met.
function check_option_value($value) {
if($value != 'expected_value') {
add_settings_error('my_option', 'my_option_error', 'Invalid value', 'error');
}
}
Update an option and display a message
In this example, we update an option and display a message about the operation.
function update_my_option($value) {
update_option('my_option', $value);
add_settings_error('my_option', 'my_option_updated', 'Successfully updated', 'success');
}
Display a warning message
Here, we display a warning message when an unexpected value is detected.
function validate_option_value($value) {
if($value == 'unexpected_value') {
add_settings_error('my_option', 'my_option_warning', 'Unexpected value', 'warning');
}
}
Show an informational message
In this case, we show an informational message to guide the user.
function info_about_my_option() {
add_settings_error('my_option', 'my_option_info', 'Please provide a valid value', 'info');
}
In each of these examples, we’re using add_settings_error() to provide feedback to the user about the result of an operation or to provide guidance. The— By I am Programmer — 2 years ago”}]n