Функция get_settings_errors() в WordPress с примерами

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

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

get_settings_errors( string $setting = '', bool $sanitize = false ): array[]

Параметры

• $setting (string) – Необязательный. Идентификатор (slug) конкретного параметра, ошибки которого вы хотите получить. По умолчанию – пустая строка.
• $sanitize (bool) – Необязательный. Определяет, нужно ли повторно очищать значение перед его возвратом. По умолчанию – false.

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

Функция возвращает массив ошибок настроек, в каждом элементе которого содержится:

• setting (string) – Идентификатор параметра, к которому относится ошибка.
• code (string) – Код ошибки, который используется для идентификации ошибки.
• message (string) – Форматированное текстовое сообщение, которое будет показано пользователю.
• type (string) – Необязательный тип сообщения, который управляет HTML-классом. Возможные значения: 'error', 'success', 'warning', 'info'. По умолчанию – 'error'.

Как это работает

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

Пример 1: Получение и отображение ошибок на странице настроек

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

<?php
add_action('admin_menu', 'custom_settings_page');

function custom_settings_page() {
    add_options_page(
        __('Настройки плагина', 'textdomain'), 
        __('Мой плагин', 'textdomain'), 
        'manage_options', 
        'custom_plugin_settings', 
        'custom_plugin_settings_callback'
    );
}

function custom_plugin_settings_callback() {
    ?>
    <div class="wrap">
        <h1><?php _e('Настройки плагина', 'textdomain'); ?></h1>
        <form method="POST" action="options.php">
            <?php
            settings_fields('custom_plugin_options_group');
            do_settings_sections('custom_plugin_settings');
            submit_button();
            ?>
        </form>
    </div>
    <?php
}

add_action('admin_init', 'custom_plugin_settings_init');

function custom_plugin_settings_init() {
    // Регистрация опции
    register_setting('custom_plugin_options_group', 'my_custom_option', 'sanitize_text_field');

    // Добавление секции
    add_settings_section(
        'custom_section', 
        __('Основные настройки', 'textdomain'), 
        'custom_section_callback', 
        'custom_plugin_settings'
    );

    // Добавление поля
    add_settings_field(
        'my_custom_option', 
        __('Моя опция', 'textdomain'), 
        'custom_option_callback', 
        'custom_plugin_settings', 
        'custom_section'
    );
}

function custom_section_callback() {
    echo '<p>' . __('Настройки вашей опции.', 'textdomain') . '</p>';
}

function custom_option_callback() {
    $value = get_option('my_custom_option', '');
    echo '<input type="text" name="my_custom_option" value="' . esc_attr($value) . '" />';
}

// Обработка ошибок
add_action('admin_notices', 'custom_admin_notices');

function custom_admin_notices() {
    $errors = get_settings_errors('my_custom_option');

    if (empty($errors)) {
        return;
    }

    foreach ($errors as $error) {
        $css_id = 'setting-error-' . $error['code'];
        $css_class = $error['type'] . ' settings-error';
        echo "<div id='$css_id' class='$css_class'>";
        echo "<p><strong>{$error['message']}</strong></p>";
        echo "</div>";
    }
}

// Проверка данных перед сохранением
add_action('pre_update_option_my_custom_option', 'validate_custom_option', 10, 2);

function validate_custom_option($new_value, $old_value) {
    if (empty($new_value)) {
        add_settings_error('my_custom_option', 'empty_option', __('Поле не должно быть пустым.', 'textdomain'), 'error');
        return $old_value; // Возврат старого значения
    }
    return $new_value; // Возврат нового значения, если оно валидное
}

Пример 2: Использование функции для очистки значений

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

add_action('admin_init', 'my_plugin_admin_init');

function my_plugin_admin_init() {
    // Проверка и регистрация опции
    $value = get_option('my_custom_option', '');
    $sanitized_value = sanitize_text_field($value);
    
    if ($value !== $sanitized_value) {
        add_settings_error('my_custom_option', 'sanitize_error', __('Значение содержит недопустимые символы.', 'textdomain'), 'error');
    }
}

// Обработка ошибок
add_action('admin_notices', 'my_plugin_admin_notices');

function my_plugin_admin_notices() {
    $errors = get_settings_errors('my_custom_option', true); // Передаем true для повторной очистки

    if (empty($errors)) {
        return;
    }

    foreach ($errors as $error) {
        $css_id = 'setting-error-' . $error['code'];
        $css_class = $error['type'] . ' settings-error';
        echo "<div id='$css_id' class='$css_class'>";
        echo "<p><strong>{$error['message']}</strong></p>";
        echo "</div>";
    }
}

Заключение

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