WordPress: как создать страницу настроек в плагине с использованием Settings API

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

Что такое Settings API и зачем он нужен

Settings API — это набор функций, предоставляемых WordPress для стандартизированного создания страниц настроек и управления сохранением опций. Использование API гарантирует, что настройки будут корректно добавлены в базу, валидированы и выведены в удобном виде.

Преимущества использования Settings API:

• Автоматическая обработка формы и сохранение данных.
• Упрощённое добавление различных типов полей (текстовые, чекбоксы, селекты и другие).
• Безопасность: API проверяет права пользователя и nonce.
• Межверсионная совместимость и стандартизация оформления.

Создаём страницу настроек плагина на примере WPCodex

Рассмотрим создание страницы настроек для плагина с префиксом wpcodex_. Начнём с регистрации страницы в меню и инициализации настроек.

add_action('admin_menu', 'wpcodex_add_settings_page');
add_action('admin_init', 'wpcodex_settings_init');

function wpcodex_add_settings_page() {
    add_options_page(
        'Настройки WPCodex',
        'WPCodex Settings',
        'manage_options',
        'wpcodex-settings',
        'wpcodex_render_settings_page'
    );
}

function wpcodex_settings_init() {
    register_setting('wpcodex_settings_group', 'wpcodex_options', 'wpcodex_options_validate');

    add_settings_section(
        'wpcodex_main_section',
        'Основные настройки',
        'wpcodex_section_cb',
        'wpcodex-settings'
    );

    add_settings_field(
        'wpcodex_text_field',
        'Текстовое поле',
        'wpcodex_text_field_cb',
        'wpcodex-settings',
        'wpcodex_main_section'
    );
}

Здесь мы добавили страницу в меню «Настройки» и зарегистрировали группу настроек с одной секцией и полем.

Вывод секции и поля

Для отрисовки секции и поля создадим обратные вызовы:

function wpcodex_section_cb() {
    echo '<p>Настройте параметры плагина ниже.</p>';
}

function wpcodex_text_field_cb() {
    $options = get_option('wpcodex_options');
    $value = isset($options['text_field']) ? esc_attr($options['text_field']) : '';
    echo '<input type="text" name="wpcodex_options[text_field]" value="' . $value . '" />';
}

Создание формы и обработка сохранения настроек

Для полноценной страницы настроек нужно вывести форму с nonce и кнопкой сохранения. Сделаем функцию вывода страницы:

function wpcodex_render_settings_page() {
    ?>
    <div class="wrap">
        <h1>Настройки плагина WPCodex</h1>
        <form action="options.php" method="post">
            <?php
            settings_fields('wpcodex_settings_group');
            do_settings_sections('wpcodex-settings');
            submit_button('Сохранить настройки');
            ?>
        </form>
    </div>
    <?php
}

Обратите внимание, что settings_fields() выводит необходимые поля для безопасности (nonce, option_page).

Валидация и фильтрация данных при сохранении

Чтобы избежать ошибок и сохранить корректные данные, реализуем функцию валидации:

function wpcodex_options_validate($input) {
    $output = array();

    if (isset($input['text_field'])) {
        $output['text_field'] = sanitize_text_field($input['text_field']);
    }

    return $output;
}

Используя sanitize_text_field(), мы очищаем ввод от опасных символов и тегов.

Добавление дополнительных полей: чекбоксы и селекты

Чтобы расширить настройки, добавим чекбокс и выпадающий список.

add_settings_field(
    'wpcodex_checkbox',
    'Включить функцию',
    'wpcodex_checkbox_cb',
    'wpcodex-settings',
    'wpcodex_main_section'
);

add_settings_field(
    'wpcodex_select',
    'Выберите опцию',
    'wpcodex_select_cb',
    'wpcodex-settings',
    'wpcodex_main_section'
);

function wpcodex_checkbox_cb() {
    $options = get_option('wpcodex_options');
    $checked = isset($options['checkbox']) && $options['checkbox'] === '1' ? 'checked' : '';
    echo '<input type="checkbox" name="wpcodex_options[checkbox]" value="1" ' . $checked . ' />';
}

function wpcodex_select_cb() {
    $options = get_option('wpcodex_options');
    $value = isset($options['select']) ? $options['select'] : '';
    $choices = [
        'option1' => 'Опция 1',
        'option2' => 'Опция 2',
        'option3' => 'Опция 3',
    ];
    echo '<select name="wpcodex_options[select]">';
    foreach ($choices as $key => $label) {
        $selected = selected($value, $key, false);
        echo "<option value=\"$key\" $selected>$label</option>";
    }
    echo '</select>';
}

Не забудьте добавить обработку этих полей в функцию валидации:

if (isset($input['checkbox'])) {
    $output['checkbox'] = $input['checkbox'] === '1' ? '1' : '0';
} else {
    $output['checkbox'] = '0';
}

$valid_selects = ['option1', 'option2', 'option3'];
if (isset($input['select']) && in_array($input['select'], $valid_selects)) {
    $output['select'] = $input['select'];
}

Использование настроек в коде плагина

После добавления и сохранения настроек их можно получить через get_option('wpcodex_options'). Например, чтобы проверить, включена ли функция:

$options = get_option('wpcodex_options');
if (!empty($options['checkbox']) && $options['checkbox'] === '1') {
    // Выполнить нужное действие
}

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

Советы по улучшению интерфейса страницы настроек

Для удобства пользователя можно добавить:

• Подсказки к полям с помощью description или title.
• Группировать параметры по секциям.
• Использовать расширенные поля с помощью популярных библиотек или плагинов (например, Clearfy Pro содержит расширенные возможности настройки).
• Сделать страницу адаптивной и понятной на мобильных устройствах.

Также рассмотрите возможность интеграции с плагинами из WPShop.ru для упрощения работы с настройками и расширения функционала.

Заключение

Создание страницы настроек с помощью Settings API — это стандартный и правильный способ сделать ваш плагин удобным для пользователя и безопасным. Следуя приведённым шагам, вы сможете быстро реализовать гибкую панель управления с валидированием и сохранением параметров. Не забывайте тестировать все изменения и следить за обновлениями WordPress, чтобы использовать новые возможности API.