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

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

Почему стоит использовать Settings API для настроек плагина

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

Стандартизация — интерфейс настроек будет выглядеть и работать как в любом другом плагине;
Автоматическая валидация и сохранение данных;
Обеспечение безопасности данных при сохранении;
Возможность легко добавлять, удалять и изменять поля настроек.

Использование Settings API заметно упрощает поддержку кода и улучшает пользовательский опыт.

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

Рассмотрим пример создания страницы настроек с несколькими полями: текстовое поле, чекбокс и селект.

Регистрация страницы настроек и секции

Сначала добавим меню и зарегистрируем настройки. В файле вашего плагина добавьте следующий код:

function wporders_register_settings() {
    // Регистрируем группу настроек
    register_setting('wporders_options_group', 'wporders_options', 'wporders_validate_options');

    // Добавляем секцию настроек
    add_settings_section(
        'wporders_main_section',
        'Основные настройки',
        'wporders_main_section_callback',
        'wporders'
    );

    // Добавляем поля
    add_settings_field(
        'wporders_text_field',
        'Текстовое поле',
        'wporders_text_field_callback',
        'wporders',
        'wporders_main_section'
    );

    add_settings_field(
        'wporders_checkbox_field',
        'Чекбокс',
        'wporders_checkbox_field_callback',
        'wporders',
        'wporders_main_section'
    );

    add_settings_field(
        'wporders_select_field',
        'Выпадающий список',
        'wporders_select_field_callback',
        'wporders',
        'wporders_main_section'
    );
}
add_action('admin_init', 'wporders_register_settings');

function wporders_add_admin_menu() {
    add_menu_page(
        'Настройки WPOrders',
        'WPOrders',
        'manage_options',
        'wporders',
        'wporders_options_page'
    );
}
add_action('admin_menu', 'wporders_add_admin_menu');

Колбэки для секции и полей

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

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

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

function wporders_checkbox_field_callback() {
    $options = get_option('wporders_options');
    $checked = isset($options['checkbox_field']) && $options['checkbox_field'] === '1' ? 'checked' : '';
    echo '<input type="checkbox" name="wporders_options[checkbox_field]" value="1" ' . $checked . ' /> Включить опцию';
}

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

Валидация и сохранение данных

Очень важно валидировать и очищать данные перед сохранением. Вот пример функции валидации:

function wporders_validate_options($input) {
    $valid = array();

    // Текстовое поле - очищаем от тегов
    if (isset($input['text_field'])) {
        $valid['text_field'] = sanitize_text_field($input['text_field']);
    }

    // Чекбокс - логика 0 или 1
    $valid['checkbox_field'] = isset($input['checkbox_field']) && $input['checkbox_field'] === '1' ? '1' : '0';

    // Селект - проверяем по списку допустимых значений
    $allowed_values = array('option1', 'option2', 'option3');
    if (isset($input['select_field']) && in_array($input['select_field'], $allowed_values, true)) {
        $valid['select_field'] = $input['select_field'];
    } else {
        $valid['select_field'] = 'option1'; // Значение по умолчанию
    }

    return $valid;
}

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

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

function wporders_options_page() {
    if (!current_user_can('manage_options')) {
        return;
    }

    // Проверяем наличие сообщений об обновлении
    if (isset($_GET['settings-updated'])) {
        add_settings_error('wporders_messages', 'wporders_message', 'Настройки сохранены', 'updated');
    }

    settings_errors('wporders_messages');

    echo '<div class="wrap">';
    echo '<h1>Настройки плагина WPOrders</h1>';
    echo '<form action="options.php" method="post">';

    settings_fields('wporders_options_group');
    do_settings_sections('wporders');
    submit_button('Сохранить настройки');

    echo '</form></div>';
}

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

При работе с настройками плагина и пользовательским вводом важно соблюдать несколько правил безопасности:

Всегда проверяйте права пользователя с помощью current_user_can() перед выводом и сохранением настроек.
Используйте nonce-поля, которые автоматически добавляются функцией settings_fields() для защиты от CSRF.
Обязательно валидируйте и очищайте все данные перед сохранением, чтобы избежать XSS и других уязвимостей.
Не выводите данные без экранирования, используйте функции esc_html(), esc_attr() и другие.

Как расширять функционал страницы настроек

После того, как базовая страница настроек создана, её можно расширять:

Добавлять новые секции и поля, например, для интеграции с внешними сервисами или управления логикой плагина.
Использовать кастомные контролы для удобства — например, цветовые пикеры, загрузчики файлов, переключатели.
Добавлять динамические поля с помощью JavaScript, если требуется более сложный UI.
Создавать страницы с несколькими вкладками настроек для удобства пользователей.

Все это реализуется с помощью тех же хуков и API WordPress.

Примеры полезных плагинов с похожим функционалом

Если хотите посмотреть готовые решения и вдохновиться, обратите внимание на такие плагины:

Contact Form 7 — содержит страницу настроек с несколькими секциями и валидацией.
WooCommerce — огромный плагин с комплексными настройками, полезно посмотреть структуру и подходы.
Advanced Custom Fields — примеры сложных интерфейсов настроек.

Итог

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

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