Как создать страницу настроек плагина WordPress с примерами кода

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

Регистрация страницы настроек в меню WordPress

Первый шаг — добавить пункт меню или подменю в админ-панель. Для этого используется хук admin_menu и функция add_options_page (если нужна страница в разделе «Настройки»).

Пример регистрации страницы настроек для плагина "wpcontrol":

add_action('admin_menu', 'wpcontrol_add_settings_page');

function wpcontrol_add_settings_page() {
    add_options_page(
        'Настройки плагина WPControl', // Заголовок страницы
        'WPControl',                   // Название меню
        'manage_options',              // Права доступа
        'wpcontrol-settings',          // Уникальный слаг
        'wpcontrol_render_settings_page' // Функция вывода содержимого
    );
}

В данном коде мы добавляем новую страницу в меню «Настройки» с названием «WPControl» и указываем функцию, которая будет выводить содержимое страницы.

Создание функции вывода страницы настроек

Функция wpcontrol_render_settings_page отвечает за отображение HTML формы с настройками. Важно использовать встроенные функции WordPress для безопасности и правильной обработки.

function wpcontrol_render_settings_page() {
    ?>
    <div class="wrap">
        <h1>Настройки плагина WPControl</h1>
        <form action="options.php" method="post">
            <?php
            settings_fields('wpcontrol_options_group');
            do_settings_sections('wpcontrol-settings');
            submit_button();
            ?>
        </form>
    </div>
    <?php
}

Здесь settings_fields выводит скрытые поля безопасности и токены, а do_settings_sections — все зарегистрированные секции и поля для страницы с слагом wpcontrol-settings.

Регистрация настроек, секций и полей

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

Пример кода, регистрирующего одну настройку и поле для ввода текста:

add_action('admin_init', 'wpcontrol_register_settings');

function wpcontrol_register_settings() {
    register_setting(
        'wpcontrol_options_group', // Группа настроек
        'wpcontrol_option_text',   // Имя опции в базе данных
        ['sanitize_callback' => 'sanitize_text_field'] // Очистка данных
    );

    add_settings_section(
        'wpcontrol_main_section',  // Идентификатор секции
        'Основные настройки',      // Заголовок секции
        'wpcontrol_section_callback', // Описание секции
        'wpcontrol-settings'       // Страница, к которой относится секция
    );

    add_settings_field(
        'wpcontrol_option_text',   // Идентификатор поля
        'Текстовое поле',          // Заголовок поля
        'wpcontrol_text_field_render', // Функция вывода поля
        'wpcontrol-settings',      // Страница
        'wpcontrol_main_section'   // Секция
    );
}

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

function wpcontrol_text_field_render() {
    $option = get_option('wpcontrol_option_text');
    ?>
    <input type="text" name="wpcontrol_option_text" value="<?php echo esc_attr($option); ?>" />
    <?php
}

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

Обработка и сохранение данных настроек

WordPress автоматически сохранит настройку при отправке формы, если она зарегистрирована через register_setting. Важен момент — нужно обеспечить корректную очистку и валидацию данных, что мы сделали с помощью параметра sanitize_callback в примере выше.

Если требуется более сложная логика обработки, можно использовать фильтры и хуки, например pre_update_option_{option_name} или update_option_{option_name}, чтобы до- или после сохранения выполнить дополнительные действия.

Пример использования нескольких полей настроек

Давайте добавим чекбокс и выпадающий список, чтобы сделать интерфейс более разнообразным.

add_action('admin_init', 'wpcontrol_register_extra_settings');

function wpcontrol_register_extra_settings() {
    register_setting('wpcontrol_options_group', 'wpcontrol_option_checkbox', ['sanitize_callback' => 'wpcontrol_sanitize_checkbox']);
    register_setting('wpcontrol_options_group', 'wpcontrol_option_select', ['sanitize_callback' => 'sanitize_text_field']);

    add_settings_field('wpcontrol_option_checkbox', 'Включить функцию', 'wpcontrol_checkbox_render', 'wpcontrol-settings', 'wpcontrol_main_section');
    add_settings_field('wpcontrol_option_select', 'Выберите вариант', 'wpcontrol_select_render', 'wpcontrol-settings', 'wpcontrol_main_section');
}

function wpcontrol_checkbox_render() {
    $option = get_option('wpcontrol_option_checkbox');
    ?>
    <input type="checkbox" name="wpcontrol_option_checkbox" value="1" <?php checked(1, $option, true); ?> />
    <?php
}

function wpcontrol_select_render() {
    $option = get_option('wpcontrol_option_select');
    $choices = ['option1' => 'Вариант 1', 'option2' => 'Вариант 2', 'option3' => 'Вариант 3'];
    ?>
    <select name="wpcontrol_option_select">
        <?php foreach ($choices as $value => $label) : ?>
            <option value="<?php echo esc_attr($value); ?>" <?php selected($option, $value); ?>><?php echo esc_html($label); ?></option>
        <?php endforeach; ?>
    </select>
    <?php
}

function wpcontrol_sanitize_checkbox($input) {
    return $input == 1 ? 1 : 0;
}

Теперь на странице настроек будет чекбокс и выпадающий список с тремя вариантами. При сохранении данные проходят валидацию и сохраняются.

Резюме и рекомендации

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

Несколько советов для эффективной работы:

• Используйте settings_fields и do_settings_sections для вывода форм — так вы обеспечите безопасность и совместимость.
• Для каждой опции обязательно регистрируйте функцию очистки данных (sanitize_callback), чтобы избежать ошибок и уязвимостей.
• Разбивайте настройки на логические секции для удобства пользователя.
• Обязательно проверяйте права доступа и используйте current_user_can('manage_options') для защиты страницы настроек.

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