Einstellungsseiten und Options API

Fast jedes Plugin braucht Einstellungen: eine E-Mail-Adresse für Benachrichtigungen, eine Farbe, einen Schalter für eine Funktion. WordPress bietet dafür zwei Bausteine. Die Options API speichert Werte dauerhaft in der Datenbank, die Settings API baut daraus eine Einstellungsseite, die Nonces, Rechte und Bereinigung automatisch mitbringt. Wer beides richtig nutzt, erspart sich viel Sicherheitscode – und wer Autoload bewusst einsetzt, sorgt dafür, dass die Website trotz vieler Plugins schnell bleibt.

1. Die Options API

Gute Praxis ist, alle Einstellungen eines Plugins in einer einzigen Option als Array zu speichern statt in zehn einzelnen Optionen. Das hält die Tabelle übersichtlich, und die Deinstallation muss nur einen Eintrag löschen.

1<?php
2$standard = [ 'farbe' => '#21759b', 'vorlauf' => 24, 'mail' => '' ];
3$einst    = wp_parse_args( get_option( 'radwerk_einstellungen', [] ), $standard );
4
5echo esc_html( $einst['vorlauf'] );          // 24
6
7update_option( 'radwerk_einstellungen', $einst, false );  // false = kein Autoload

2. Autoload bewusst einsetzen

Alle Optionen mit Autoload landen bei jedem Aufruf im Speicher – auch dann, wenn sie gar nicht gebraucht werden. Viele Plugins speichern dort Protokolle, Caches oder große Datenmengen, und plötzlich lädt jede Seite mehrere Megabyte aus der Datenbank. Seit Version 6.6 entscheidet WordPress bei großen Optionen selbst, sie nicht automatisch zu laden, und der Website-Zustand warnt vor zu viel Autoload. Besser ist es, die Frage selbst bewusst zu beantworten:

3. Die Settings API

Eine Einstellungsseite von Hand zu bauen bedeutet: Formular, Nonce, Rechteprüfung, Bereinigung, Speichern, Fehlermeldungen. Die Settings API übernimmt das meiste davon. Man registriert eine Einstellung mit einer Bereinigungsfunktion, legt Abschnitte und Felder an und ruft im Formular zwei Hilfsfunktionen auf. Den Rest – Nonce, Speichern über options.php, Erfolgsmeldung – erledigt WordPress.

1<?php
2add_action( 'admin_init', function () {
3    register_setting( 'radwerk', 'radwerk_einstellungen', [
4        'type'              => 'array',
5        'sanitize_callback' => [ $this, 'bereinigen' ],
6        'show_in_rest'      => false,
7    ] );
8} );
9
10public function bereinigen( $ein ): array {
11    return [
12        'farbe'   => sanitize_hex_color( $ein['farbe'] ?? '' ) ?: '#21759b',
13        'vorlauf' => min( 168, absint( $ein['vorlauf'] ?? 24 ) ),
14        'mail'    => sanitize_email( $ein['mail'] ?? '' ),
15    ];
16}

1// noch nichts gespeichert

4. Moderne Einstellungsseiten

Neuere Plugins bauen Einstellungsseiten zunehmend mit denselben React-Komponenten wie der Block-Editor. Die Oberfläche lädt die Werte über die REST API (Endpunkt /wp/v2/settings, wenn show_in_rest aktiv ist) und speichert sie dort wieder. Das Ergebnis wirkt einheitlich mit dem Rest des Backends und reagiert ohne Neuladen. Die Registrierung mit register_setting und die Bereinigung bleiben gleich – nur die Oberfläche ändert sich. Für einfache Plugins ist die klassische Settings API dennoch völlig ausreichend und schneller umgesetzt.

Ein Beispiel und typische Fehler

Ein Hotel nutzt ein kleines Plugin für Anfragen zu Arrangements. Die Einstellungsseite hat drei Abschnitte: Empfänger der Anfragen, Texte der Bestätigungsmail und Sperrzeiten, in denen keine Anfragen angenommen werden. Alle Werte liegen in einer Option mit Autoload, weil sie klein sind und auf jeder Arrangement-Seite gebraucht werden. Ein Protokoll der letzten Anfragen liegt dagegen nicht in einer Option, sondern als eigener Inhaltstyp ohne öffentliche Seiten. Das Team kann Empfänger und Texte selbst ändern, und die Bereinigung verhindert, dass versehentlich eine ungültige Adresse gespeichert wird.

Typische Fehler bei Einstellungen sind: Werte ohne Bereinigung speichern, weil „nur Administratoren“ Zugriff haben – doch auch deren Konten können übernommen werden. Formulare selbst verarbeiten und dabei Nonce oder Rechteprüfung vergessen. Standardwerte an zehn Stellen im Code wiederholen, statt sie einmal zentral festzulegen. Und bei jeder Anfrage get_option in Schleifen aufrufen: Das ist zwar dank Cache schnell, macht den Code aber unübersichtlich. Besser ist eine kleine Klasse, die die Einstellungen einmal lädt und mit Standardwerten zusammenführt.

5. Häufige Fragen

Wo speichere ich API-Schlüssel? Idealerweise nicht in der Datenbank, sondern als Konstante in wp-config.php oder als Umgebungsvariable, damit sie nicht in Datenbank-Backups landen. Für KI-Anbieter übernimmt seit WordPress 7.0 die zentrale Verwaltung der Connectors diese Aufgabe – mehr dazu in Lektion 7.

Wie lege ich Einstellungen pro Benutzer ab? Mit User Meta (get_user_meta, update_user_meta). Optionen gelten für die ganze Website.

Was ist mit Multisite? Für netzwerkweite Einstellungen gibt es get_site_option und update_site_option. Normale Optionen gelten je Website im Netzwerk.

6. Übung zum Selbermachen

Bauen Sie für Ihr Übungsplugin eine Einstellungsseite mit zwei Feldern: dem Hinweistext und einem Schalter, ob der Hinweis auch auf Seiten erscheinen soll. Verwenden Sie register_setting mit einer Bereinigungsfunktion, die den Text mit sanitize_textarea_field bereinigt und den Schalter in einen echten Wahrheitswert umwandelt. Prüfen Sie im Browser, dass das Formular ein verstecktes Feld _wpnonce enthält, und versuchen Sie, das Formular als Benutzer mit der Rolle „Redakteur“ aufzurufen.

Stand: September 2026, WordPress 7.1, PHP 8.3. Kursmaterial der Klarwerk Akademie. WordPress entwickelt sich schnell – maßgeblich ist die aktuelle Dokumentation auf developer.wordpress.org.