Как добавить собственные настройки в админ-панель WordPress

Часто при разработке плагинов или тем возникает необходимость добавить собственные настройки, которые будут доступны в административной панели WordPress. Это позволяет сделать ваш продукт более гибким и удобным для пользователя. В этой статье мы подробно разберём, как добавить собственные настройки в админ-панель WordPress, используя встроенный API, и приведём практические примеры с кодом.

Понимание API настроек WordPress

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

• add_options_page() — добавляет страницу настроек в меню «Настройки»;
• register_setting() — регистрирует группу настроек для сохранения;
• add_settings_section() — добавляет логическую секцию на страницу настроек;
• add_settings_field() — добавляет отдельное поле ввода в секцию;
• settings_fields() и do_settings_sections() — выводят необходимые скрытые поля и секции на форме.

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

Добавление страницы настроек в меню админ-панели

Для начала создадим страницу настроек, которая будет доступна в разделе «Настройки».

function wpstock_add_settings_page() {
    add_options_page(
        'Настройки WPStock', // Заголовок страницы
        'WPStock Settings',  // Название в меню
        'manage_options',    // Права доступа
        'wpstock-settings',  // Уникальный slug
        'wpstock_render_settings_page' // Функция вывода
    );
}
add_action('admin_menu', 'wpstock_add_settings_page');

Функция wpstock_add_settings_page регистрирует пункт меню, который вызывает функцию wpstock_render_settings_page. Далее реализуем её.

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

Чтобы данные корректно сохранялись и валидировались, необходимо зарегистрировать их через API настроек.

function wpstock_register_settings() {
    register_setting('wpstock_options_group', 'wpstock_options', 'wpstock_sanitize_options');

    add_settings_section(
        'wpstock_main_section',
        'Основные настройки',
        'wpstock_main_section_cb',
        'wpstock-settings'
    );

    add_settings_field(
        'wpstock_text_field',
        'Текстовое поле',
        'wpstock_text_field_cb',
        'wpstock-settings',
        'wpstock_main_section'
    );

    add_settings_field(
        'wpstock_checkbox_field',
        'Флажок',
        'wpstock_checkbox_field_cb',
        'wpstock-settings',
        'wpstock_main_section'
    );
}
add_action('admin_init', 'wpstock_register_settings');

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

Функции обратного вызова для секции и полей

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

function wpstock_main_section_cb() {
    echo '<p>Настройки для плагина WPStock.</p>';
}

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

function wpstock_checkbox_field_cb() {
    $options = get_option('wpstock_options');
    $checked = !empty($options['checkbox_field']) ? 'checked' : '';
    echo '<input type="checkbox" name="wpstock_options[checkbox_field]" ' . $checked . ' /> Включить опцию';
}

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

Валидация и очистка данных

Очень важно обезопасить сохранение настроек, очистив входящие данные и проверив их корректность.

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

    if (isset($input['text_field'])) {
        $output['text_field'] = sanitize_text_field($input['text_field']);
    }

    $output['checkbox_field'] = !empty($input['checkbox_field']) ? 1 : 0;

    return $output;
}

Функция wpstock_sanitize_options гарантирует, что текстовое поле будет безопасным, а чекбокс сохранится как булево значение.

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

Реализуем функцию, которая выведет форму настроек на нашей странице.

function wpstock_render_settings_page() {
    ?>
    <div class="wrap">
        <h1>Настройки WPStock</h1>
        <form action="options.php" method="post">
            <?php
            settings_fields('wpstock_options_group');
            do_settings_sections('wpstock-settings');
            submit_button();
            ?>
        </form>
    </div>
    <?php
}

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

Пример использования сохранённых настроек в коде

Чтобы использовать эти настройки внутри темы или плагина, достаточно получить опции через get_option:

$wpstock_options = get_option('wpstock_options');
if (!empty($wpstock_options['checkbox_field'])) {
    // Выполнить действие, если опция включена
}
if (!empty($wpstock_options['text_field'])) {
    echo 'Текст из настроек: ' . esc_html($wpstock_options['text_field']);
}

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

Дополнительные советы по безопасности и удобству

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

• Всегда проверяйте права пользователя перед выводом или сохранением настроек (current_user_can('manage_options'));
• Используйте функции очистки данных, например, sanitize_text_field, esc_url, intval и т.п.;
• Для более сложных настроек рассмотрите использование кастомных классов или фреймворков настроек, например, CMB2 или Redux Framework;
• Добавляйте описания к полям, чтобы пользователи понимали назначение каждой настройки.

Следование этим рекомендациям поможет сделать настройки безопасными и удобными в использовании.