🛠 Добавление произвольного поля в настройки WordPress: add_settings

Q: Можно ли добавить несколько полей в одну секцию?

Да. Вызывайте add_settings_field() столько раз, сколько полей нужно. Передавайте один и тот же ID секции в параметре $section. Каждое поле получит уникальный $id и свой callback. Порядок вызовов add_settings_field() определяет порядок полей на странице.

Q: Нужно ли экранировать вывод в callback?

Да, обязательно. Используйте esc_attr() для значений атрибутов (value, name, id) и esc_html() для текста между тегами. Это защищает от XSS и гарантирует, что спецсимволы в сохранённом значении не сломают вёрстку.

Q: Можно ли добавить поле на страницу своего плагина?

Да. Создайте страницу через add_options_page() или add_menu_page(), затем зарегистрируйте секции и поля тем же способом. Slug вашей страницы подставьте в параметр $page у add_settings_field(). Механика ничем не отличается от стандартных страниц.

Q: Что делать, если значение не сохраняется после нажатия «Сохранить изменения»?

Почти наверняка вы пропустили register_setting(). Без этой функции WordPress не знает, что поле нужно сохранять, и игнорирует его при submit. Проверьте: первый параметр register_setting() должен совпадать с названием страницы (например, 'general'), а второй, с атрибутом name вашего поля.

Стандартные настройки WordPress покрывают большинство повседневных задач. Но рано или поздно появляется потребность в поле, которого в админке нет: телефон компании в разделе «Общие», API-ключ сервиса, поле для номера лицензии или текст в футер.

Разработчики тем и плагинов решают это через Settings API, набор функций WordPress для регистрации своих секций и полей на штатных страницах настроек. Ключевая из них, add_settings_field(): она добавляет произвольное поле в указанную секцию и страницу.

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

💡 Быстрый обзор:

Подготовьте окружение: создайте дочернюю тему или установите плагин Code Snippets, чтобы код не слетел при обновлении родительской темы.
Зарегистрируйте настройку: вызовите register_setting() на хуке admin_init, иначе WordPress не сохранит данные поля.
Добавьте секцию и поле: используйте add_settings_section() для нового блока и add_settings_field() для поля ввода внутри него.
Выведите значение: примените get_option() в любом месте шаблона, чтобы отобразить сохранённые данные на сайте.

Что такое add_settings_field и где применяется

Функция add_settings_field() появилась в WordPress 2.7.0 и с тех пор остаётся основным инструментом для расширения страниц настроек. Согласно документации WordPress, она добавляет новое поле в существующую секцию на одной из страниц админки.

Что это даёт на практике. Вы можете вывести дополнительное поле на любой стандартной странице: Общие (general), Написание (writing), Чтение (reading), Обсуждение (discussion) или Медиафайлы (media). А если создали собственную страницу настроек через add_options_page(), поле встанет и туда.

Типичные сценарии:

Поле «Контактный телефон» в разделе общих настроек, менеджеру не нужно лезть в код, чтобы обновить номер.
Поле API-ключа для своего плагина, пользователь вводит ключ в админке вместо правки wp-config.php.
Группа полей для кастомного раздела (телефон, email, адрес), через связку add_settings_section() + несколько add_settings_field().

Обратите внимание: add_settings_field() только выводит HTML поля. Само сохранение берёт на себя register_setting(), без неё WordPress проигнорирует введённые данные.

Синтаксис и параметры add_settings_field

Сигнатура функции, четыре обязательных параметра и два опциональных:

1 add_settings_field(
2     string $id,
3     string $title,
4     callable $callback,
5     string $page,
6     string $section = 'default',
7     array $args = array()
8 );

Разберём каждый параметр.

$id, уникальный идентификатор поля. Это значение станет HTML-атрибутом id тега <input>, который вы выводите в callback-функции. Используйте префикс во избежание конфликтов, например, myplugin_phone_number.

$title, подпись к полю, которая отображается в админке слева от самого input-а. Пишите понятно: «Контактный телефон», «API-ключ сервиса».

$callback, имя вашей функции, которая выводит HTML-код поля (input, textarea, select). Именно здесь вы пишете echo. Функция должна быть объявлена заранее, передавайте её как строку: 'my_field_callback'.

$page, slug страницы настроек. Стандартные значения: general, reading, writing, discussion и media. Если вы создали кастомную страницу, укажите её slug. Определяет, где появится поле.

$section (опциональный), slug секции, в которую попадёт поле. По умолчанию 'default' — это самая верхняя секция на странице. Если вы создали свою секцию через add_settings_section(), укажите её ID здесь.

$args (опциональный), массив дополнительных настроек. Поддерживаются ключи label_for (значение HTML-атрибута for у <label>) и class (CSS-класс для обёртки поля).

Все параметры и их поведение описаны в официальном руководстве по Settings API на WordPress.org.

Практический пример: добавляем текстовое поле в «Общие настройки»

Соберём всё вместе. Задача: вывести текстовое поле «Контактный телефон» на странице Настройки → Общие, сохранять введённое значение и получать его через get_option().

Код добавляется в functions.php дочерней темы или через плагин Code Snippets. Второй вариант безопаснее: сниппет не слетит при обновлении темы.

1 // Callback to output the section description
2 function my_custom_section_callback() {
3     echo 'Contact information for the organization. Phone number is displayed in the site footer.';
4 }
5  
6 // Callback to output the input field
7 function my_phone_field_callback() {
8     $value = get_option( 'my_contact_phone', '' );
9     echo '<input 
10         name="my_contact_phone" 
11         type="text" 
12         id="my_contact_phone" 
13         value="' . esc_attr( $value ) . '" 
14         class="regular-text" 
15         placeholder="+1 (555) 123-4567" 
16     />';
17 }
18  
19 // Register the section and field
20 function my_register_settings() {
21     // Register the setting — without this, data will not be saved
22     register_setting( 'general', 'my_contact_phone' );
23  
24     // Add a section to the General settings page
25     add_settings_section(
26         'my_contact_section',            // Section ID
27         'Contact Information',            // Section title
28         'my_custom_section_callback',    // Callback for description
29         'general'                         // Page slug
30     );
31  
32     // Add a field to the section
33     add_settings_field(
34         'my_contact_phone',              // Field ID
35         'Contact Phone',                  // Field label
36         'my_phone_field_callback',       // Callback to render the field
37         'general',                        // Page slug
38         'my_contact_section'             // Section ID
39     );
40 }
41 add_action( 'admin_init', 'my_register_settings' );

Что здесь происходит построчно. register_setting() указывает WordPress: значение поля my_contact_phone нужно сохранять как опцию в таблице wp_options при нажатии «Сохранить изменения» на странице general.

add_settings_section() создаёт новый блок с заголовком «Контакты организации» на странице общих настроек. Колбэк my_custom_section_callback() выводит текст-описание над полями секции.

add_settings_field() помещает наше поле внутрь этой секции и связывает его с колбэком my_phone_field_callback(), который рендерит <input type="text">. Функция get_option() подставляет сохранённое значение в атрибут value, а esc_attr() экранирует вывод.

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

После добавления кода откройте wp-admin/options-general.php, вы увидите результат:

Введите номер, нажмите Сохранить изменения, значение запишется в базу. Чтобы вывести телефон на сайте, используйте get_option() в любом месте шаблона:

1 $phone = get_option( 'my_contact_phone', '' );
2 if ( $phone ) {
3     echo '<a href="tel:' . esc_attr( $phone ) . '">' . esc_html( $phone ) . '</a>';
4 }

Куда помещать код и как тестировать

Три варианта размещения, от худшего к лучшему.

Родительская тема (functions.php). Не делайте так. При обновлении темы файл перезапишется, и ваша кастомизация исчезнет.

Дочерняя тема (functions.php** дочерней темы).** Рабочий вариант для правок, привязанных к конкретному сайту. Код переживёт обновления родительской темы.

Плагин Code Snippets. Лучший выбор для тестирования и долгосрочной поддержки. Сниппет можно включать/отключать одной кнопкой, не трогая файловую систему. Плюс вы получаете изоляцию: если сниппет вызовет фатальную ошибку, WordPress автоматически деактивирует его и сайт не упадёт.

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

Если поле не появляется, проверьте, что вы не перепутали ID секции в параметре $section у add_settings_field(). Частая ошибка: секция создана с одним ID, а в поле передан другой.

Видеоинструкция по теме

Для закрепления материала посмотрите видеоразбор Settings API от одного из WordPress-разработчиков. Показан полный цикл: регистрация секции, добавление поля, сохранение и вывод на сайте.

⁉️🤔 Частые вопросы

Можно ли добавить несколько полей в одну секцию?

Да. Вызывайте add_settings_field() столько раз, сколько полей нужно. Передавайте один и тот же ID секции в параметре $section. Каждое поле получит уникальный $id и свой callback. Порядок вызовов add_settings_field() определяет порядок полей на странице.

Как добавить select, textarea или чекбокс вместо текстового поля?

Тип поля задаётся внутри callback-функции через HTML. Для select формируете <select> с <option>, для textarea, тег <textarea>, для чекбокса, <input type="checkbox">. Значение сохраняется так же через register_setting() и извлекается через get_option(). Специфика только в HTML.

Нужно ли экранировать вывод в callback?

Да, обязательно. Используйте esc_attr() для значений атрибутов (value, name, id) и esc_html() для текста между тегами. Это защищает от XSS и гарантирует, что спецсимволы в сохранённом значении не сломают вёрстку.

Можно ли добавить поле на страницу своего плагина?

Да. Создайте страницу через add_options_page() или add_menu_page(), затем зарегистрируйте секции и поля тем же способом. Slug вашей страницы подставьте в параметр $page у add_settings_field(). Механика ничем не отличается от стандартных страниц.

Что делать, если значение не сохраняется после нажатия «Сохранить изменения»?

Почти наверняка вы пропустили register_setting(). Без этой функции WordPress не знает, что поле нужно сохранять, и игнорирует его при submit. Проверьте: первый параметр register_setting() должен совпадать с названием страницы (например, 'general'), а второй, с атрибутом name вашего поля.

Что в итоге: когда стоит расширять настройки админки

Settings API WordPress, зрелый и стабильный механизм: add_settings_field() не менялась с версии 2.7 и остаётся актуальной в 2026 году. Добавление своих полей в админку оправдано в трёх случаях:

Вы разрабатываете тему или плагин и хотите дать пользователю интерфейс для ввода данных, без правки кода.
Вам нужно поле с настройкой на уровне сайта (номер телефона, API-ключ, ID каталога), и оно должно быть доступно через админку, а не через wp-config.php.
Вы кастомизируете сайт клиента и хотите, чтобы менеджер мог сам менять данные без обращения к разработчику.

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

Начните с простого: добавьте одно текстовое поле по примеру выше. Когда освоите базовый поток, регистрация, callback, сохранение, вывод, переходите к select-ам, группам полей и кастомным страницам настроек. А с каким типом поля вы работаете чаще всего, напишите в комментариях.