Как создать настройки плагина в WordPress: практическое руководство

|

Введение в создание страницы настроек плагина

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

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

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

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

function wpapp_add_settings_page() {
    add_options_page(
        'Настройки плагина WPApp', // Заголовок страницы
        'WPApp Настройки',           // Текст в меню
        'manage_options',            // Капабилити
        'wpapp-settings',            // Слаг страницы
        'wpapp_render_settings_page' // Функция вывода
    );
}
add_action('admin_menu', 'wpapp_add_settings_page');

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

Регистрация и обработка опций плагина через Settings API

Чтобы управлять настройками, лучше использовать WordPress Settings API. Это обеспечит корректную валидацию и сохранение параметров. Для начала зарегистрируем группу настроек и поля:

function wpapp_register_settings() {
    register_setting('wpapp_options_group', 'wpapp_options', 'wpapp_sanitize_options');

    add_settings_section(
        'wpapp_main_section',
        'Основные настройки',
        'wpapp_main_section_callback',
        'wpapp-settings'
    );

    add_settings_field(
        'wpapp_text_field',
        'Текстовое поле',
        'wpapp_text_field_callback',
        'wpapp-settings',
        'wpapp_main_section'
    );
}
add_action('admin_init', 'wpapp_register_settings');

function wpapp_sanitize_options($input) {
    $output = array();
    if (isset($input['wpapp_text_field'])) {
        $output['wpapp_text_field'] = sanitize_text_field($input['wpapp_text_field']);
    }
    return $output;
}

В этом примере мы регистрируем настройки с группой wpapp_options_group и создаём секцию и поле. Функция wpapp_sanitize_options отвечает за очистку входящих данных перед сохранением — важная мера безопасности.

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

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

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

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

function wpapp_text_field_callback() {
    $options = get_option('wpapp_options');
    printf(
        '<input type="text" id="wpapp_text_field" name="wpapp_options[wpapp_text_field]" value="%s" />',
        isset($options['wpapp_text_field']) ? esc_attr($options['wpapp_text_field']) : ''
    );
}

Тут мы используем стандартные функции WordPress: settings_fields выводит скрытые поля для безопасности, do_settings_sections отрисовывает зарегистрированные секции и поля, а submit_button добавляет кнопку отправки.

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

Вместо одного текстового поля зачастую нужны чекбоксы, селекты или textarea. Рассмотрим, как добавить и вывести разные типы:

function wpapp_register_settings() {
    register_setting('wpapp_options_group', 'wpapp_options', 'wpapp_sanitize_options');

    add_settings_section('wpapp_main_section', 'Основные настройки', 'wpapp_main_section_callback', 'wpapp-settings');

    add_settings_field('wpapp_text_field', 'Текстовое поле', 'wpapp_text_field_callback', 'wpapp-settings', 'wpapp_main_section');

    add_settings_field('wpapp_checkbox', 'Включить функцию', 'wpapp_checkbox_callback', 'wpapp-settings', 'wpapp_main_section');

    add_settings_field('wpapp_select', 'Выберите вариант', 'wpapp_select_callback', 'wpapp-settings', 'wpapp_main_section');
}

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

function wpapp_select_callback() {
    $options = get_option('wpapp_options');
    $value = isset($options['wpapp_select']) ? $options['wpapp_select'] : '';
    ?>
    <select id="wpapp_select" name="wpapp_options[wpapp_select]">
        <option value="" <?php selected($value, ''); ?>>-- Выберите --</option>
        <option value="option1" <?php selected($value, 'option1'); ?>>Вариант 1</option>
        <option value="option2" <?php selected($value, 'option2'); ?>>Вариант 2</option>
    </select>
    <?php
}

function wpapp_sanitize_options($input) {
    $output = array();
    $output['wpapp_text_field'] = isset($input['wpapp_text_field']) ? sanitize_text_field($input['wpapp_text_field']) : '';
    $output['wpapp_checkbox'] = !empty($input['wpapp_checkbox']) ? 1 : 0;
    $allowed = array('option1', 'option2');
    $output['wpapp_select'] = in_array($input['wpapp_select'], $allowed) ? $input['wpapp_select'] : '';
    return $output;
}

Используя разные типы полей, вы сделаете настройки более удобными и информативными. Обязательно валидируйте данные при сохранении.

Советы по безопасности и юзабилити

При создании страницы настроек важно учитывать несколько моментов:

  • Проверка прав доступа: всегда проверяйте, что пользователь имеет права manage_options перед выводом страницы.
  • Используйте nonce: WordPress автоматически добавляет nonce в settings_fields(), что защищает от CSRF.
  • Очистка данных: применяйте функции наподобие sanitize_text_field, esc_attr, wp_kses_post в зависимости от типа данных.
  • Удобство интерфейса: группируйте поля по логике, добавляйте описания и подсказки.

Использование популярных плагинов для расширения настроек

Если вы хотите не создавать настройки вручную, можно использовать готовые библиотеки и плагины, которые значительно упрощают работу:

  • Redux Framework — мощный инструмент с поддержкой множества типов полей, панель настроек с вкладками.
  • CMB2 — удобный фреймворк для создания метаполей и настроек, прост в использовании.
  • OptionTree — позволяет создавать страницы настроек с визуальным интерфейсом и множеством опций.

Пример использования Redux Framework:

if (!class_exists('Redux')) {
    return;
}

$opt_name = 'wpapp_options';

$args = array(
    'opt_name' => $opt_name,
    'menu_title' => 'WPApp Настройки',
    'page_title' => 'Настройки плагина WPApp',
    'menu_type' => 'menu',
);

Redux::setArgs($opt_name, $args);

Redux::setSection($opt_name, array(
    'title'  => 'Основные настройки',
    'id'     => 'main_section',
    'fields' => array(
        array(
            'id'    => 'text_field',
            'type'  => 'text',
            'title' => 'Текстовое поле',
        ),
        array(
            'id'    => 'checkbox',
            'type'  => 'checkbox',
            'title' => 'Включить функцию',
        ),
    ),
));

Вывод сохранённых настроек в коде плагина

После того, как пользователь сохранил настройки, их нужно получить и использовать в вашем плагине. Для этого применяем функцию get_option:

$options = get_option('wpapp_options');
if (!empty($options['wpapp_text_field'])) {
    $text = esc_html($options['wpapp_text_field']);
    // Используем $text в плагине
}

if (!empty($options['wpapp_checkbox'])) {
    // Включён чекбокс — активируем функцию
}

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

Наш каталог плагинов WordPress