Jak stworzyć własny kreator ustawień w WordPress (Settings API krok po kroku)

Jeśli tworzysz własną wtyczkę lub motyw WordPress, prędzej czy później będziesz potrzebować panelu ustawień – miejsca, w którym użytkownik może zmieniać opcje, zapisywać dane i dostosowywać działanie Twojego rozwiązania.
Zamiast tworzyć formularze „na piechotę”, warto skorzystać z wbudowanego w WordPressa Settings API – potężnego, ale często pomijanego narzędzia.

W tym poradniku pokażę Ci krok po kroku, jak stworzyć własny kreator ustawień, który:

• posiada własną stronę w panelu administracyjnym,
• zapisuje dane w bazie danych (wp_options),
• jest zgodny ze standardami WordPressa,
• może być łatwo rozszerzony o kolejne pola i sekcje.

Krok 1: Utworzenie strony ustawień

Zacznijmy od dodania nowej strony w panelu administracyjnym WordPressa.
W pliku głównym Twojej wtyczki (np. my-plugin.php) dodaj:

add_action( 'admin_menu', 'myplugin_add_admin_menu' );

function myplugin_add_admin_menu() {
    add_options_page(
        'Ustawienia Mojej Wtyczki',    // Tytuł strony
        'Moja Wtyczka',                // Nazwa w menu
        'manage_options',              // Uprawnienia
        'myplugin_settings',           // Slug strony
        'myplugin_settings_page_html'  // Funkcja wyświetlająca zawartość
    );
}

Ta funkcja utworzy pozycję „Moja Wtyczka” w sekcji Ustawienia → Moja Wtyczka.

Krok 2: Rejestracja ustawień i pól

Teraz dodamy pola formularza, które będą zapisywane w bazie danych.
Skorzystamy z hooka admin_init:

add_action( 'admin_init', 'myplugin_settings_init' );

function myplugin_settings_init() {
    register_setting( 'myplugin_options_group', 'myplugin_options' );

    add_settings_section(
        'myplugin_section_main',
        'Podstawowe ustawienia',
        'myplugin_section_callback',
        'myplugin_settings'
    );

    add_settings_field(
        'myplugin_field_text',
        'Tekst powitalny',
        'myplugin_field_text_callback',
        'myplugin_settings',
        'myplugin_section_main'
    );
}

function myplugin_section_callback() {
    echo '<p>Ustawienia główne Twojej wtyczki.</p>';
}

function myplugin_field_text_callback() {
    $options = get_option( 'myplugin_options' );
    ?>
    <input type="text" name="myplugin_options[text]" value="<?php echo esc_attr( $options['text'] ?? '' ); ?>" />
    <?php
}

To stworzy sekcję i pole tekstowe, którego wartość zostanie zapisana w bazie po kliknięciu „Zapisz zmiany”.

Krok 3: Wyświetlenie strony ustawień

Teraz czas na kod HTML naszej strony:

function myplugin_settings_page_html() {
    if ( ! current_user_can( 'manage_options' ) ) {
        return;
    }
    ?>
    <div class="wrap">
        <h1><?php echo esc_html( get_admin_page_title() ); ?></h1>
        <form action="options.php" method="post">
            <?php
            settings_fields( 'myplugin_options_group' );
            do_settings_sections( 'myplugin_settings' );
            submit_button( 'Zapisz zmiany' );
            ?>
        </form>
    </div>
    <?php
}

Po wejściu do Ustawienia → Moja Wtyczka zobaczysz formularz, który automatycznie obsługuje walidację i zapisywanie danych w bazie.

Krok 4: Dodanie walidacji i sanitizacji danych

Warto zadbać o bezpieczeństwo danych – wystarczy dodać funkcję callback podczas rejestracji ustawień:

register_setting(
    'myplugin_options_group',
    'myplugin_options',
    [
        'sanitize_callback' => 'myplugin_sanitize_options'
    ]
);

function myplugin_sanitize_options( $input ) {
    $output = [];
    $output['text'] = sanitize_text_field( $input['text'] );
    return $output;
}

Dzięki temu żadne niepożądane dane nie trafią do bazy.

Podsumowanie

Settings API pozwala tworzyć czyste, zgodne z WordPressem panele ustawień bez pisania własnych zapytań SQL ani obsługi formularzy.
Z czasem możesz rozszerzyć swój kreator o:

• pola typu checkbox, select, textarea, upload, color picker,
• własne sekcje i zakładki,
• dynamiczne ustawienia zależne od użytkownika.

To potężne narzędzie, które każdy developer WordPressa powinien znać.