Как создать и настроить собственную страницу настроек для плагина в WordPress

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

Почему важна собственная страница настроек плагина в WordPress

Пользователь должен иметь возможность без лишних усилий изменять поведение плагина. Если опции разбросаны или хранятся в базе без интерфейса, это создаёт неудобства и повышает вероятность ошибок. Собственная страница настроек:

• Обеспечивает централизованное управление параметрами;
• Улучшает UX и повышает доверие к плагину;
• Позволяет использовать стандартные API WordPress для валидации и сохранения данных;
• Облегчает дальнейшее расширение и поддержку плагина.

Далее мы пройдёмся по основным шагам создания такой страницы.

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

Чтобы добавить страницу в меню админ-панели, используем хук admin_menu и функцию add_options_page(). Пример:

function wpdebug_add_plugin_settings_page() {
    add_options_page(
        'WPDebug Настройки плагина', // Заголовок страницы
        'WPDebug Настройки',           // Текст меню
        'manage_options',              // Возможность доступа
        'wpdebug-plugin-settings',    // Слаг страницы
        'wpdebug_render_settings_page'// Функция вывода контента
    );
}
add_action('admin_menu', 'wpdebug_add_plugin_settings_page');

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

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

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

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

function wpdebug_register_settings() {
    register_setting('wpdebug_options_group', 'wpdebug_text_option', 'wpdebug_sanitize_text');

    add_settings_section(
        'wpdebug_main_section',
        'Основные настройки',
        'wpdebug_main_section_cb',
        'wpdebug-plugin-settings'
    );

    add_settings_field(
        'wpdebug_text_option',
        'Текстовая опция',
        'wpdebug_text_option_cb',
        'wpdebug-plugin-settings',
        'wpdebug_main_section'
    );
}
add_action('admin_init', 'wpdebug_register_settings');

Здесь мы зарегистрировали группу опций wpdebug_options_group, опцию wpdebug_text_option с функцией санитайзера, добавили секцию и поле.

Функции обратного вызова:

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

function wpdebug_text_option_cb() {
    $value = get_option('wpdebug_text_option', '');
    echo '<input type="text" id="wpdebug_text_option" name="wpdebug_text_option" value="' . esc_attr($value) . '" size="50" />';
}

function wpdebug_sanitize_text($input) {
    return sanitize_text_field($input);
}

Функция wpdebug_sanitize_text очищает введённые данные, чтобы исключить вредоносный ввод.

Вывод страницы настроек с формой

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

function wpdebug_render_settings_page() {
    if (!current_user_can('manage_options')) {
        return;
    }
    ?>
    <div class="wrap">
        <h1>WPDebug Настройки плагина</h1>
        <form method="post" action="options.php">
            <?php
            settings_fields('wpdebug_options_group');
            do_settings_sections('wpdebug-plugin-settings');
            submit_button();
            ?>
        </form>
    </div>
    <?php
}

Функция settings_fields() генерирует скрытые поля безопасности, do_settings_sections() выводит зарегистрированные секции и поля, а submit_button() — кнопку сохранения.

Добавление различных типов полей настроек

Для удобства пользователей полезно создавать не только текстовые поля, но и чекбоксы, селекты, textarea и другие элементы.

Пример чекбокса

function wpdebug_checkbox_option_cb() {
    $option = get_option('wpdebug_checkbox_option', 0);
    echo '<input type="checkbox" id="wpdebug_checkbox_option" name="wpdebug_checkbox_option" value="1" ' . checked(1, $option, false) . ' /> Включить функцию';
}

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

Регистрация и добавление поля аналогично текстовому, только с указанием функции валидации wpdebug_sanitize_checkbox.

Пример селекта

function wpdebug_select_option_cb() {
    $option = get_option('wpdebug_select_option', 'option1');
    $choices = [
        'option1' => 'Опция 1',
        'option2' => 'Опция 2',
        'option3' => 'Опция 3'
    ];
    echo '<select id="wpdebug_select_option" name="wpdebug_select_option">';
    foreach ($choices as $value => $label) {
        echo '<option value="' . esc_attr($value) . '" ' . selected($option, $value, false) . '>' . esc_html($label) . '</option>';
    }
    echo '</select>';
}

function wpdebug_sanitize_select($input) {
    $valid = ['option1', 'option2', 'option3'];
    return in_array($input, $valid) ? $input : 'option1';
}

Практические советы и распространённые ошибки при создании страниц настроек

Создавая интерфейс для настроек, важно:

• Корректно проверять права доступа — функция current_user_can('manage_options') поможет защитить страницу;
• Использовать API настроек WordPress — это упрощает работу и повышает безопасность;
• Валидация и санитайзинг данных обязательны — не доверяйте пользовательскому вводу;
• Старайтесь делать интерфейс понятным и минималистичным, чтобы не перегружать пользователя;
• Тестируйте сохранение и загрузку опций в разных сценариях.

Распространённая ошибка — попытка самостоятельно обрабатывать POST-запросы без использования register_setting() и settings_fields(). Это усложняет код и увеличивает риск ошибок.

Дополнительные возможности: сохранение настроек через AJAX

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

function wpdebug_enqueue_admin_scripts($hook) {
    if ($hook !== 'settings_page_wpdebug-plugin-settings') {
        return;
    }
    wp_enqueue_script('wpdebug-admin-js', plugin_dir_url(__FILE__) . 'admin.js', ['jquery'], null, true);
    wp_localize_script('wpdebug-admin-js', 'wpdebug_ajax_obj', [
        'ajax_url' => admin_url('admin-ajax.php'),
        'nonce' => wp_create_nonce('wpdebug_save_settings_nonce')
    ]);
}
add_action('admin_enqueue_scripts', 'wpdebug_enqueue_admin_scripts');

function wpdebug_handle_ajax_save_settings() {
    check_ajax_referer('wpdebug_save_settings_nonce', 'nonce');

    if (!current_user_can('manage_options')) {
        wp_send_json_error('Нет доступа');
    }

    $text_option = isset($_POST['text_option']) ? sanitize_text_field($_POST['text_option']) : '';
    update_option('wpdebug_text_option', $text_option);

    wp_send_json_success('Настройки сохранены');
}
add_action('wp_ajax_wpdebug_save_settings', 'wpdebug_handle_ajax_save_settings');

В JavaScript (файл admin.js) нужно отправить AJAX-запрос с данными и nonce, обработать ответ и показать уведомление пользователю. Это повышает удобство работы с настройками.

Заключение

Создание собственной страницы настроек — обязательный навык для разработчика WordPress плагинов. Использование стандартного API значительно упрощает задачу и повышает безопасность. В статье мы рассмотрели полный цикл — от регистрации страницы до добавления различных полей и продвинутых приёмов с AJAX. Применяйте эти знания в своих проектах для удобного и функционального управления плагинами.