Функция settings_errors() в WordPress: параметры, возвращаемое значение, примеры

## SETTINGS_ERRORS() │ WP 3.0.0

Функция settings_errors() выводит ошибки настройки, зарегистрированные с помощью add_settings_error(). Эта функция является частью API настроек в WordPress и отображает блок для каждой ошибки, полученной с помощью функции get_settings_errors().

Когда вы отправляете страницу настроек, которая использует API настроек, функция settings_errors() вызывается автоматически. Ошибки добавляются во время функции обратного вызова валидации для конкретной настройки, определённой в функции register_setting().

### Параметры

- **$sanitize**: данный параметр передаётся в get_settings_errors() и позволяет повторно выполнить очистку значения настройки.
- **$hide_on_update**: данный параметр позволяет показывать ошибки только при первом загрузке страницы настроек. Если пользо��атель уже сохранил новые значения, ошибки будут скрыты, чтобы избежать повторного отображения сообщений.

Это особенно полезно для отображения общих ошибок, таких как отсутствие необходимых настроек, когда пользователь попадает на страницу настроек.

### Возвращаемое значение

Функция возвращает null, если ошибок нет.

### Как использовать

```php
settings_errors( $setting, $sanitize, $hide_on_update );

• $setting (string): (необязательный) Название конкретной настройки, для которой вы хотите получить ошибки. По умолчанию ''.
• $sanitize (bool): (необязательный) Нужно ли повторно очищать значение настройки перед возвратом ошибок. По умолчанию false.
• $hide_on_update (bool): (необязательный) Если установить в true, ошибки не будут отображаться, если страница настроек уже была отправлена. По умолчанию false.

Примеры

Пример 1: Отображение всех сообщений, зарегистрированных для вашей настройки my_setting_error

add_action( 'admin_notices', 'your_admin_notices_action' );

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

Изменения

• С версии 3.0.0: Введена функция.
• С версии 5.3.0: Устаревшие коды ошибок и CSS-классы были сопоставлены с notice-error и notice-success.

Код функции

Функция settings_errors() находится в файле 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 .= "
 n";
    $output .= "
{$details['message']}
";
    $output .= "
 n";
}

echo $output;

}

Связанные функции

• add_settings_error(): Добавляет ошибку настройки.
• add_settings_field(): Добавляет поле для настройки.
• add_settings_section(): Добавляет секцию для настроек.
• do_settings_fields(): Выводит поля настройки.
• do_settings_sections(): Выводит секции настроек.
• get_settings_errors(): Получает ошибки настройки.
• register_setting(): Регистрирует настройку.
• settings_fields(): Выводит поля настроек.
• unregister_setting(): Убирает настройку.