Skip to content
🛠 Додавання довільного поля в налаштування WordPress: add_settings_field
WordPressВеб-розробка
6 хв1,255 слів

🛠 Додавання довільного поля в налаштування WordPress: add_settings_field

Стандартні налаштування 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

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

1add_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
2function 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
7function 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
20function 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}
41add_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', '' );
2if ( $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-ів, груп полів і кастомних сторінок налаштувань. А з яким типом поля ви працюєте найчастіше, напишіть у коментарях.

Редакція
РедакціяРедакційна команда→ Усі публікації

Професійна команда авторів та редакторів, що спеціалізуються на створенні якісного контенту.