{"id":20873,"date":"2026-10-14T12:16:00","date_gmt":"2026-10-14T10:16:00","guid":{"rendered":"https:\/\/www.lukaswojcik.com\/blog\/?p=20873"},"modified":"2026-10-09T22:41:10","modified_gmt":"2026-10-09T20:41:10","slug":"einstellungsseiten-settings-api-register-setting","status":"publish","type":"post","link":"https:\/\/www.lukaswojcik.com\/blog\/de\/wordpress-plugins-tricks-de\/tutorials-de-wordpress-plugins-tricks-de\/einstellungsseiten-settings-api-register-setting\/","title":{"rendered":"Einstellungsseiten mit der Settings API und register_setting"},"content":{"rendered":"

Fast jedes Plugin braucht eine Seite, auf der Administratoren ein paar Werte \u00e4ndern k\u00f6nnen. Erstaunlich viele Plugins bauen sie noch von Hand: mit einem eigenen POST-Handler, einer Capability-Pr\u00fcfung hier, einer vergessenen Nonce dort und einem Dutzend einzelner Zeilen in wp_options<\/code>. WordPress bietet daf\u00fcr seit Version 2.7 die Settings API. Sie stellt das Formular im gewohnten Admin-Layout dar, schickt es an wp-admin\/options.php<\/code> und \u00fcbernimmt dort die Nonce-Pr\u00fcfung, Rechtepr\u00fcfung, Bereinigung und Speicherung. Seit WordPress 4.7 beschreibt register_setting()<\/code> au\u00dferdem die Daten selbst: Typ, Standardwert, Sanitize-Callback und \u00fcber show_in_rest<\/code> die Sichtbarkeit im REST-Endpunkt \/wp\/v2\/settings<\/code>.<\/p>\n

Dieser Beitrag baut ein kleines, aber vollst\u00e4ndiges Plugin namens \u201eLW Settings Demo\u201c: eine Hinweisleiste, deren drei Einstellungen geb\u00fcndelt in einer einzigen Option liegen, eine Seite unter \u201eEinstellungen\u201c, einen Sanitize-Callback, der Formular und REST-API gleicherma\u00dfen bedient, und ein kurzes Skript, das dieselbe Option mit apiFetch<\/code> liest und schreibt. Unterwegs wird ein einzelnes Formularfeld vom Eingabeelement bis zu seiner Zeile in wp_options<\/code> verfolgt, samt der Stelle, an der der REST-Weg abzweigt. Der Core-Quelltext wurde am 29.09.2026 gelesen; laut Versionspr\u00fcfung von WordPress.org ist 7.1.2 die aktuelle Version, das Beispiel setzt mindestens WordPress 6.6 voraus.<\/p>\n

Vier Aufgaben, vier Funktionsgruppen<\/h2>\n

Die Settings API zerlegt eine Einstellungsseite in klar getrennte Aufgaben. Jede Funktionsgruppe geh\u00f6rt an einen eigenen Hook. Wer das durcheinanderbringt, bekommt meist eine Seite, die sauber erscheint, aber nichts speichert.<\/p>\n\n\n\n\n\n\n\n\n
Funktion<\/th>\nHook<\/th>\nAufgabe<\/th>\n<\/tr>\n<\/thead>\n
add_options_page()<\/code><\/td>\nadmin_menu<\/code><\/td>\nMen\u00fceintrag unter \u201eEinstellungen\u201c, Capability f\u00fcr die Anzeige des Men\u00fcpunkts<\/td>\n<\/tr>\n
register_setting()<\/code><\/td>\ninit<\/code> (Erl\u00e4uterung weiter unten)<\/td>\nTr\u00e4gt die Option in die Freigabeliste einer Gruppe ein, h\u00e4ngt Sanitize-Callback, Standardwert und REST-Schema an<\/td>\n<\/tr>\n
add_settings_section()<\/code>, add_settings_field()<\/code><\/td>\nadmin_init<\/code><\/td>\nLayout: \u00dcberschriften, Beschriftungen, Callbacks f\u00fcr die Eingabeelemente<\/td>\n<\/tr>\n
settings_fields()<\/code>, do_settings_sections()<\/code><\/td>\nSeiten-Callback<\/td>\nVersteckte Felder mit Nonce, danach alle Abschnitte und Felder der Seite<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

add_options_page()<\/code> ist nur eine d\u00fcnne H\u00fclle um add_submenu_page()<\/code> mit options-general.php<\/code> als Elternseite. Die dort \u00fcbergebene Capability entscheidet dar\u00fcber, ob der Men\u00fcpunkt erscheint; Benutzer ohne sie erhalten auch beim direkten Aufruf der Seitenadresse den Status 403. Der Docblock verlangt ausdr\u00fccklich, dass der Seiten-Callback die Berechtigung noch einmal selbst pr\u00fcft; deshalb beginnt die Render-Funktion im Beispiel mit current_user_can( 'manage_options' )<\/code>. Beim Speichern folgt eine dritte, getrennte Pr\u00fcfung in options.php<\/code>, wie der Abschnitt zum Speicherweg zeigt.<\/p>\n

Formular und Speicherung h\u00e4ngen \u00fcber die Optionsgruppe zusammen. register_setting( 'lwsd_notice_bar', 'lwsd_settings', \u2026 )<\/code> nimmt die Option lwsd_settings<\/code> in die Gruppe lwsd_notice_bar<\/code> auf, und settings_fields( 'lwsd_notice_bar' )<\/code> schickt genau diesen Gruppennamen als verstecktes Feld option_page<\/code> mit. Die Seiten-ID, die add_settings_section()<\/code> und do_settings_sections()<\/code> verwenden, ist ein anderer Bezeichner; im Beispiel entspricht sie dem Men\u00fc-Slug lwsd-notice-bar<\/code>.<\/p>\n

Eine Option statt Dutzender<\/h2>\n

Das Plugin Handbook empfiehlt, zusammengeh\u00f6rige Werte als Array in einer einzigen Option abzulegen, weil Lesen und Schreiben dann in einer Datenbanktransaktion statt in vielen geschieht. Der Quelltext von options.php<\/code> liefert einen zweiten, weniger offensichtlichen Grund. Beim Speichern durchl\u00e4uft die Datei alle<\/strong> Optionen, die in der gesendeten Gruppe registriert sind, und ruft f\u00fcr jede update_option()<\/code> auf. Fehlt ein Feld in den POST-Daten, wird null<\/code> \u00fcbergeben. Zwei Formulare in derselben Gruppe \u00fcberschreiben sich deshalb gegenseitig. Mit einer Array-Option je Formular entf\u00e4llt diese Falle, und der Sanitize-Callback sieht alle Werte gleichzeitig. Damit lassen sich Regeln \u00fcber mehrere Felder formulieren, etwa \u201ekeine aktive Hinweisleiste ohne Text\u201c.<\/p>\n

Der Preis ist die Serialisierung: Das Array steht als serialisierte Zeichenkette in einer Zeile, einzelne Schl\u00fcssel lassen sich per SQL nicht filtern. F\u00fcr Konfigurationswerte spielt das selten eine Rolle. F\u00fcr Daten, die abgefragt werden m\u00fcssen, zeigt der Beitrag zu den Leistungsgrenzen von wp_postmeta<\/code> und eigenen Tabellen<\/a> die Alternativen.<\/p>\n

Autoload bewusst setzen<\/h3>\n

WordPress 6.6 hat die Autoload-Spalte umgebaut. Der Parameter $autoload<\/code> von add_option()<\/code> steht seitdem standardm\u00e4\u00dfig auf null<\/code>. In der Spalte landen on<\/code> und off<\/code> f\u00fcr ausdr\u00fcckliche Entscheidungen, auto<\/code>, wenn niemand entschieden hat, sowie auto-on<\/code> oder auto-off<\/code>, wenn ein Filter dynamisch entschieden hat. Die alten Werte yes<\/code> und no<\/code> gelten seit 6.7 als veraltet. Optionen \u00fcber 150.000 Bytes werden standardm\u00e4\u00dfig nicht automatisch geladen (Filter wp_max_autoloaded_option_size<\/code>). Laut wp_autoload_values_to_autoload()<\/code> wird auto<\/code> derzeit noch geladen; die Dev Note zu 6.6 h\u00e4lt aber fest, dass sich dieser Standard in k\u00fcnftigen Versionen \u00e4ndern kann.<\/p>\n

F\u00fcr die Settings API ist das relevant, weil options.php<\/code> update_option()<\/code> ohne Autoload-Argument aufruft. Existiert die Option noch nicht, ruft update_option()<\/code> daf\u00fcr add_option()<\/code> auf, und die Zeile entsteht mit auto<\/code>. Wer Autoload ausdr\u00fccklich festlegen will, legt die Option selbst an. Das Beispiel macht das bei der Aktivierung mit add_option( \u2026, true )<\/code>, weil die Hinweisleiste bei jedem Frontend-Aufruf gelesen wird.<\/p>\n

Sp\u00e4tere Aufrufe von update_option()<\/code> ohne Autoload-Argument behalten ein ausdr\u00fcckliches on<\/code> oder off<\/code> bei; neu bewertet werden nur die auto<\/code>-Varianten. Eine Option, die nur auf einer einzigen Admin-Seite gebraucht wird, bek\u00e4me stattdessen false<\/code>.<\/p>\n

Nachtr\u00e4glich l\u00e4sst sich Autoload mit wp_set_option_autoload()<\/code> (seit 6.4) \u00e4ndern, ohne den gespeicherten Optionswert anzufassen. update_option()<\/code> \u00fcbernimmt einen neuen Autoload-Wert dagegen nur, wenn sich auch der Optionswert \u00e4ndert. Was die einzelnen Werte der Spalte in der Praxis bedeuten, behandelt ein eigener, geplanter Beitrag zu Autoload<\/span>.<\/p>\n

Das vollst\u00e4ndige Plugin<\/h2>\n

Die Hauptdatei enth\u00e4lt alles: Registrierung, Seite, Felder, Sanitize-Callback, Frontend-Ausgabe und Aktivierung. Das Pr\u00e4fix lwsd_<\/code> gilt durchgehend f\u00fcr Funktionen, Konstanten, die Option und die HTML-IDs.<\/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
Warum register_setting an init h\u00e4ngt<\/h3>\n
Das Beispiel im Plugin Handbook registriert Einstellungen an admin_init<\/code>. Dieser Hook feuert in wp-admin\/admin.php<\/code>, und ein REST-Aufruf an \/wp-json\/<\/code> l\u00e4dt diese Datei nie. Eine nur dort registrierte Einstellung funktioniert im Formular, fehlt aber in \/wp\/v2\/settings<\/code>. Der Core registriert seine eigenen Einstellungen an rest_api_init<\/code>, und das Beispiel im Developer Blog f\u00fcr React-basierte Einstellungsseiten nutzt init<\/code>. Das Plugin folgt dem: init<\/code> deckt options.php<\/code>, die Einstellungsseite, REST-Aufrufe und das Frontend ab, wo zus\u00e4tzlich der registrierte Standardwert greift. Abschnitte und Felder sind dagegen reines Admin-Layout und bleiben an admin_init<\/code>.<\/p>\n
Ein Sanitize-Callback f\u00fcr zwei Wege<\/h3>\n
register_setting()<\/code> h\u00e4ngt den Callback an den Filter sanitize_option_lwsd_settings<\/code>. Diesen Filter wendet sanitize_option()<\/code> an: update_option()<\/code> ruft sanitize_option()<\/code> bei jedem Schreibvorgang auf, unabh\u00e4ngig davon, ob der Wert aus options.php<\/code> oder aus der REST-API stammt. Daraus ergeben sich zwei Anforderungen.<\/p>\n
Erstens ist add_settings_error()<\/code> in wp-admin\/includes\/template.php<\/code> definiert, einer Datei, die ein gew\u00f6hnlicher REST-Aufruf nicht l\u00e4dt. Die Pr\u00fcfung mit function_exists()<\/code> stellt deshalb sicher, dass die Funktion vor dem Aufruf verf\u00fcgbar ist. Zweitens muss der Callback idempotent sein: Wendet man ihn erneut auf sein eigenes Ergebnis an, muss dasselbe Ergebnis herauskommen. Fehlt die Option, bereinigt update_option()<\/code> einmal und add_option()<\/code> ein zweites Mal. Das Anlegen der Zeile bei der Aktivierung vermeidet diesen Doppeldurchlauf im Normalbetrieb. Der Callback darf sich darauf aber nicht verlassen.<\/p>\n
Kein Aufruf von settings_errors() auf der Seite<\/h3>\n
Bei Seiten unter \u201eEinstellungen\u201c bindet admin-header.php<\/code> die Datei options-head.php<\/code> ein, und die ruft settings_errors()<\/code> von sich aus auf. Ein zus\u00e4tzlicher Aufruf im Seiten-Callback w\u00fcrde jede Meldung doppelt ausgeben. Das Handbook-Beispiel verwendet eine Men\u00fcseite auf oberster Ebene und ruft settings_errors()<\/code> deshalb selbst auf. Ein weiteres Detail aus options.php<\/code>: Die Meldung \u201eDie Einstellungen wurden gespeichert.\u201c kommt nur hinzu, wenn keine andere Meldung registriert ist. Die Warnung aus dem Sanitize-Callback ersetzt sie, obwohl die \u00fcbrigen Werte gespeichert wurden.<\/p>\n
Was beim Speichern passiert<\/h2>\n
Das Formular sendet an options.php<\/code>, nicht an die Einstellungsseite. Die folgenden Schritte stammen direkt aus dem Core-Quelltext und gelten f\u00fcr jede Seite, die auf der Settings API aufbaut.<\/p>\n
\n\"Vom
options.php pr\u00fcft Capability, Nonce und Freigabeliste; REST m\u00fcndet bei update_option(), wo der Sanitize-Callback l\u00e4uft<\/figcaption><\/figure>\n
    \n
  1. settings_fields()<\/code> gibt vier versteckte Felder aus: option_page<\/code> mit dem Gruppennamen, action<\/code> mit dem Wert update<\/code>, die Nonce _wpnonce<\/code> f\u00fcr die Aktion lwsd_notice_bar-options<\/code> und _wp_http_referer<\/code> mit der Adresse, zu der options.php<\/code> nach dem Speichern zur\u00fcckleitet.<\/li>\n
  2. options.php<\/code> bestimmt die n\u00f6tige Capability: manage_options<\/code>, \u00e4nderbar \u00fcber den Filter option_page_capability_{$option_page}<\/code>. Fehlt sie, endet die Anfrage mit Status 403.<\/li>\n
  3. check_admin_referer( $option_page . '-options' )<\/code> pr\u00fcft die Nonce.<\/li>\n
  4. Die Gruppe muss auf der Freigabeliste stehen, die register_setting()<\/code> bef\u00fcllt und der Filter allowed_options<\/code> erweitern kann. Andernfalls bricht wp_die()<\/code> ab.<\/li>\n
  5. F\u00fcr jede registrierte Option wird der Wert aus $_POST<\/code> gelesen, bei skalaren Werten getrimmt, mit wp_unslash()<\/code> behandelt und an update_option()<\/code> \u00fcbergeben.<\/li>\n
  6. update_option()<\/code> f\u00fchrt sanitize_option()<\/code> und damit den Callback aus, danach die Filter pre_update_option<\/code>. Hat sich der Wert nicht ge\u00e4ndert, wird nichts geschrieben; sonst landet der serialisierte Wert in der Zeile.<\/li>\n
  7. Die gesammelten Meldungen wandern f\u00fcr 30 Sekunden in das Transient settings_errors<\/code>, danach folgt eine Weiterleitung mit settings-updated=true<\/code>. Nach der Weiterleitung liest settings_errors()<\/code> das Transient und gibt die Meldungen aus.<\/li>\n<\/ol>\n
    Schritt zwei hat eine praktische Folge. Ein Plugin, das seinen Men\u00fcpunkt Redakteuren mit der Capability edit_pages<\/code> zeigt, scheitert beim Speichern, solange der Filter option_page_capability_lwsd_notice_bar<\/code> weiterhin manage_options<\/code> verlangt. Men\u00fc, Seiten-Callback und Speichern m\u00fcssen dieselbe Capability voraussetzen. Warum eine Nonce allein nie die Rechtepr\u00fcfung ersetzt, vertieft ein eigener Beitrag dieser Reihe zu Sanitizing, Escaping, Nonces und Capabilities<\/a>.<\/p>\n
    register_setting und der REST-Endpunkt \/wp\/v2\/settings<\/h2>\n
    Registrierte Einstellungen erscheinen standardm\u00e4\u00dfig nicht in der REST-API. F\u00fcr skalare Typen gen\u00fcgt show_in_rest<\/code> mit dem Wert true<\/code>. Bei array<\/code> und object<\/code> braucht die Option ein Schema unter show_in_rest.schema<\/code>: F\u00fcr Arrays ohne items<\/code> meldet der Core einen _doing_it_wrong<\/code>-Hinweis (seit 5.4), f\u00fcr Objekte legen properties<\/code> fest, welche Schl\u00fcssel existieren. Der Controller baut das endg\u00fcltige Schema aus type<\/code>, label<\/code> (als title<\/code>), description<\/code> und default<\/code> und legt das Schema aus show_in_rest<\/code> dar\u00fcber. Zugelassen sind nur die Typen number<\/code>, integer<\/code>, string<\/code>, boolean<\/code>, array<\/code> und object<\/code>; alle anderen Einstellungen werden stillschweigend \u00fcbergangen.<\/p>\n
    Der Controller in class-wp-rest-settings-controller.php<\/code> beantwortet einige Fragen, die die Referenzseiten offenlassen:<\/p>\n