Как создать настройки плагина WordPress с применением Options API

Автор: Степан Панин | Опубликовано: 01.11.2025

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

Что такое Options API и почему он важен для настроек плагина

Options API — это функционал WordPress, предназначенный для удобного сохранения, получения и обновления настроек в базе данных. Он работает с таблицей wp_options, позволяя хранить данные в формате ключ-значение. Использование Options API обеспечивает:

Автоматическую сериализацию сложных данных.
Удобное взаимодействие с настройками через функции get_option() и update_option().
Безопасность и стандартизацию — ваш плагин будет лучше интегрироваться с ядром WordPress и другими плагинами.

Рассмотрим, как на практике применить Options API для создания страницы настроек.

Создание страницы настроек плагина: шаг за шагом

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

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

add_action('admin_menu', 'wpfreecourses_register_settings_page');

function wpfreecourses_register_settings_page() {
    add_options_page(
        'Настройки моего плагина', // Название страницы
        'Мой плагин',               // Название меню
        'manage_options',           // Права доступа
        'wpfreecourses_plugin',     // Уникальный slug
        'wpfreecourses_render_settings_page' // Функция вывода
    );
}

Этот код добавит страницу настроек в меню «Настройки» в админке.

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

Далее нужно зарегистрировать опции и определить поля формы. Для этого используем хук admin_init:

add_action('admin_init', 'wpfreecourses_register_settings');

function wpfreecourses_register_settings() {
    // Регистрируем опцию
    register_setting('wpfreecourses_options_group', 'wpfreecourses_option_name');

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

    // Добавляем поле
    add_settings_field(
        'wpfreecourses_field_text',
        'Текстовое поле',
        'wpfreecourses_field_text_callback',
        'wpfreecourses_plugin',
        'wpfreecourses_main_section'
    );
}

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

function wpfreecourses_field_text_callback() {
    $option = get_option('wpfreecourses_option_name');
    echo '<input type="text" name="wpfreecourses_option_name[text]" value="' . esc_attr($option['text'] ?? '') . '" />';
}

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

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

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

function wpfreecourses_render_settings_page() {
    ?>
    <div class="wrap">
        <h1>Настройки моего плагина</h1>
        <form method="post" action="options.php">
            <?php
            settings_fields('wpfreecourses_options_group');
            do_settings_sections('wpfreecourses_plugin');
            submit_button();
            ?>
        </form>
    </div>
    <?php
}

Обратите внимание, что функции settings_fields() и do_settings_sections() отвечают за вывод скрытых полей безопасности и зарегистрированных секций и полей.

Расширение настроек: разные типы полей и валидация

Добавление чекбокса и селектора

Чтобы сделать настройки более функциональными, добавим чекбокс и выпадающий список. Для этого расширим функцию wpfreecourses_register_settings() новыми полями:

add_settings_field(
    'wpfreecourses_field_checkbox',
    'Включить функцию',
    'wpfreecourses_field_checkbox_callback',
    'wpfreecourses_plugin',
    'wpfreecourses_main_section'
);

add_settings_field(
    'wpfreecourses_field_select',
    'Выберите опцию',
    'wpfreecourses_field_select_callback',
    'wpfreecourses_plugin',
    'wpfreecourses_main_section'
);

function wpfreecourses_field_checkbox_callback() {
    $option = get_option('wpfreecourses_option_name');
    $checked = !empty($option['checkbox']) ? 'checked' : '';
    echo '<input type="checkbox" name="wpfreecourses_option_name[checkbox]" value="1" ' . $checked . ' />';
}

function wpfreecourses_field_select_callback() {
    $option = get_option('wpfreecourses_option_name');
    $value = $option['select'] ?? '';
    $options = [
        'option1' => 'Опция 1',
        'option2' => 'Опция 2',
        'option3' => 'Опция 3',
    ];
    echo '<select name="wpfreecourses_option_name[select]">';
    foreach ($options as $key => $label) {
        $selected = selected($value, $key, false);
        echo "<option value=\"$key\" $selected>$label</option>";
    }
    echo '</select>';
}

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

Валидация и фильтрация данных

Очень важно валидировать и фильтровать данные, которые пользователь вводит в настройки. Для этого в register_setting() можно добавить функцию валидации:

register_setting('wpfreecourses_options_group', 'wpfreecourses_option_name', 'wpfreecourses_validate_options');

function wpfreecourses_validate_options($input) {
    $output = [];

    // Текстовое поле — фильтруем как безопасный текст
    $output['text'] = sanitize_text_field($input['text'] ?? '');

    // Чекбокс — приводим к булевому значению
    $output['checkbox'] = !empty($input['checkbox']) ? 1 : 0;

    // Селектор — проверяем на допустимые значения
    $valid_select_options = ['option1', 'option2', 'option3'];
    if (in_array($input['select'] ?? '', $valid_select_options, true)) {
        $output['select'] = $input['select'];
    } else {
        $output['select'] = 'option1'; // Значение по умолчанию
    }

    return $output;
}

Это предотвратит сохранение некорректных или опасных данных.

Примеры популярных плагинов с использованием Options API

Многие известные плагины WordPress (например, Yoast SEO, Contact Form 7) используют Options API для хранения настроек. Это позволяет им легко масштабироваться и интегрироваться с WordPress.

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

Заключение: советы по разработке настроек плагина

Запомните ключевые моменты:

Всегда используйте register_setting() и хук admin_init для регистрации настроек.
Разбивайте настройки на логичные секции и поля.
Обязательно валидируйте и фильтруйте пользовательский ввод.
Используйте функции settings_fields() и do_settings_sections() для вывода формы.
Для сложных настроек можно использовать кастомные классы и объекты, но Options API остаётся основой.

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

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