Функция ADD_SETTINGS_ERROR: Регистрация ошибки настройки – WP 3.0.0

# Функция ADD_SETTINGS_ERROR() │ WP 3.0.0

## Регистрация ошибки настройки для отображения пользователю

Эта функция является частью API настроек WordPress. Её используют для отображения сообщений пользователям о проблемах с проверкой настроек, отсутствующих настройках или других любых проблемах.

Ошибки настроек следует добавлять внутри функции $sanitize_callback, определенной в register_setting() для конкретной настройки, чтобы предоставить обратную связь о результате отправки.

По умолчанию сообщения об ошибках отображаются сразу после отправки, вызвавшей ошибку. Дополнительные вызовы функции settings_errors() можно использовать для отображения ошибок даже при первом открытии страницы с настройками.

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

- **null**. Ничего (null).

## Применение

Для использования функции используется следующий синтаксис:

```php
add_settings_error( $setting, $code, $message, $type );

• $setting (строка) (обязательно) — З_slug (идентификатор) настройки, к которой относится эта ошибка.
• $code (строка) (обязательно) — С_slug (имя) для идентификации ошибки. Используется как часть атрибута 'id' в HTML выводе.
• $message (строка) (обязательно) — Форматированный текст сообщения для отображения пользователю (будет показан внутри стилизованных <div> и <p> тегов).
• $type (строка) — Тип сообщения, который контролирует HTML-класс. Возможные значения: 'error', 'success', 'warning', 'info'. По умолчанию: 'error'.

Примеры

Пример 1: Сохранение значения опции или отображение сообщения об ошибке

Предположим, мы зарегистрировали опцию с помощью функции register_setting() и указали функцию проверки sanitize_opt() в параметре $sanitize_callback.

Вот пример данной функции, которая добавляет сообщение о проверке и сохранении значения опции:

function sanitize_opt( $value ) {
    $option_name = 'my_option'; // имя опции
    $message = 'Данные успешно обновлены.';
    $type = 'updated';

    if ( empty( $value ) ) {
        $type = 'error';
        $message = 'Поле не может быть пустым';
    }

    if ( is_numeric( $value ) ) {
        $type = 'error';
        $message = 'Поле не может быть числом';
    }

    // Очистка значения опции
    $value = sanitize_text_field( $value );

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

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

    return $value;
}

Функция sanitize_opt() всегда должна возвращать значение опции, чтобы сохранить его в базе данных. WordPress сам сохранит возвращаемое значение в опции. Но если некоторые опции не были проверены и ошибка должна быть зарегистрирована, но нет необходимости обновлять значение опции в базе данных, функция sanitize_opt() должна вернуть исходное значение опции. В этом случае возвращение исходного значения опции позволяет избежать обновления, что можно рассматривать как своего рода хак.

Пример 2: Регистрация ошибок при проверке значений опций

Допустим, мы создали страницу настроек с двумя полями формы: поле ввода и флажок (чекбокс). Теперь нам нужно проверить значения этих полей, и если они не соответствуют требованиям, зарегистрировать ошибки, которые WordPress автоматически отобразит при сохранении:

function primer_options_check( $data ) {
    $option_name = 'my_option'; // имя опции

    // Проверка поля ввода
    $message = $type = null;

    if ( empty( $data['input'] ) ) {
        $type = 'error';
        $message = 'Поле имени опции не может быть пустым';
    } elseif ( preg_match( '~[0-9]~', $data['input'] ) ) {
        $data['input'] = null;
        $type = 'error';
        $message = 'Поле имени опции не может содержать числа';
    }

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

    // Проверка поля чекбокса
    $message = $type = null;

    if ( empty( $data['checkbox'] ) ) {
        $type = 'error';
        $message = 'Чекбокс должен быть отмечен!';
    }

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

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

    return $data;
}

Заметки

• Глобальная переменная. $wp_settings_errors — массив для хранения ошибок, зарегистрированных во время загрузки страницы.

Изменения

• С 3.0.0 ��� Введена в систему.
• С 5.3.0 — Добавлены возможные значения 'warning' и 'info' для параметра $type.

Код функции

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,
    );
}

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

• add_settings_field()
• add_settings_section()
• do_settings_fields()
• do_settings_sections()
• get_settings_errors()
• register_setting()
• settings_errors()
• settings_fields()
• unregister_setting()