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

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

Зачем нужны настройки в плагине WordPress

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

Создание страницы настроек — это не просто добавление меню в админке, но и правильное сохранение и валидация данных, обеспечение безопасности и удобства для пользователя.

Добавляем меню и страницу настроек

Для начала зарегистрируем меню в админке, где будет доступна наша страница настроек. Используем хук admin_menu и функцию add_options_page(). Ниже пример функции, которую мы назовём wpblog_add_plugin_menu:

function wpblog_add_plugin_menu() {
    add_options_page(
        'Настройки плагина WP-Blog', // Заголовок страницы
        'WP-Blog Настройки',           // Название меню
        'manage_options',              // Возможность доступа
        'wpblog-plugin-settings',     // Уникальный слаг
        'wpblog_render_settings_page' // Функция вывода контента
    );
}
add_action('admin_menu', 'wpblog_add_plugin_menu');

В функции wpblog_render_settings_page мы будем выводить форму настроек.

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

Страница настроек — это HTML-форма, которая отправляет данные на обработку. Используем встроенные функции WordPress для безопасности и удобства.

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

Здесь settings_fields выводит скрытые поля для безопасности, do_settings_sections — наши поля настроек, а submit_button — кнопку сохранения.

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

Для регистрации настроек используем хук admin_init и функции register_setting, add_settings_section, add_settings_field.

function wpblog_register_settings() {
    register_setting('wpblog_settings_group', 'wpblog_option_text');

    add_settings_section(
        'wpblog_main_section',
        'Основные настройки',
        'wpblog_main_section_callback',
        'wpblog-plugin-settings'
    );

    add_settings_field(
        'wpblog_option_text',
        'Текстовое значение',
        'wpblog_option_text_callback',
        'wpblog-plugin-settings',
        'wpblog_main_section'
    );
}
add_action('admin_init', 'wpblog_register_settings');

В этой функции мы создаём настройку с ключом wpblog_option_text, добавляем секцию и поле.

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

function wpblog_main_section_callback() {
    echo '<p>Здесь вы можете изменить основные параметры плагина WP-Blog.</p>';
}

Коллбэк для поля ввода

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

Валидация и безопасность настроек

При регистрации настройки register_setting можно указать функцию валидации, которая проверит и очистит ввод пользователя.

function wpblog_sanitize_option($input) {
    // Пример: ограничить длину строки
    $input = sanitize_text_field($input);
    if (strlen($input) > 50) {
        $input = substr($input, 0, 50);
        add_settings_error('wpblog_option_text', 'wpblog_error', 'Длина должна быть не более 50 символов.');
    }
    return $input;
}

И добавляем её при регистрации:

register_setting('wpblog_settings_group', 'wpblog_option_text', 'wpblog_sanitize_option');

Это гарантирует, что в базу попадут только корректные данные, а пользователю будет выведено сообщение об ошибке.

Пример: добавляем несколько типов полей

Часто в настройках нужны разные типы полей: чекбоксы, селекты, текстовые поля.

function wpblog_register_more_fields() {
    register_setting('wpblog_settings_group', 'wpblog_checkbox');
    register_setting('wpblog_settings_group', 'wpblog_select');

    add_settings_field('wpblog_checkbox', 'Включить функцию', 'wpblog_checkbox_callback', 'wpblog-plugin-settings', 'wpblog_main_section');
    add_settings_field('wpblog_select', 'Выберите вариант', 'wpblog_select_callback', 'wpblog-plugin-settings', 'wpblog_main_section');
}
add_action('admin_init', 'wpblog_register_more_fields');

function wpblog_checkbox_callback() {
    $value = get_option('wpblog_checkbox', 0);
    echo '<input type="checkbox" id="wpblog_checkbox" name="wpblog_checkbox" value="1" ' . checked(1, $value, false) . ' />';
}

function wpblog_select_callback() {
    $value = get_option('wpblog_select', 'option1');
    echo '<select id="wpblog_select" name="wpblog_select">
          <option value="option1" ' . selected($value, 'option1', false) . '>Вариант 1</option>
          <option value="option2" ' . selected($value, 'option2', false) . '>Вариант 2</option>
          <option value="option3" ' . selected($value, 'option3', false) . '>Вариант 3</option>
          </select>';
}

Так вы легко расширите настройки плагина и дадите пользователю удобный интерфейс.

Подключаем настройки к функционалу плагина

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

$text = get_option('wpblog_option_text', '');
if (get_option('wpblog_checkbox')) {
    // выполняем дополнительную логику
}

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

Полезные плагины и инструменты для работы с настройками

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

• Settings API Framework — облегчает работу с Settings API WordPress.
• CMB2 — мощный инструмент для создания метабоксов и форм настроек.
• Redux Framework — удобный фреймворк для сложных панелей настроек.

Но для простых плагинов и чтобы лучше понимать, как это работает, рекомендуем писать вручную, как в примерах выше.

Выводы

Добавление страницы настроек в плагин — важный этап, который повышает удобство использования и расширяет возможности. Используйте стандартный Settings API, продумывайте удобный интерфейс и всегда проверяйте ввод пользователя. Приведённые примеры кода помогут быстро создать собственную страницу настроек и интегрировать её в ваш плагин.