Функция add_settings_error(): Вывод Сообщений Об Ошибках на Страницах Настроек WordPress

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

add_settings_error( string $setting, string $code, string $message, string $type = 'error' )

Описание

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

• $setting — строка, название опции, к которой относится ошибка.
• $code — строка, идентификатор ошибки (используется в HTML как часть атрибута id).
• $message — строка, сообщение для отображения пользователю.
• $type — строка, тип сообщения (например, error, updated, success, warning).

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

• null — функция не возвращает значений.

Когда использовать add_settings_error()

1. При проверке значений опций — если в процессе валидации настроек обнаружена ошибка, вы можете зарегистрировать ее с помощью этой функции, чтобы пользователи видели сообщение.
2. Для успешных действий — помимо ошибок, функция может выводить и успешные уведомления, используя параметр $type = 'updated' или другие варианты.

Пример 1: Вывод сообщения об ошибке валидации опции

Предположим, у нас есть настройка с именем my_custom_option, и нам нужно убедиться, что она не пуста. Если поле пустое, выводим ошибку.

function validate_my_custom_option( $value ) {
    $option_name = 'my_custom_option';
    
    if ( empty( $value ) ) {
        // Регистрация ошибки
        add_settings_error(
            $option_name,            // Опция, к которой относится ошибка
            'empty_option',          // Идентификатор ошибки
            'Значение не может быть пустым!',  // Сообщение об ошибке
            'error'                  // Тип сообщения
        );
        return get_option( $option_name );  // Возвращаем текущее значение, чтобы не сохранить пустое поле
    }
    
    // Если валидация успешна, возвращаем значение
    return sanitize_text_field( $value );
}

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

Пример 2: Вывод сообщения об успешном сохранении

Вы можете использовать add_settings_error() не только для ошибок, но и для уведомлений о том, что данные были успешно сохранены. Например:

function validate_and_save_option( $value ) {
    $option_name = 'my_custom_setting';
    
    // Проверим значение
    if ( strlen( $value ) < 5 ) {
        add_settings_error( 
            $option_name, 
            'value_too_short', 
            'Значение слишком короткое. Введите не менее 5 символов.', 
            'error' 
        );
        return get_option( $option_name ); // Возвращаем текущее значение
    }

    // Если все хорошо, сохраняем и выводим сообщение об успехе
    add_settings_error(
        $option_name, 
        'settings_saved', 
        'Настройки успешно сохранены!', 
        'updated'
    );
    
    return sanitize_text_field( $value );
}

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

Пример 3: Проверка нескольких полей и регистрация ошибок

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

function validate_multiple_options( $options ) {
    // Проверим текстовое поле
    if ( empty( $options['text_field'] ) ) {
        add_settings_error(
            'text_field', 
            'empty_text', 
            'Текстовое поле не может быть пустым.', 
            'error'
        );
    }

    // Проверим, отмечен ли чекбокс
    if ( ! isset( $options['checkbox_field'] ) ) {
        add_settings_error(
            'checkbox_field', 
            'checkbox_not_checked', 
            'Необходимо отметить чекбокс.', 
            'error'
        );
    }

    // Если были ошибки, возвращаем текущие значения опций
    if ( get_settings_errors() ) {
        return get_option( 'my_options_group' );
    }

    // Если все успешно, возвращаем очищенные данные
    return array_map( 'sanitize_text_field', $options );
}

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

Вывод ошибок на странице

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

function render_settings_page() {
    echo '<h1>Мои настройки</h1>';
    
    // Выводим сообщения об ошибках и успехах
    settings_errors();
    
    // Остальной HTML-код формы настроек
}

Функция settings_errors() выводит все зарегистрированные ошибки и уведомления.

Заключение

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