WordPress Settings API: как создать страницу настроек плагина

WordPress Settings API помогает создать страницу настроек плагина или темы без ручной обработки формы. Вы добавите меню, зарегистрируете одну опцию-массив, выведете 5 типов полей и проверите ввод. В конце готовый PHP-файл соберет все части в рабочий плагин.

Что такое Settings API и когда он нужен

WordPress Settings API связывает страницу админки, секции, поля и сохранение данных. Используйте его, когда плагину или теме нужна собственная форма настроек.

ИнструментНазначениеКогда выбирать
Settings APIРегистрирует настройки, секции и поляНужна страница настроек плагина
Options APIЧитает и меняет значения через get_option() и update_option()Коду нужно получить или сохранить опцию
Customizer APIПоказывает параметры темы с визуальным предпросмотромПользователь меняет внешний вид сайта

Options API работает с данными в коде, а Customizer API показывает опции темы рядом с предпросмотром сайта. Settings API нужен для экрана, где пользователь вводит эти значения.

Ручная обработка $_POST требует отдельно проверять nonce, права пользователя, имя опции и запись в базу. Settings API отправляет форму в options.php, где WordPress проверяет nonce, полномочия и список разрешенных опций. Функция settings_fields() добавляет служебные поля формы, включая nonce.

Callback sanitize_callback очищает вход, а зарегистрированная опция получает стандартный путь сохранения WordPress.

Связанные параметры храните в одном массиве: один вызов get_option() вернет все значения, а общий callback проверит их согласованно.

Из чего состоит страница настроек: страница, секция, поле, опция

Страница задает место в меню, секция объединяет поля, поле выводит элемент формы, а опция хранит данные. Идентификаторы связывают эти части между собой.

ЧастьИдентификаторРоль
Страницаitws-settingsSlug меню и страницы вывода секций
Группаitws_groupСвязь register_setting() и settings_fields()
Секцияitws_mainОбъединяет поля
Опцияitws_optionsХранит массив в базе

Подключите страницу к хуку admin_menu, а опцию, секцию и поля зарегистрируйте на admin_init. При сохранении WordPress снова вызывает admin_init, поэтому настройки остаются зарегистрированными.

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

Функция add_options_page() помещает экран в раздел «Настройки». Передайте ей заголовок, подпись пункта, capability, slug и callback вывода. Capability manage_options ограничивает экран пользователями, которые могут управлять настройками сайта. После активации плагина пункт «ITWS» появится у пользователя с нужным правом.

Для отдельного пункта верхнего уровня используйте add_menu_page() внутри того же хука. Выберите только один способ регистрации с этим slug, иначе меню получит дублирующий пункт.

add_action('admin_menu', 'itws_add_page');

function itws_add_page() {
    add_options_page(
        'Настройки ITWS',
        'ITWS',
        'manage_options',
        'itws-settings',
        'itws_render_page'
    );

    // Для пункта верхнего уровня используйте этот вызов вместо add_options_page():
    /*
    add_menu_page(
        'Настройки ITWS',
        'ITWS',
        'manage_options',
        'itws-settings',
        'itws_render_page',
        'dashicons-admin-generic'
    );
    */
}

Регистрация опции через register_setting

Функция register_setting() связывает группу сохранения с именем опции. Третий аргумент принимает массив параметров.

register_setting('itws_group', 'itws_options', [
    'type'              => 'array',
    'description'       => 'Настройки демонстрационного плагина',
    'sanitize_callback' => 'itws_sanitize_options',
    'show_in_rest'      => false,
    'default'           => itws_defaults(),
]);
  • type описывает общий тип значения.
  • description хранит описание опции.
  • sanitize_callback очищает и проверяет вход.
  • show_in_rest разрешает публикацию опции через REST API.
  • default задает начальное значение.

Параметр type не проверяет ключи внутри массива. Callback должен принять только разрешенные значения и вернуть очищенный массив. Функцию itws_defaults() с начальными значениями содержит полный пример плагина.

Параметр show_in_rest позволяет открыть настройку через маршрут /wp/v2/settings. Для REST-запросов задайте схему элементов массива. В примере REST-доступ отключен.

Секции и поля

Секция объединяет поля по смыслу, а callback поля печатает конкретный элемент формы. Передайте один и тот же slug страницы во все связанные вызовы.

add_settings_section(
    'itws_main',
    'Основные параметры',
    'itws_render_section',
    'itws-settings'
);

add_settings_field(
    'itws_title',
    'Заголовок',
    'itws_render_field',
    'itws-settings',
    'itws_main',
    [
        'key'       => 'title',
        'label_for' => 'itws_title',
    ]
);

add_settings_section() регистрирует заголовок и callback секции. add_settings_field() регистрирует подпись, callback поля и дополнительные аргументы.

Callback поля самостоятельно печатает элемент input, его имя и текущее значение. Аргумент label_for связывает подпись с атрибутом id. Имя itws_options[title] сохраняет ключ title внутри опции itws_options. Для radio задайте одно имя, отдельный id и подпись каждого варианта.

Вывод формы через options.php

Форма отправляет данные в options.php.

Служебные поля добавьте через settings_fields(), секции выведите через do_settings_sections(), а кнопку создайте функцией submit_button().

<form method='post' action='<?php echo esc_url(admin_url('options.php')); ?>'>
    <?php
    settings_fields('itws_group');
    do_settings_sections('itws-settings');
    submit_button('Сохранить настройки');
    ?>
</form>

settings_fields() печатает nonce и имя группы. Строка itws_group должна совпадать с первым аргументом register_setting(), а itws-settings связывает вывод секций с регистрацией секций и полей. После отправки ядро возвращает пользователя на экран настроек, поэтому отдельный обработчик $_POST для формы не нужен.

Очистка и проверка ввода

Очистка приводит данные к нужному формату, а проверка решает, можно ли сохранять значение. Callback учитывает отсутствующие ключи, потому что браузер отправляет не все элементы формы.

ТипФункцияПроверка
Однострочный текстsanitize_text_field()Проверить пустое значение
Многострочный текстsanitize_textarea_field()Задать правило для пустого поля
Целое числоabsint()Проверить диапазон
URLesc_url_raw()Разрешить нужный протокол
Select и radioПроверка строкиСравнить с белым списком
CheckboxПреобразованиеОтсутствие ключа считать значением 0

Функция absint() превращает отрицательное число в положительное, поэтому отдельно проверяйте диапазон. esc_url_raw() очищает URL для хранения, а при выводе используйте esc_url(). Снятый checkbox браузер не отправляет, поэтому записывайте 0, когда ключ отсутствует.

Select и radio проверяйте на сервере: пользователь может отправить значение, которого нет в форме. При недопустимом выборе верните прежнее значение и зарегистрируйте сообщение через add_settings_error(). В callback страницы вызовите settings_errors('itws_options') перед формой, чтобы пользователь увидел причину отказа.

add_settings_error(
    'itws_options',
    'itws_invalid_layout',
    'Недопустимый вариант выбора. Прежнее значение сохранено.',
    'error'
);

Чтение настроек в теме или плагине

Для чтения настроек передайте имя опции в get_option(), а вторым аргументом задайте значение до первого сохранения.

Слияние с itws_defaults() добавит ключи, которых нет в старой записи. При выводе заголовка используйте esc_html(), а внутри атрибута – esc_attr(). Заключите значение атрибута в кавычки, чтобы пробелы не разбили его.

$options = get_option('itws_options', itws_defaults());
$options = is_array($options) ? $options : [];
$options = array_merge(itws_defaults(), $options);

echo '<h2>' . esc_html($options['title']) . '</h2>';
printf('<input value="%s">', esc_attr($options['title']));

Для textarea используйте esc_textarea(), для URL – esc_url(), экранируя данные непосредственно в момент вывода.

Ошибки при работе с Settings API

Проблемы чаще всего связаны с несовпадением идентификаторов или неполной обработкой массива. Сопоставьте группу, slug страницы, секцию и имена полей.

  • Error: The %s options page is not in the allowed options list. WordPress показывает это сообщение, если переданная группа не зарегистрирована в списке разрешенных настроек. Сопоставьте settings_fields('itws_group') с register_setting('itws_group', 'itws_options', ...) и проверьте регистрацию на admin_init.
  • Поля не выводятся. Сравните slug в add_settings_section(), add_settings_field() и do_settings_sections(). Затем проверьте ID секции.
  • Checkbox не выключается. Записывайте 0, когда ключ отсутствует во входных данных.
  • Поля перезаписывают друг друга. Используйте имена itws_options[title], itws_options[layout] и другие ключи одного массива.
  • Настройки исчезают после другой формы. Сохранение массива заменяет весь массив. Объединяйте разрешенные ключи с прежними значениями или разделяйте опции между экранами.

Группа настроек не привязана к slug меню: форма отправляет данные в options.php. Одна опция-массив подходит связанным параметрам одной страницы. Разные права доступа или независимое сохранение требуют отдельных опций.

Полный пример плагина

Файл добавляет страницу в раздел «Настройки», одну секцию и поля text, textarea, checkbox, select и radio. Все значения хранятся в опции itws_options, поэтому callback сохраняет их согласованно.

  1. В каталоге установки WordPress откройте wp-content/plugins и создайте папку itws-settings-demo.
  2. Создайте в ней файл itws-settings-demo.php.
  3. Вставьте полный код из листинга и сохраните файл.
  4. В админке WordPress активируйте плагин «ITWS Settings Demo».
  5. Откройте «Настройки» → «ITWS». На странице появятся 5 полей и кнопка сохранения.

Если плагин вызывает ошибку и админка недоступна, переименуйте папку itws-settings-demo через доступ к файлам. WordPress перестанет загружать плагин.

<?php
/**
 * Plugin Name: ITWS Settings Demo
 * Description: Пример страницы настроек через Settings API.
 */

if (!defined('ABSPATH')) {
    exit;
}

function itws_defaults() {
    return [
        'title'       => 'Новости проекта',
        'description' => '',
        'enabled'     => 0,
        'layout'      => 'compact',
        'audience'    => 'all',
    ];
}

function itws_get_options() {
    $saved = get_option('itws_options', itws_defaults());
    return array_merge(itws_defaults(), is_array($saved) ? $saved : []);
}

function itws_choices($key) {
    if ($key === 'layout') {
        return ['compact' => 'Компактный', 'expanded' => 'Развернутый'];
    }
    if ($key === 'audience') {
        return ['all' => 'Все посетители', 'members' => 'Только зарегистрированные'];
    }
    return [];
}

function itws_input_string($input, $key) {
    return isset($input[$key]) && is_string($input[$key]) ? $input[$key] : '';
}

function itws_sanitize_options($input) {
    $input = is_array($input) ? $input : [];
    $old = itws_get_options();
    $clean = itws_defaults();

    $title = sanitize_text_field(itws_input_string($input, 'title'));
    if ($title === '') {
        $clean['title'] = $old['title'];
        add_settings_error('itws_options', 'itws_title_required', 'Введите непустой заголовок. Прежнее значение сохранено.', 'error');
    } else {
        $clean['title'] = $title;
    }

    $clean['description'] = sanitize_textarea_field(itws_input_string($input, 'description'));
    $clean['enabled'] = in_array($input['enabled'] ?? null, ['1', 1], true) ? 1 : 0;

    foreach (['layout', 'audience'] as $key) {
        $value = itws_input_string($input, $key);
        $choices = itws_choices($key);
        if (array_key_exists($value, $choices)) {
            $clean[$key] = $value;
        } else {
            $clean[$key] = $old[$key];
            add_settings_error('itws_options', 'itws_invalid_' . $key, 'Недопустимый вариант выбора. Прежнее значение сохранено.', 'error');
        }
    }
    return $clean;
}

add_action('admin_init', 'itws_register_settings');
function itws_register_settings() {
    register_setting('itws_group', 'itws_options', [
        'type'              => 'array',
        'description'       => 'Настройки демонстрационного плагина',
        'sanitize_callback' => 'itws_sanitize_options',
        'show_in_rest'      => false,
        'default'           => itws_defaults(),
    ]);

    add_settings_section('itws_main', 'Основные параметры', 'itws_render_section', 'itws-settings');
    foreach ([
        'title'       => 'Заголовок',
        'description' => 'Описание',
        'enabled'     => 'Включить вывод',
        'layout'      => 'Вид блока',
        'audience'    => 'Аудитория',
    ] as $key => $label) {
        $args = ['key' => $key];
        if ($key !== 'audience') {
            $args['label_for'] = 'itws_' . $key;
        }
        add_settings_field('itws_' . $key, $label, 'itws_render_field', 'itws-settings', 'itws_main', $args);
    }
}

add_action('admin_menu', 'itws_add_page');
function itws_add_page() {
    add_options_page('Настройки ITWS', 'ITWS', 'manage_options', 'itws-settings', 'itws_render_page');
}

function itws_render_section() {
    echo '<p>Задайте текст и параметры блока. Заголовок обязателен.</p>';
}

function itws_render_field($args) {
    $options = itws_get_options();
    $key = $args['key'];
    $id = 'itws_' . $key;
    $name = 'itws_options[' . $key . ']';
    $value = $options[$key];

    if ($key === 'title') {
        printf('<input type="text" class="regular-text" id="%s" name="%s" value="%s">', esc_attr($id), esc_attr($name), esc_attr($value));
    } elseif ($key === 'description') {
        printf('<textarea class="large-text" rows="4" id="%s" name="%s">%s</textarea>', esc_attr($id), esc_attr($name), esc_textarea($value));
    } elseif ($key === 'enabled') {
        printf('<input type="checkbox" id="%s" name="%s" value="1" %s>', esc_attr($id), esc_attr($name), checked(1, $value, false));
    } elseif ($key === 'layout') {
        printf('<select id="%s" name="%s">', esc_attr($id), esc_attr($name));
        foreach (itws_choices($key) as $choice => $label) {
            printf('<option value="%s" %s>%s</option>', esc_attr($choice), selected($value, $choice, false), esc_html($label));
        }
        echo '</select>';
    } else {
        echo '<fieldset><legend class="screen-reader-text">Аудитория</legend>';
        foreach (itws_choices($key) as $choice => $label) {
            $radio_id = $id . '_' . $choice;
            printf('<p><label for="%s"><input type="radio" id="%s" name="%s" value="%s" %s> %s</label></p>', esc_attr($radio_id), esc_attr($radio_id), esc_attr($name), esc_attr($choice), checked($value, $choice, false), esc_html($label));
        }
        echo '</fieldset>';
    }
}

function itws_render_page() {
    if (!current_user_can('manage_options')) {
        return;
    }
    ?>
    <div class="wrap">
        <h1><?php echo esc_html(get_admin_page_title()); ?></h1>
        <?php settings_errors('itws_options'); ?>
        <form method="post" action="<?php echo esc_url(admin_url('options.php')); ?>">
            <?php
            settings_fields('itws_group');
            do_settings_sections('itws-settings');
            submit_button('Сохранить настройки');
            ?>
        </form>
    </div>
    <?php
}

После активации откройте «Настройки» → «ITWS». Заполните заголовок и сохраните форму. После возврата выбранные значения останутся в полях. Если удалить заголовок, callback добавит сообщение через add_settings_error(), а settings_errors('itws_options') выведет его перед формой.

Снимите checkbox и сохраните форму повторно. Callback запишет 0, потому что отсутствующий ключ обработан отдельно. Плагин сохраняет параметры, но сам не выводит блок на сайте. В теме или другом плагине вызовите itws_get_options(), а перед выводом экранируйте каждое значение подходящей функцией.

Совет от нашей редакции: связанные параметры храните в одной опции-массиве, пока для них не понадобятся разные права доступа или независимое сохранение.

Комментарии

Оставьте свой комментарий
Пока никто не оставил комментариев