{"id":20874,"date":"2026-10-14T18:52:00","date_gmt":"2026-10-14T16:52:00","guid":{"rendered":"https:\/\/www.lukaswojcik.com\/blog\/?p=20874"},"modified":"2026-10-09T22:41:08","modified_gmt":"2026-10-09T20:41:08","slug":"strony-ustawien-settings-api-register-setting","status":"publish","type":"post","link":"https:\/\/www.lukaswojcik.com\/blog\/pl\/wordpress-plugins-tricks-pl\/tutorials-pl-wordpress-plugins-tricks-pl\/strony-ustawien-settings-api-register-setting\/","title":{"rendered":"Strony ustawie\u0144 wtyczki z Settings API i register_setting"},"content":{"rendered":"

Prawie ka\u017cda wtyczka potrzebuje strony, na kt\u00f3rej administrator mo\u017ce zmieni\u0107 kilka warto\u015bci. Zaskakuj\u0105co wiele wtyczek wci\u0105\u017c buduje j\u0105 r\u0119cznie: w\u0142asna obs\u0142uga \u017c\u0105dania POST, sprawdzenie uprawnie\u0144 w jednym miejscu, zapomniany Nonce w innym i kilkana\u015bcie osobnych wierszy w wp_options<\/code>. WordPress od wersji 2.7 udost\u0119pnia do tego Settings API. Interfejs ten wy\u015bwietla formularz w znanym uk\u0142adzie panelu administracyjnego i wysy\u0142a dane do wp-admin\/options.php<\/code>, gdzie rdze\u0144 sprawdza Nonce i uprawnienia, oczyszcza dane oraz je zapisuje. Od WordPressa 4.7 funkcja register_setting()<\/code> opisuje ponadto same dane: typ, warto\u015b\u0107 domy\u015bln\u0105, callback oczyszczaj\u0105cy oraz, dzi\u0119ki show_in_rest<\/code>, widoczno\u015b\u0107 w punkcie ko\u0144cowym REST \/wp\/v2\/settings<\/code>.<\/p>\n

W tym artykule powstaje ma\u0142a, ale kompletna wtyczka \u201eLW Settings Demo\u201d: pasek komunikatu, kt\u00f3rego trzy ustawienia s\u0105 zebrane w jednej opcji, strona w menu \u201eUstawienia\u201d, callback oczyszczaj\u0105cy obs\u0142uguj\u0105cy zar\u00f3wno formularz, jak i REST API, oraz kr\u00f3tki skrypt, kt\u00f3ry t\u0119 sam\u0105 opcj\u0119 odczytuje i zapisuje przez apiFetch<\/code>. Po drodze da si\u0119 prze\u015bledzi\u0107 drog\u0119 pojedynczego pola formularza od elementu wej\u015bciowego a\u017c do wiersza w wp_options<\/code> i zobaczy\u0107, w kt\u00f3rym miejscu \u015bcie\u017cka REST biegnie inaczej. Kod \u017ar\u00f3d\u0142owy rdzenia przeczytano 29.09.2026; wed\u0142ug sprawdzenia wersji na WordPress.org aktualne wydanie to 7.1.2, a przyk\u0142ad wymaga co najmniej WordPressa 6.6.<\/p>\n

Cztery zadania, cztery grupy funkcji<\/h2>\n

Settings API dzieli stron\u0119 ustawie\u0144 na wyra\u017anie rozdzielone zadania. Ka\u017cda grupa funkcji nale\u017cy do w\u0142asnego hooka. Pomieszanie ich to najcz\u0119stszy pow\u00f3d, dla kt\u00f3rego strona wy\u015bwietla si\u0119 poprawnie, ale niczego nie zapisuje.<\/p>\n\n\n\n\n\n\n\n\n
Funkcja<\/th>\nHook<\/th>\nZadanie<\/th>\n<\/tr>\n<\/thead>\n
add_options_page()<\/code><\/td>\nadmin_menu<\/code><\/td>\nPozycja w menu \u201eUstawienia\u201d, Capability decyduj\u0105ca o wy\u015bwietleniu pozycji<\/td>\n<\/tr>\n
register_setting()<\/code><\/td>\ninit<\/code> (wyja\u015bnienie ni\u017cej)<\/td>\nDopisuje opcj\u0119 do listy dozwolonych opcji grupy, do\u0142\u0105cza callback oczyszczaj\u0105cy, warto\u015b\u0107 domy\u015bln\u0105 i schemat REST<\/td>\n<\/tr>\n
add_settings_section()<\/code>, add_settings_field()<\/code><\/td>\nadmin_init<\/code><\/td>\nUk\u0142ad: nag\u0142\u00f3wki, etykiety, callbacki wypisuj\u0105ce elementy formularza<\/td>\n<\/tr>\n
settings_fields()<\/code>, do_settings_sections()<\/code><\/td>\nCallback strony<\/td>\nUkryte pola z Nonce, a potem wszystkie sekcje i pola strony<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

add_options_page()<\/code> to cienka nak\u0142adka: wywo\u0142uje add_submenu_page()<\/code> z options-general.php<\/code> jako stron\u0105 nadrz\u0119dn\u0105. Przekazana tu Capability rozstrzyga o tym, czy pozycja pojawi si\u0119 w menu; u\u017cytkownik bez niej dostaje te\u017c status 403 przy bezpo\u015brednim otwarciu adresu strony. Docblock funkcji wprost zaznacza, \u017ce callback strony musi sam jeszcze raz sprawdzi\u0107 uprawnienia, dlatego funkcja renderuj\u0105ca w przyk\u0142adzie zaczyna si\u0119 od current_user_can( 'manage_options' )<\/code>. Przy zapisie nast\u0119puje trzecia, osobna kontrola w options.php<\/code>, co pokazuje sekcja o \u015bcie\u017cce zapisu.<\/p>\n

Formularz i zapis \u0142\u0105czy grupa opcji. register_setting( 'lwsd_notice_bar', 'lwsd_settings', \u2026 )<\/code> przypisuje opcj\u0119 lwsd_settings<\/code> do grupy lwsd_notice_bar<\/code>, a settings_fields( 'lwsd_notice_bar' )<\/code> wysy\u0142a w\u0142a\u015bnie t\u0119 nazw\u0119 grupy w ukrytym polu option_page<\/code>. Identyfikator strony u\u017cywany przez add_settings_section()<\/code> i do_settings_sections()<\/code> to osobna nazwa; w przyk\u0142adzie pokrywa si\u0119 ze slugiem menu lwsd-notice-bar<\/code>.<\/p>\n

Jedna opcja zamiast kilkunastu<\/h2>\n

Plugin Handbook zaleca przechowywanie powi\u0105zanych warto\u015bci jako tablicy w jednej opcji, bo odczyt i zapis odbywaj\u0105 si\u0119 wtedy w jednej transakcji bazy danych, a nie w wielu. Kod options.php<\/code> dostarcza drugiego, mniej oczywistego argumentu. Przy zapisie plik przechodzi przez wszystkie<\/strong> opcje zarejestrowane w przes\u0142anej grupie i dla ka\u017cdej wywo\u0142uje update_option()<\/code>. Je\u015bli w danych POST brakuje pola, przekazywana jest warto\u015b\u0107 null<\/code>. Dwa formularze w tej samej grupie nadpisuj\u0105 wi\u0119c nawzajem swoje warto\u015bci. Jedna opcja tablicowa na formularz usuwa t\u0119 pu\u0142apk\u0119, a callback oczyszczaj\u0105cy widzi wszystkie warto\u015bci jednocze\u015bnie. Dzi\u0119ki temu da si\u0119 sformu\u0142owa\u0107 regu\u0142y obejmuj\u0105ce kilka p\u00f3l, na przyk\u0142ad \u201ebrak aktywnego paska bez tre\u015bci komunikatu\u201d.<\/p>\n

Cen\u0105 jest serializacja: tablica trafia do jednego wiersza jako zserializowany ci\u0105g znak\u00f3w, a pojedynczych kluczy nie da si\u0119 filtrowa\u0107 w SQL. Przy warto\u015bciach konfiguracyjnych rzadko ma to znaczenie. Dla danych, kt\u00f3re trzeba przeszukiwa\u0107, alternatywy omawia artyku\u0142 o granicach wydajno\u015bci wp_postmeta<\/code> i w\u0142asnych tabelach<\/a>.<\/p>\n

\u015awiadome ustawienie autoload<\/h3>\n

WordPress 6.6 przebudowa\u0142 kolumn\u0119 autoload. Parametr $autoload<\/code> funkcji add_option()<\/code> ma od tej wersji domy\u015blnie warto\u015b\u0107 null<\/code>. W kolumnie zapisywane s\u0105 on<\/code> i off<\/code> dla jawnych decyzji, auto<\/code>, gdy nikt nie zdecydowa\u0142, oraz auto-on<\/code> lub auto-off<\/code>, gdy decyzj\u0119 dynamicznie podj\u0105\u0142 filtr. Stare warto\u015bci yes<\/code> i no<\/code> s\u0105 od 6.7 oznaczone jako przestarza\u0142e. Opcje wi\u0119ksze ni\u017c 150 000 bajt\u00f3w domy\u015blnie nie s\u0105 \u0142adowane automatycznie (filtr wp_max_autoloaded_option_size<\/code>). Wed\u0142ug wp_autoload_values_to_autoload()<\/code> warto\u015b\u0107 auto<\/code> jest obecnie nadal \u0142adowana, jednak notatka deweloperska do 6.6 zastrzega, \u017ce ta domy\u015blna regu\u0142a mo\u017ce si\u0119 w przysz\u0142ych wersjach zmieni\u0107.<\/p>\n

Dla Settings API ma to znaczenie, poniewa\u017c options.php<\/code> wywo\u0142uje update_option()<\/code> bez argumentu autoload. Je\u015bli opcja jeszcze nie istnieje, update_option()<\/code> wywo\u0142uje add_option()<\/code>, a wiersz powstaje z warto\u015bci\u0105 auto<\/code>. Aby jawnie ustawi\u0107 autoload, nale\u017cy utworzy\u0107 opcj\u0119 samodzielnie. Przyk\u0142ad robi to przy aktywacji za pomoc\u0105 add_option( \u2026, true )<\/code>, poniewa\u017c pasek komunikatu jest odczytywany przy ka\u017cdym \u017c\u0105daniu frontendu.<\/p>\n

P\u00f3\u017aniejsze wywo\u0142ania update_option()<\/code> bez argumentu autoload zachowuj\u0105 jawne on<\/code> lub off<\/code>; ponownie oceniane s\u0105 tylko warianty auto<\/code>. Opcja potrzebna tylko na jednej stronie panelu dosta\u0142aby natomiast false<\/code>.<\/p>\n

P\u00f3\u017aniej mo\u017cna zmieni\u0107 autoload za pomoc\u0105 wp_set_option_autoload()<\/code> (od 6.4), bez zmiany zapisanej warto\u015bci opcji. Natomiast update_option()<\/code> przyjmuje now\u0105 warto\u015b\u0107 autoload tylko wtedy, gdy zmienia si\u0119 r\u00f3wnie\u017c tre\u015b\u0107 opcji. Znaczenie poszczeg\u00f3lnych warto\u015bci kolumny w praktyce om\u00f3wi osobny, zaplanowany artyku\u0142 o autoload<\/span>.<\/p>\n

Kompletna wtyczka<\/h2>\n

Plik g\u0142\u00f3wny zawiera wszystko: rejestracj\u0119, stron\u0119, pola, callback oczyszczaj\u0105cy, wyj\u015bcie na frontendzie i aktywacj\u0119. Prefiks lwsd_<\/code> obowi\u0105zuje konsekwentnie dla funkcji, sta\u0142ych, opcji i identyfikator\u00f3w HTML.<\/p>\n

<?php\n\/**\n * Plugin Name:       LW Settings Demo\n * Description:       Notice bar with a settings page built on the Settings API, also available via \/wp\/v2\/settings.\n * Version:           1.0.0\n * Requires at least: 6.6\n * Requires PHP:      7.4\n * Author:            Lukas Wojcik\n * License:           GPL-2.0-or-later\n * License URI:       https:\/\/www.gnu.org\/licenses\/gpl-2.0.html\n * Text Domain:       lw-settings-demo\n *\n * @package LW_Settings_Demo\n *\/\n\nif ( ! defined( 'ABSPATH' ) ) {\n\texit;\n}\n\nconst LWSD_OPTION = 'lwsd_settings';   \/\/ Row in wp_options.\nconst LWSD_GROUP  = 'lwsd_notice_bar'; \/\/ Option group, sent as option_page.\nconst LWSD_PAGE   = 'lwsd-notice-bar'; \/\/ Menu slug and settings page ID.\n\n\/**\n * Default values of the bundled option.\n *\n * @return array\n *\/\nfunction lwsd_default_settings() {\n\treturn array(\n\t\t'enabled'  => false,\n\t\t'message'  => '',\n\t\t'position' => 'bottom',\n\t);\n}\n\n\/**\n * Returns the stored settings merged with the defaults.\n *\n * @return array\n *\/\nfunction lwsd_get_settings() {\n\t$settings = get_option( LWSD_OPTION );\n\n\tif ( ! is_array( $settings ) ) {\n\t\t$settings = array();\n\t}\n\n\treturn wp_parse_args( $settings, lwsd_default_settings() );\n}\n\n\/**\n * Registers the option on init, so admin screens and REST requests both know it.\n *\/\nfunction lwsd_register_setting() {\n\tregister_setting(\n\t\tLWSD_GROUP,\n\t\tLWSD_OPTION,\n\t\tarray(\n\t\t\t'type'              => 'object',\n\t\t\t'label'             => __( 'Notice bar', 'lw-settings-demo' ),\n\t\t\t'description'       => __( 'Visibility, text and position of the notice bar.', 'lw-settings-demo' ),\n\t\t\t'sanitize_callback' => 'lwsd_sanitize_settings',\n\t\t\t'default'           => lwsd_default_settings(),\n\t\t\t'show_in_rest'      => array(\n\t\t\t\t'schema' => array(\n\t\t\t\t\t'type'       => 'object',\n\t\t\t\t\t'properties' => array(\n\t\t\t\t\t\t'enabled'  => array(\n\t\t\t\t\t\t\t'type' => 'boolean',\n\t\t\t\t\t\t),\n\t\t\t\t\t\t'message'  => array(\n\t\t\t\t\t\t\t'type'      => 'string',\n\t\t\t\t\t\t\t'maxLength' => 200,\n\t\t\t\t\t\t),\n\t\t\t\t\t\t'position' => array(\n\t\t\t\t\t\t\t'type' => 'string',\n\t\t\t\t\t\t\t'enum' => array( 'top', 'bottom' ),\n\t\t\t\t\t\t),\n\t\t\t\t\t),\n\t\t\t\t),\n\t\t\t),\n\t\t)\n\t);\n}\nadd_action( 'init', 'lwsd_register_setting' );\n\n\/**\n * Sanitizes the whole settings array.\n *\n * Runs for options.php and for REST writes, because both end in update_option().\n * Must be idempotent: on the first save of a missing option it runs twice.\n *\n * @param mixed $input Raw value.\n * @return array\n *\/\nfunction lwsd_sanitize_settings( $input ) {\n\t$defaults = lwsd_default_settings();\n\n\tif ( ! is_array( $input ) ) {\n\t\treturn $defaults;\n\t}\n\n\t$message  = isset( $input['message'] ) ? sanitize_text_field( $input['message'] ) : '';\n\t$position = isset( $input['position'] ) ? sanitize_key( $input['position'] ) : '';\n\n\t$output = array(\n\t\t'enabled'  => ! empty( $input['enabled'] ),\n\t\t'message'  => mb_substr( $message, 0, 200 ),\n\t\t'position' => in_array( $position, array( 'top', 'bottom' ), true ) ? $position : $defaults['position'],\n\t);\n\n\tif ( $output['enabled'] && '' === $output['message'] ) {\n\t\t$output['enabled'] = false;\n\n\t\t\/\/ add_settings_error() lives in wp-admin\/includes\/template.php,\n\t\t\/\/ which a REST request does not load.\n\t\tif ( function_exists( 'add_settings_error' ) ) {\n\t\t\tadd_settings_error(\n\t\t\t\tLWSD_OPTION,\n\t\t\t\t'lwsd_empty_message',\n\t\t\t\t__( 'The notice bar stays off until a message is entered.', 'lw-settings-demo' ),\n\t\t\t\t'warning'\n\t\t\t);\n\t\t}\n\t}\n\n\treturn $output;\n}\n\n\/**\n * Adds the page below Settings and loads its script only there.\n *\/\nfunction lwsd_add_settings_page() {\n\t$hook_suffix = add_options_page(\n\t\t__( 'Notice bar', 'lw-settings-demo' ),\n\t\t__( 'Notice bar', 'lw-settings-demo' ),\n\t\t'manage_options',\n\t\tLWSD_PAGE,\n\t\t'lwsd_render_settings_page'\n\t);\n\n\tif ( $hook_suffix ) {\n\t\tadd_action( 'load-' . $hook_suffix, 'lwsd_load_settings_page' );\n\t}\n}\nadd_action( 'admin_menu', 'lwsd_add_settings_page' );\n\n\/**\n * Runs only when the settings page is requested.\n *\/\nfunction lwsd_load_settings_page() {\n\tadd_action( 'admin_enqueue_scripts', 'lwsd_enqueue_admin_script' );\n}\n\n\/**\n * Enqueues the REST demo script.\n *\/\nfunction lwsd_enqueue_admin_script() {\n\twp_enqueue_script(\n\t\t'lwsd-settings-rest',\n\t\tplugins_url( 'js\/settings-rest.js', __FILE__ ),\n\t\tarray( 'wp-api-fetch', 'wp-i18n' ),\n\t\t'1.0.0',\n\t\tarray( 'in_footer' => true )\n\t);\n\twp_set_script_translations( 'lwsd-settings-rest', 'lw-settings-demo' );\n}\n\n\/**\n * Declares section and fields. Only needed on admin screens.\n *\/\nfunction lwsd_register_fields() {\n\tadd_settings_section(\n\t\t'lwsd_section_main',\n\t\t__( 'Display', 'lw-settings-demo' ),\n\t\t'lwsd_render_section',\n\t\tLWSD_PAGE\n\t);\n\n\tadd_settings_field(\n\t\t'lwsd_enabled',\n\t\t__( 'Show notice bar', 'lw-settings-demo' ),\n\t\t'lwsd_render_enabled_field',\n\t\tLWSD_PAGE,\n\t\t'lwsd_section_main',\n\t\tarray( 'label_for' => 'lwsd_enabled' )\n\t);\n\n\tadd_settings_field(\n\t\t'lwsd_message',\n\t\t__( 'Message', 'lw-settings-demo' ),\n\t\t'lwsd_render_message_field',\n\t\tLWSD_PAGE,\n\t\t'lwsd_section_main',\n\t\tarray( 'label_for' => 'lwsd_message' )\n\t);\n\n\tadd_settings_field(\n\t\t'lwsd_position',\n\t\t__( 'Position', 'lw-settings-demo' ),\n\t\t'lwsd_render_position_field',\n\t\tLWSD_PAGE,\n\t\t'lwsd_section_main',\n\t\tarray( 'label_for' => 'lwsd_position' )\n\t);\n}\nadd_action( 'admin_init', 'lwsd_register_fields' );\n\n\/**\n * Section intro.\n *\/\nfunction lwsd_render_section() {\n\techo '<p>' . esc_html__( 'All three values are stored together in one option.', 'lw-settings-demo' ) . '<\/p>';\n}\n\n\/**\n * Checkbox field.\n *\/\nfunction lwsd_render_enabled_field() {\n\t$settings = lwsd_get_settings();\n\n\tprintf(\n\t\t'<input type=\"checkbox\" id=\"lwsd_enabled\" name=\"%1$s[enabled]\" value=\"1\" %2$s \/>',\n\t\tesc_attr( LWSD_OPTION ),\n\t\tchecked( $settings['enabled'], true, false )\n\t);\n}\n\n\/**\n * Text field.\n *\/\nfunction lwsd_render_message_field() {\n\t$settings = lwsd_get_settings();\n\n\tprintf(\n\t\t'<input type=\"text\" class=\"regular-text\" id=\"lwsd_message\" name=\"%1$s[message]\" value=\"%2$s\" maxlength=\"200\" \/>',\n\t\tesc_attr( LWSD_OPTION ),\n\t\tesc_attr( $settings['message'] )\n\t);\n}\n\n\/**\n * Select field.\n *\/\nfunction lwsd_render_position_field() {\n\t$settings = lwsd_get_settings();\n\t$choices  = array(\n\t\t'top'    => __( 'Top of the page', 'lw-settings-demo' ),\n\t\t'bottom' => __( 'Bottom of the page', 'lw-settings-demo' ),\n\t);\n\n\tprintf( '<select id=\"lwsd_position\" name=\"%s[position]\">', esc_attr( LWSD_OPTION ) );\n\n\tforeach ( $choices as $value => $label ) {\n\t\tprintf(\n\t\t\t'<option value=\"%1$s\" %2$s>%3$s<\/option>',\n\t\t\tesc_attr( $value ),\n\t\t\tselected( $settings['position'], $value, false ),\n\t\t\tesc_html( $label )\n\t\t);\n\t}\n\n\techo '<\/select>';\n}\n\n\/**\n * Settings page. The form posts to options.php, not to this page.\n *\/\nfunction lwsd_render_settings_page() {\n\tif ( ! current_user_can( 'manage_options' ) ) {\n\t\treturn;\n\t}\n\t?>\n\t<div class=\"wrap\">\n\t\t<h1><?php echo esc_html( get_admin_page_title() ); ?><\/h1>\n\t\t<form action=\"options.php\" method=\"post\">\n\t\t\t<?php\n\t\t\tsettings_fields( LWSD_GROUP );\n\t\t\tdo_settings_sections( LWSD_PAGE );\n\t\t\tsubmit_button();\n\t\t\t?>\n\t\t<\/form>\n\t\t<p>\n\t\t\t<button type=\"button\" class=\"button\" id=\"lwsd-rest-toggle\"><?php esc_html_e( 'Toggle via REST API', 'lw-settings-demo' ); ?><\/button>\n\t\t\t<span id=\"lwsd-rest-status\" aria-live=\"polite\"><\/span>\n\t\t<\/p>\n\t<\/div>\n\t<?php\n}\n\n\/**\n * Prints the notice bar on the front end.\n *\n * @param string $position Where the calling hook prints: top or bottom.\n *\/\nfunction lwsd_print_notice( $position ) {\n\t$settings = lwsd_get_settings();\n\n\tif ( ! $settings['enabled'] || $position !== $settings['position'] || '' === $settings['message'] ) {\n\t\treturn;\n\t}\n\n\tprintf(\n\t\t'<div class=\"lwsd-notice lwsd-notice-%1$s\" role=\"status\">%2$s<\/div>',\n\t\tesc_attr( $position ),\n\t\tesc_html( $settings['message'] )\n\t);\n}\n\n\/**\n * Top position, needs a theme that calls wp_body_open().\n *\/\nfunction lwsd_print_top_notice() {\n\tlwsd_print_notice( 'top' );\n}\nadd_action( 'wp_body_open', 'lwsd_print_top_notice' );\n\n\/**\n * Bottom position.\n *\/\nfunction lwsd_print_bottom_notice() {\n\tlwsd_print_notice( 'bottom' );\n}\nadd_action( 'wp_footer', 'lwsd_print_bottom_notice' );\n\n\/**\n * Creates the option with an explicit autoload value.\n *\/\nfunction lwsd_activate() {\n\t\/\/ Read on every front-end request, so autoload it on purpose.\n\tadd_option( LWSD_OPTION, lwsd_default_settings(), '', true );\n}\nregister_activation_hook( __FILE__, 'lwsd_activate' );<\/code><\/pre>\n
Dlaczego register_setting dzia\u0142a na hooku init<\/h3>\n
Przyk\u0142ad w Plugin Handbook rejestruje ustawienia na hooku admin_init<\/code>. Ten hook jest wywo\u0142ywany w wp-admin\/admin.php<\/code>, a \u017c\u0105danie REST do \/wp-json\/<\/code> nigdy nie \u0142aduje tego pliku. Ustawienie zarejestrowane tylko tam dzia\u0142a w formularzu, ale nie pojawia si\u0119 w \/wp\/v2\/settings<\/code>. Rdze\u0144 rejestruje w\u0142asne ustawienia na rest_api_init<\/code>, a przyk\u0142ad z WordPress Developer Blog dla stron ustawie\u0144 opartych na React korzysta z init<\/code>. Wtyczka idzie t\u0105 drug\u0105 drog\u0105: init<\/code> obejmuje options.php<\/code>, stron\u0119 ustawie\u0144, \u017c\u0105dania REST oraz frontend, gdzie dodatkowo dzia\u0142a zarejestrowana warto\u015b\u0107 domy\u015blna. Sekcje i pola to natomiast czysty uk\u0142ad panelu i zostaj\u0105 na admin_init<\/code>.<\/p>\n
Jeden callback oczyszczaj\u0105cy dla dw\u00f3ch \u015bcie\u017cek<\/h3>\n
register_setting()<\/code> podpina callback pod filtr sanitize_option_lwsd_settings<\/code>. Filtr ten stosuje sanitize_option()<\/code>, kt\u00f3r\u0105 update_option()<\/code> wywo\u0142uje przy ka\u017cdym zapisie, niezale\u017cnie od tego, czy warto\u015b\u0107 pochodzi z options.php<\/code>, czy z REST API. Ma to dwie konsekwencje.<\/p>\n
Po pierwsze, add_settings_error()<\/code> jest zdefiniowana w wp-admin\/includes\/template.php<\/code>, pliku, kt\u00f3rego zwyk\u0142e \u017c\u0105danie REST nie \u0142aduje. Sprawdzenie przez function_exists()<\/code> pozwala wi\u0119c ustali\u0107, czy funkcja jest dost\u0119pna przed jej wywo\u0142aniem. Po drugie, callback musi by\u0107 idempotentny: ponowne zastosowanie go do w\u0142asnego wyniku musi da\u0107 ten sam wynik. Gdy opcji brakuje, update_option()<\/code> oczyszcza warto\u015b\u0107 raz, a add_option()<\/code> drugi raz. Utworzenie wiersza przy aktywacji zapobiega temu podw\u00f3jnemu przebiegowi w normalnej pracy, ale callback nie powinien na tym polega\u0107.<\/p>\n
Bez wywo\u0142ania settings_errors() na stronie<\/h3>\n
Dla stron w menu \u201eUstawienia\u201d plik admin-header.php<\/code> do\u0142\u0105cza options-head.php<\/code>, a ten sam wywo\u0142uje settings_errors()<\/code>. Dodatkowe wywo\u0142anie w callbacku strony wypisa\u0142oby ka\u017cdy komunikat dwukrotnie. Przyk\u0142ad z Handbooka u\u017cywa strony menu najwy\u017cszego poziomu i dlatego wywo\u0142uje settings_errors()<\/code> samodzielnie. Jeszcze jeden szczeg\u00f3\u0142 z options.php<\/code>: komunikat o zapisaniu ustawie\u0144 dodawany jest tylko wtedy, gdy nie zarejestrowano \u017cadnego innego. Ostrze\u017cenie z callbacku oczyszczaj\u0105cego zast\u0119puje go, cho\u0107 pozosta\u0142e warto\u015bci zosta\u0142y zapisane.<\/p>\n
Co dzieje si\u0119 przy zapisie<\/h2>\n
Formularz wysy\u0142a dane do options.php<\/code>, a nie do strony ustawie\u0144. Poni\u017csze kroki pochodz\u0105 bezpo\u015brednio z kodu rdzenia i dotycz\u0105 ka\u017cdej strony zbudowanej na Settings API.<\/p>\n
\n\"Od
options.php sprawdza Capability, Nonce i list\u0119 dozwolonych; REST do\u0142\u0105cza przy update_option(), gdzie dzia\u0142a callback<\/figcaption><\/figure>\n
    \n
  1. settings_fields()<\/code> wypisuje cztery ukryte pola: option_page<\/code> z nazw\u0105 grupy, action<\/code> z warto\u015bci\u0105 update<\/code>, Nonce _wpnonce<\/code> dla akcji lwsd_notice_bar-options<\/code> oraz _wp_http_referer<\/code> z adresem, na kt\u00f3ry options.php<\/code> przekierowuje po zapisie.<\/li>\n
  2. options.php<\/code> ustala wymagan\u0105 Capability: manage_options<\/code>, z mo\u017cliwo\u015bci\u0105 zmiany przez filtr option_page_capability_{$option_page}<\/code>. Bez niej \u017c\u0105danie ko\u0144czy si\u0119 statusem 403.<\/li>\n
  3. check_admin_referer( $option_page . '-options' )<\/code> weryfikuje Nonce.<\/li>\n
  4. Grupa musi znajdowa\u0107 si\u0119 na li\u015bcie dozwolonych, kt\u00f3r\u0105 wype\u0142nia register_setting()<\/code>, a rozszerza filtr allowed_options<\/code>. W przeciwnym razie wp_die()<\/code> przerywa \u017c\u0105danie.<\/li>\n
  5. Dla ka\u017cdej zarejestrowanej opcji warto\u015b\u0107 jest odczytywana z $_POST<\/code>, przycinana, je\u015bli jest skalarna, przepuszczana przez wp_unslash()<\/code> i przekazywana do update_option()<\/code>.<\/li>\n
  6. update_option()<\/code> uruchamia sanitize_option()<\/code>, a wi\u0119c callback, potem filtry pre_update_option<\/code>. Je\u015bli warto\u015b\u0107 si\u0119 nie zmieni\u0142a, nic nie jest zapisywane; w przeciwnym razie zserializowana warto\u015b\u0107 trafia do wiersza.<\/li>\n
  7. Zebrane komunikaty trafiaj\u0105 na 30 sekund do transientu settings_errors<\/code>, po czym nast\u0119puje przekierowanie z settings-updated=true<\/code>. Po przekierowaniu settings_errors()<\/code> odczytuje transient i wy\u015bwietla komunikaty.<\/li>\n<\/ol>\n
    Krok drugi ma praktyczn\u0105 konsekwencj\u0119. Wtyczka, kt\u00f3ra pokazuje swoj\u0105 pozycj\u0119 menu redaktorom z uprawnieniem edit_pages<\/code>, nie zapisze ustawie\u0144, dop\u00f3ki filtr option_page_capability_lwsd_notice_bar<\/code> nadal wymaga manage_options<\/code>. Wy\u015bwietlanie menu, callback strony i zapis musz\u0105 wymaga\u0107 tego samego uprawnienia. Dlaczego sam Nonce nigdy nie zast\u0119puje sprawdzenia uprawnie\u0144, wyja\u015bnia szczeg\u00f3\u0142owo osobny artyku\u0142 tej serii o sanitizacji, escapowaniu, Nonce i Capabilities<\/a>.<\/p>\n
    register_setting a punkt ko\u0144cowy \/wp\/v2\/settings<\/h2>\n
    Zarejestrowane ustawienia domy\u015blnie nie pojawiaj\u0105 si\u0119 w REST API. Dla typ\u00f3w skalarnych wystarczy show_in_rest<\/code> z warto\u015bci\u0105 true<\/code>. Przy array<\/code> i object<\/code> opcja potrzebuje schematu w show_in_rest.schema<\/code>: dla tablic bez items<\/code> rdze\u0144 zg\u0142asza komunikat _doing_it_wrong<\/code> (od 5.4), a dla obiekt\u00f3w properties<\/code> okre\u015blaj\u0105, jakie klucze istniej\u0105. Kontroler buduje ostateczny schemat z type<\/code>, label<\/code> (jako title<\/code>), description<\/code> i default<\/code>, a nast\u0119pnie nak\u0142ada na niego schemat z show_in_rest<\/code>. Akceptowane s\u0105 wy\u0142\u0105cznie typy number<\/code>, integer<\/code>, string<\/code>, boolean<\/code>, array<\/code> i object<\/code>; pozosta\u0142e ustawienia s\u0105 po cichu pomijane.<\/p>\n
    Kontroler w class-wp-rest-settings-controller.php<\/code> odpowiada na kilka pyta\u0144, kt\u00f3re strony referencyjne pozostawiaj\u0105 otwarte:<\/p>\n