🛠 Dodawanie dowolnego pola w ustawieniach WordPress: add_settings_field

Standardowe ustawienia WordPress pokrywają większość codziennych zadań. Jednak prędzej czy później pojawia się potrzeba dodania pola, którego nie ma w panelu administracyjnym: telefonu firmy w sekcji „Ogólne", klucza API usługi, pola na numer licencji lub tekstu w stopce.

Twórcy motywów i wtyczek rozwiązują to za pomocą Settings API, zestawu funkcji WordPress do rejestrowania własnych sekcji i pól na standardowych stronach ustawień. Kluczową z nich jest add_settings_field(): dodaje ona dowolne pole do wskazanej sekcji i strony.

Do końca tego samouczka będzie Pan/Pani dysponować gotowym, działającym kodem, który wyświetla pole tekstowe w panelu administracyjnym, zapisuje wartość w bazie danych i pokazuje ją na stronie. Żadnych zewnętrznych wtyczek, tylko wbudowane API.

💡 Szybki przegląd:

• Proszę przygotować środowisko: utworzyć motyw potomny lub zainstalować wtyczkę Code Snippets, aby kod nie zniknął podczas aktualizacji motywu nadrzędnego.
• Proszę zarejestrować ustawienie: wywołać register_setting() na haku admin_init, w przeciwnym razie WordPress nie zapisze danych pola.
• Proszę dodać sekcję i pole: użyć add_settings_section() dla nowego bloku oraz add_settings_field() dla pola wewnątrz niego.
• Proszę wyświetlić wartość: zastosować get_option() w dowolnym miejscu szablonu, aby pokazać zapisane dane na stronie.

Czym jest add_settings_field i gdzie się ją stosuje

Funkcja add_settings_field() pojawiła się w WordPress 2.7.0 i od tego czasu pozostaje podstawowym narzędziem do rozszerzania stron ustawień. Zgodnie z dokumentacją WordPress, dodaje ona nowe pole do istniejącej sekcji na jednej ze stron panelu administracyjnego.

Co to daje w praktyce. Może Pan/Pani wyświetlić dodatkowe pole na dowolnej standardowej stronie: Ogólne (general), Pisanie (writing), Czytanie (reading), Dyskusja (discussion) lub Media (media). A jeśli utworzył Pan/Pani własną stronę ustawień przez add_options_page(), pole trafi również tam.

Typowe scenariusze:

• Pole „Telefon kontaktowy" w sekcji ustawień ogólnych, menedżer nie musi zaglądać do kodu, aby zaktualizować numer.
• Pole klucza API dla własnej wtyczki, użytkownik wprowadza klucz w panelu administracyjnym zamiast edytować wp-config.php.
• Grupa pól dla niestandardowej sekcji (telefon, email, adres), poprzez połączenie add_settings_section() + kilka add_settings_field().

Proszę zwrócić uwagę: add_settings_field() jedynie wyświetla HTML pola. Za samo zapisywanie odpowiada register_setting(), bez niej WordPress zignoruje wprowadzone dane.

Składnia i parametry add_settings_field

Sygnatura funkcji, cztery parametry obowiązkowe i dwa opcjonalne:

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
);

Przeanalizujmy każdy parametr.

$id, unikalny identyfikator pola. Ta wartość stanie się atrybutem HTML id znacznika <input>, który wyświetla Pan/Pani w funkcji callback. Proszę użyć prefiksu, aby uniknąć konfliktów, na przykład myplugin_phone_number.

$title, etykieta pola, która wyświetla się w panelu administracyjnym po lewej stronie samego inputa. Proszę pisać zrozumiale: „Telefon kontaktowy", „Klucz API usługi".

$callback, nazwa Pana/Pani funkcji, która wyświetla kod HTML pola (input, textarea, select). To tutaj pisze Pan/Pani echo. Funkcja musi być zadeklarowana wcześniej, proszę przekazywać ją jako ciąg znaków: 'my_field_callback'.

$page, slug strony ustawień. Standardowe wartości to: general, reading, writing, discussion i media. Jeśli utworzył Pan/Pani niestandardową stronę, proszę podać jej slug. Określa, gdzie pojawi się pole.

$section (opcjonalny), slug sekcji, do której trafi pole. Domyślnie 'default', jest to najwyższa sekcja na stronie. Jeśli utworzył Pan/Pani własną sekcję przez add_settings_section(), proszę podać tutaj jej ID.

$args (opcjonalny), tablica dodatkowych ustawień. Obsługiwane są klucze label_for (wartość atrybutu HTML for w <label>) oraz class (klasa CSS dla opakowania pola).

Wszystkie parametry i ich działanie są opisane w oficjalnym przewodniku po Settings API na WordPress.org.

Praktyczny przykład: dodajemy pole tekstowe w „Ustawienia ogólne"

Zbierzmy wszystko razem. Zadanie: wyświetlić pole tekstowe „Telefon kontaktowy" na stronie Ustawienia → Ogólne, zapisywać wprowadzoną wartość i pobierać ją przez get_option().

Kod dodaje się do functions.php motywu potomnego lub przez wtyczkę Code Snippets. Druga opcja jest bezpieczniejsza: snippet nie zniknie podczas aktualizacji motywu.

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' );

Co tu się dzieje, linijka po linijce. register_setting() mówi WordPress: wartość pola my_contact_phone ma być zapisywana jako opcja w tabeli wp_options po kliknięciu „Zapisz zmiany" na stronie general.

add_settings_section() tworzy nowy blok z nagłówkiem „Kontakty organizacji" na stronie ustawień ogólnych. Callback my_custom_section_callback() wyświetla tekst opisu nad polami sekcji.

add_settings_field() umieszcza nasze pole wewnątrz tej sekcji i wiąże je z callbackiem my_phone_field_callback(), który renderuje <input type="text">. Funkcja get_option() podstawia zapisaną wartość do atrybutu value, a esc_attr() ekranuje wyjście.

Cały kod jest podpięty do haka admin_init, który uruchamia się podczas ładowania panelu administracyjnego i gwarantuje, że do momentu renderowania strony ustawień sekcja i pole są już zarejestrowane.

Po dodaniu kodu proszę otworzyć wp-admin/options-general.php, zobaczy Pan/Pani wynik:

Proszę wprowadzić numer, kliknąć Zapisz zmiany, wartość zostanie zapisana w bazie. Aby wyświetlić telefon na stronie, proszę użyć get_option() w dowolnym miejscu szablonu:

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

Gdzie umieszczać kod i jak testować

Trzy opcje umieszczenia, od najgorszej do najlepszej.

Motyw nadrzędny (functions.php). Proszę tego nie robić. Podczas aktualizacji motywu plik zostanie nadpisany, a Pana/Pani dostosowanie zniknie.

Motyw potomny (****functions.php** motywu potomnego).** Działająca opcja dla poprawek związanych z konkretną witryną. Kod przetrwa aktualizację motywu nadrzędnego.

Wtyczka Code Snippets. Najlepszy wybór do testowania i długoterminowego utrzymania. Snippet można włączać/wyłączać jednym przyciskiem, bez dotykania systemu plików. Dodatkowo zyskuje Pan/Pani izolację: jeśli snippet spowoduje błąd krytyczny, WordPress automatycznie go dezaktywuje, a strona nie padnie.

Kolejność testowania. Proszę utworzyć pełną kopię zapasową witryny (baza + pliki), to standardowy środek ostrożności przy każdej modyfikacji panelu administracyjnego. Proszę dodać kod wybraną metodą. Proszę otworzyć stronę ustawień i sprawdzić, czy pole się wyświetla. Proszę wprowadzić wartość i zapisać. Proszę sprawdzić zapis: odświeżyć stronę, pole powinno być wypełnione tym, co Pan/Pani wprowadził.

Jeśli pole się nie pojawia, proszę sprawdzić, czy nie pomylił Pan/Pani ID sekcji w parametrze $section w add_settings_field(). Częsty błąd: sekcja jest tworzona z jednym ID, a do pola przekazywane jest inne.

Instrukcja wideo na ten temat

Aby utrwalić materiał, proszę obejrzeć omówienie wideo Settings API od jednego z deweloperów WordPress. Pokazano pełny cykl: rejestracja sekcji, dodanie pola, zapis i wyświetlenie na stronie.

⁉️🤔 Często zadawane pytania

Czy można dodać kilka pól do jednej sekcji?

Tak. Proszę wywołać add_settings_field() tyle razy, ile pól jest potrzebnych. Proszę przekazywać to samo ID sekcji w parametrze $section. Każde pole otrzyma unikalny $id i swój callback. Kolejność wywołań add_settings_field() określa kolejność pól na stronie.

Jak dodać select, textarea lub checkbox zamiast pola tekstowego?

Typ pola określa się wewnątrz funkcji callback za pomocą HTML. Dla select tworzy Pan/Pani <select> z <option>, dla textarea znacznik <textarea>, dla checkboxa <input type="checkbox">. Wartość zapisuje się tak samo przez register_setting() i pobiera przez get_option(). Specyfika dotyczy tylko HTML.

Czy trzeba ekranować wyjście w callbacku?

Tak, obowiązkowo. Proszę używać esc_attr() dla wartości atrybutów (value, name, id) i esc_html() dla tekstu między znacznikami. Chroni to przed XSS i gwarantuje, że znaki specjalne w zapisanej wartości nie zepsują układu strony.

Czy można dodać pole na stronę własnej wtyczki?

Tak. Proszę utworzyć stronę przez add_options_page() lub add_menu_page(), a następnie zarejestrować sekcje i pola w ten sam sposób. Slug Pana/Pani strony proszę podstawić w parametrze $page w add_settings_field(). Mechanika nie różni się niczym od standardowych stron.

Co zrobić, jeśli wartość nie zapisuje się po kliknięciu „Zapisz zmiany"?

Prawie na pewno pominął Pan/Pani register_setting(). Bez tej funkcji WordPress nie wie, że pole ma być zapisane, i ignoruje je podczas submit. Proszę sprawdzić: pierwszy parametr register_setting() musi być zgodny z nazwą strony (na przykład 'general'), a drugi z atrybutem name Pana/Pani pola.

Podsumowując: kiedy warto rozszerzać ustawienia panelu administracyjnego

Settings API WordPress to dojrzały i stabilny mechanizm: add_settings_field() nie zmieniła się od wersji 2.7 i pozostaje aktualna w 2026 roku. Dodawanie własnych pól w panelu administracyjnym jest uzasadnione w trzech przypadkach:

• Tworzy Pan/Pani motyw lub wtyczkę i chce dać użytkownikowi interfejs do wprowadzania danych, bez edycji kodu.
• Potrzebuje Pan/Pani pola z ustawieniem na poziomie witryny (numer telefonu, klucz API, ID katalogu) i musi być ono dostępne przez panel administracyjny, a nie przez wp-config.php.
• Dostosowuje Pan/Pani witrynę klienta i chce, aby menedżer mógł samodzielnie zmieniać dane bez kontaktu z deweloperem.

Jeśli pole jest potrzebne tylko Panu/Pani i zmienia się raz w roku, prościej jest wpisać wartość bezpośrednio w kodzie. Settings API sprawdza się tam, gdzie z ustawień korzysta ktoś, kto nie jest deweloperem.

Proszę zacząć od czegoś prostego: dodać jedno pole tekstowe według powyższego przykładu. Kiedy opanuje Pan/Pani podstawowy przepływ, rejestracja, callback, zapis, wyświetlanie, proszę przejść do selectów, grup pól i niestandardowych stron ustawień. A z jakim typem pola pracuje Pan/Pani najczęściej, proszę napisać w komentarzach.