WordPress Settings API: как создать страницу настроек плагина
WordPress Settings API помогает создать страницу настроек плагина или темы без ручной обработки формы. Вы добавите меню, зарегистрируете одну опцию-массив, выведете 5 типов полей и проверите ввод. В конце готовый PHP-файл соберет все части в рабочий плагин.
- Что такое Settings API и когда он нужен
- Из чего состоит страница настроек: страница, секция, поле, опция
- Регистрация страницы в меню
- Регистрация опции через register_setting
- Секции и поля
- Вывод формы через options.php
- Очистка и проверка ввода
- Чтение настроек в теме или плагине
- Ошибки при работе с Settings API
- Полный пример плагина
Что такое 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-settings | Slug меню и страницы вывода секций |
| Группа | 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() | Проверить диапазон |
| URL | esc_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 сохраняет их согласованно.
- В каталоге установки WordPress откройте
wp-content/pluginsи создайте папкуitws-settings-demo. - Создайте в ней файл
itws-settings-demo.php. - Вставьте полный код из листинга и сохраните файл.
- В админке WordPress активируйте плагин «ITWS Settings Demo».
- Откройте «Настройки» → «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(), а перед выводом экранируйте каждое значение подходящей функцией.
Совет от нашей редакции: связанные параметры храните в одной опции-массиве, пока для них не понадобятся разные права доступа или независимое сохранение.
Популярное за неделю
- Как создать сайт самому в 2026: 4 способа + пошаговая инструкция 34 мин чтения
- Лучшие конструкторы для создания сайтов — плюсы, минусы и сравнения 22 мин чтения
- Как правильно редактировать шаблоны WordPress 4 мин чтения
- Что такое .htaccess в WordPress 5 мин чтения
- Как увеличить максимальный размер загружаемых файлов в WordPress 4 мин чтения
- Как восстановить сайт WordPress из резервной копии базы данных 14 мин чтения
Комментарии