⌨️ Як додати свою секцію на сторінку налаштувань WordPress

Стандартні сторінки налаштувань WordPress, «Загальні», «Читання», «Обговорення», покривають базові потреби сайту. Але щойно ви пишете плагін або допрацьовуєте тему під клієнта, вбудованого набору полів перестає вистачати. Потрібен блок із власними опціями: ключ API, текст для футера, перемикач режиму.

Створювати окрему сторінку в адмінці заради двох полів, зайве. Значно чистіше додати свою секцію на вже наявну сторінку налаштувань, туди ж, де знаходяться дефолтні опції WordPress. Для цього в Settings API передбачена одна функція: add_settings_section.

Розберемо її синтаксис, параметри та зберемо робочий приклад із секцією та полем, від хука admin_init до виведення в адмінці. Без зайвих абстракцій: тільки те, що ви скопіюєте та запустите в себе.

💡 Швидкий огляд:

• Визначте цільову сторінку (general, reading, writing, discussion, media або кастомну), slug знадобиться в четвертому параметрі
• Зареєструйте секцію через add_settings_section() на хуку admin_init: задайте ID, заголовок і callback для пояснювального тексту
• Прив’яжіть поля до секції через add_settings_field(), а саму опцію збережіть через register_setting()
• Викличте do_settings_sections() у колбеку сторінки для кастомних сторінок, секція відрендериться автоматично

Що таке Settings API та навіщо він потрібен

Settings API з’явився у WordPress 2.7 і відтоді залишається стандартним способом додавати налаштування в адмінку. Суть проста: замість ручного виведення <form> та обробки $_POST ви описуєте секції та поля через функції, а WordPress сам рендерить розмітку, обробляє збереження та перевіряє nonce.

Три кити Settings API:

• register_setting(), реєструє опцію в wp_options;
• add_settings_section(), створює блок (секцію) із заголовком;
• add_settings_field(), додає конкретне поле в секцію.

Саме add_settings_section відповідає за «контейнер», візуальний блок, який групує кілька полів під спільним заголовком на сторінці налаштувань. Без неї поля просто нікуди класти.

Синтаксис add_settings_section

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

1
add_settings_section(
2
    string $id,
3
    string $title,
4
    callable $callback,
5
    string $page,
6
    array  $args = array()
7
);

Функція нічого не повертає. Вона реєструє секцію в глобальному масиві $wp_settings_sections, звідки WordPress забирає її під час виклику do_settings_sections() на цільовій сторінці. Виклик add_settings_section без подальшого do_settings_sections на кастомній сторінці, секція мовчки не відрендериться.

Важливий нюанс: add_settings_section лише описує блок. Самі поля додаються окремими викликами add_settings_field із зазначенням ID секції в п’ятому параметрі. Без полів секція залишиться порожньою обгорткою, іноді це потрібно для текстового пояснення, але на практиці поруч майже завжди йде хоча б одне поле.

Параметри функції, що передавати

$id (string, обов’язковий), унікальний slug секції. Використовуйте малі літери, цифри та підкреслення: my_plugin_main_section. Цей самий ID ви вкажете в add_settings_field, щоб «прив’язати» поле до секції, і він же фігурує в HTML-атрибуті id тега-обгортки.

$title (string, обов’язковий), заголовок секції, який бачить адміністратор. Виводиться як <h2> усередині сторінки налаштувань. Пишіть українською для української адмінки: «Настройки интеграции с CRM», а не my_plugin_crm_settings.

$callback (callable, обов’язковий), ім’я функції, яка виводить через echo пояснювальний текст між заголовком секції та полями. Сигнатура: function my_callback($args), де $args, масив із ключами id, title і callback. Якщо пояснення не потрібне, передайте '__return_false'.

$page (string, обов’язковий), slug сторінки налаштувань, куди додається секція. Вбудовані сторінки WordPress: general, reading, writing, discussion, media. Для кастомної сторінки, slug, переданий у add_options_page(). ⚠ Сторінки misc і privacy видалені з ядра (deprecated), WordPress автоматично перенаправить misc → general, privacy → reading, але краще не покладатися на цю поведінку.

$args (array, опціональний, з WordPress 6.1.0), масив для кастомізації HTML-обгортки секції:

Аргумент $args працює тільки під час виклику do_settings_sections(). Якщо помилково використовується do_settings_fields(), масив ігнорується, і before_section/after_section мовчки не спрацюють.

Практичний приклад: секція з полем на сторінці «Загальні»

Зберемо готовий фрагмент для functions.php або власного плагіна. Код додає секцію «Налаштування сайту-візитівки» на сторінку options-general.php з одним текстовим полем, наприклад, для номера телефону у футері.

1
/**
2
 * Додає кастомну секцію та поле на сторінку «Загальні».
3
 */
4
function sdstudio_add_visiting_card_section() {
5
    // 1. Секція
6
    add_settings_section(
7
        'visiting_card_section',               // ID секції
8
        'Visiting Card Settings',             // Заголовок
9
        'sdstudio_visiting_card_section_cb',   // Callback-пояснення
10
        'general',                             // Сторінка «Загальні»
11
        array(
12
            'before_section' => '<div class="visiting-card-wrapper">',
13
            'after_section'  => '</div>',
14
        )
15
    );
16
 
17
    // 2. Поле
18
    add_settings_field(
19
        'footer_phone',                        // ID поля
20
        'Footer Phone Number',                    // Лейбл
21
        'sdstudio_footer_phone_field_cb',      // Callback — рендерить <input>
22
        'general',                             // Та сама сторінка
23
        'visiting_card_section'                // До якої секції прив'язати
24
    );
25
 
26
    // 3. Реєстрація опції
27
    register_setting( 'general', 'footer_phone' );
28
}
29
add_action( 'admin_init', 'sdstudio_add_visiting_card_section' );
30
 
31
/**
32
 * Пояснювальний текст над полями секції.
33
 */
34
function sdstudio_visiting_card_section_cb( $args ) {
35
    ?>
36
    <p id="<?php echo esc_attr( $args['id'] ); ?>">
37
        Contact details displayed in the site footer.
38
    </p>
39
    <?php
40
}
41
 
42
/**
43
 * Рендерить текстове поле вводу.
44
 */
45
function sdstudio_footer_phone_field_cb() {
46
    $value = get_option( 'footer_phone', '' );
47
    printf(
48
        '<input type="text" id="footer_phone" name="footer_phone" value="%s" class="regular-text" />',
49
        esc_attr( $value )
50
    );
51
}
52

Після додавання коду зайдіть в адмінку: Налаштування → Загальні, під стандартними полями з’явиться секція «Налаштування сайту-візитівки» з полем «Телефон у футері». Збережіть сторінку, значення запишеться в wp_options.

Код розміщують у functions.php активної теми або, що правильніше, в окремому плагіні. Плагін виживає при зміні теми, а functions.php, ні. Якщо секція потрібна тільки поки активна конкретна тема, functions.php допустимий; у всіх інших випадках, тільки плагін.

Аргумент $args: що змінилося в WordPress 6.1

До версії 6.1 у add_settings_section було рівно чотири параметри, обгортку секції доводилося «підфарбовувати» через CSS за ID або лізти в буфер виведення. Починаючи з 6.1 додався п’ятий параметр $args, і тепер HTML-обрамлення задається прямо під час реєстрації секції:

• before_section, div-обгортка або пояснювальна плашка ДО вмісту;
• after_section, закривальний тег або підказка ПІСЛЯ вмісту;
• section_class, власний клас, якщо стандартного form-table недостатньо.

Приклад із пояснювальною плашкою та кастомним класом:

1
add_settings_section(
2
    'api_keys_section',
3
    'API Keys',
4
    'sdstudio_api_keys_section_cb',
5
    'general',
6
    array(
7
        'before_section' => '<div class="notice notice-info inline"><p>Store keys in wp-config.php, override here only.</p></div>',
8
        'after_section'  => '',
9
        'section_class'  => 'api-keys-section',
10
    )
11
);

Що важливо пам’ятати: after_section не виводиться, якщо секція порожня, тобто коли всередині неї немає зареєстрованих полів. Якщо розраховуєте на закривальний </div>, переконайтеся, що через add_settings_field додано хоча б одне поле. І головне: do_settings_sections(), а не do_settings_fields(), останній проігнорує $args повністю.

Перед використанням before_section / after_section перевірте версію WordPress, на сайтах, молодших за 6.1, передача п’ятого параметра викличе фатальну помилку. Безпечний підхід: обернути виклик у global $wp_version або використати function_exists для перевірки наявності хуків.

⁉️🤔 Часті запитання

Чи можна обійтися без add_settings_section і додавати поля напряму?

Формально, ні. Поля реєструються через add_settings_field(), а п’ятий параметр цієї функції вимагає ID секції. Якщо секції немає, поле не відрендериться. Для одиничного поля можна створити секцію з порожнім заголовком і callback’ом '__return_false', секція буде невидимою, а поле, робочим.

Чим відрізняється add_settings_section від add_settings_field?

Секція — це контейнер із заголовком і пояснювальним текстом. Поле, конкретний елемент введення (input, select, checkbox) усередині секції. Одна секція може містити скільки завгодно полів, усі вони групуються під одним заголовком і зберігаються одним натисканням кнопки «Зберегти».

Що буде, якщо вказати slug неіснуючої сторінки в $page?

Секція зареєструється в $wp_settings_sections, але ніколи не відрендериться, WordPress не знає, на якій сторінці її виводити. Помилки при цьому не буде, секція просто «повисне в повітрі». Перевіряйте slug: для вбудованих сторінок це general / reading / writing / discussion / media; для кастомних, точний slug із add_menu_page або add_options_page.

Чи можна додати секцію на сторінку чужого плагіна?

Так, якщо знаєте slug його сторінки. Передайте його в $page, і секція з’явиться на чужій сторінці налаштувань. Але це крихке рішення: автор плагіна може змінити slug в оновленні, і ваша секція «відвалиться». Використовуйте тільки для власних проєктів або коли альтернатив немає.

Що робить хук admin_init і чому add_settings_section викликають саме на ньому?

admin_init спрацьовує при кожному запиті до адмінки ДО рендерингу сторінки. Це правильний момент для реєстрації налаштувань: секції та поля мають бути оголошені до того, як WordPress почне збирати форму. Якщо викликати add_settings_section пізніше, наприклад, усередині колбеку сторінки, секція не потрапить у $wp_settings_sections і не відобразиться.

Своя секція чи окрема сторінка: що обрати

Додати секцію на general простіше: менше коду, користувач бачить налаштування там же, де редагує заголовок сайту. Але коли опцій більше трьох-чотирьох, секція роздуває стандартну сторінку та плутає адміністратора.

Правило просте: одна-дві опції, логічно пов’язані із загальною сторінкою (телефон у футері, ключ API для коментарів),, секція на general. Три та більше опцій, самостійний функціонал (слайдер, інтеграція з CRM, сітка тарифів), окрема сторінка через add_options_page(). В обох випадках add_settings_section, та сама цеглина, з якої починається збірка.

Перш ніж копіювати код, переконайтеся, що WordPress оновлено до актуальної версії. Масив $args, section_class та обгортки before_section/after_section вимагають щонайменше 6.1, а сама функція живе в ядрі з версії 2.7. Два десятки років зворотної сумісності, не привід сидіти на застарілому рушії.