🛠 Ein benutzerdefiniertes Feld zu den WordPress-Einstellungen hinzufügen: add_settings_field

Standard-WordPress-Einstellungen decken die meisten alltäglichen Aufgaben ab. Früher oder später benötigen Sie jedoch ein Feld, das im Admin nicht existiert: eine Firmen-Telefonnummer im Bereich Allgemein, einen Service-API-Schlüssel, ein Feld für eine Lizenznummer oder einen Footer-Text.

Theme- und Plugin-Entwickler lösen dies über die Settings API, eine Reihe von WordPress-Funktionen zum Registrieren eigener Abschnitte und Felder auf den standardmäßigen Einstellungsseiten. Die zentrale Funktion ist add_settings_field(): Sie fügt einer angegebenen Sektion und Seite ein benutzerdefiniertes Feld hinzu.

Am Ende dieses Tutorials verfügen Sie über funktionierenden Code, der ein Textfeld im Admin ausgibt, den Wert in der Datenbank speichert und auf der Website anzeigt. Keine Drittanbieter-Plugins, nur die eingebaute API.

💡 Kurzüberblick:

• Bereiten Sie Ihre Umgebung vor: Erstellen Sie ein Child-Theme oder installieren Sie das Code Snippets-Plugin, damit Ihr Code bei einem Update des Parent-Themes nicht überschrieben wird.
• Registrieren Sie die Einstellung: Rufen Sie register_setting() am admin_init-Hook auf, andernfalls speichert WordPress die Felddaten nicht.
• Fügen Sie einen Abschnitt und ein Feld hinzu: Verwenden Sie add_settings_section() für einen neuen Block und add_settings_field() für das Eingabefeld darin.
• Geben Sie den Wert aus: Nutzen Sie get_option() an beliebiger Stelle in einem Template, um die gespeicherten Daten auf der Website anzuzeigen.

Was add_settings_field ist und wo es eingesetzt wird

Die Funktion add_settings_field() erschien in WordPress 2.7.0 und ist seitdem das primäre Werkzeug zur Erweiterung von Einstellungsseiten. Laut der WordPress-Dokumentation fügt sie einer bestehenden Sektion auf einer der Admin-Seiten ein neues Feld hinzu.

Was das in der Praxis bedeutet. Sie können ein zusätzliches Feld auf jeder Standardseite ausgeben: Allgemein (general), Schreiben (writing), Lesen (reading), Diskussion (discussion) oder Medien (media). Und wenn Sie über add_options_page() eine eigene Einstellungsseite erstellt haben, kommt das Feld ebenfalls dorthin.

Typische Szenarien:

• Ein Feld „Telefon Kontakt" im Bereich Allgemeine Einstellungen, damit der Manager die Nummer aktualisieren kann, ohne Code anfassen zu müssen.
• Ein API-Schlüssel-Feld für Ihr Plugin, in dem der Nutzer den Schlüssel im Admin eingibt, anstatt die wp-config.php zu bearbeiten.
• Eine Gruppe von Feldern für einen eigenen Abschnitt (Telefon, E-Mail, Adresse) unter Verwendung von add_settings_section() plus mehreren add_settings_field()-Aufrufen.

Hinweis: add_settings_field() gibt nur das Feld-HTML aus. Das eigentliche Speichern übernimmt register_setting(); ohne diese Funktion ignoriert WordPress die eingegebenen Daten.

Syntax und Parameter von add_settings_field

Die Funktionssignatur, vier erforderliche und zwei optionale Parameter:

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

Gehen wir jeden Parameter durch.

$id, die eindeutige Feldkennung. Dieser Wert wird zum HTML-id-Attribut des <input>-Tags, das Sie in der Callback-Funktion ausgeben. Verwenden Sie ein Präfix, um Konflikte zu vermeiden, zum Beispiel myplugin_phone_number.

$title, die Feldbezeichnung, die im Admin links neben dem Eingabefeld angezeigt wird. Formulieren Sie sie klar: „Telefon Kontakt", „Service-API-Schlüssel".

$callback, der Name Ihrer Funktion, die das Feld-HTML ausgibt (input, textarea, select). Hier schreiben Sie echo. Die Funktion muss zuvor deklariert sein; übergeben Sie sie als String: 'my_field_callback'.

$page, der Slug der Einstellungsseite. Standardwerte: general, reading, writing, discussion und media. Wenn Sie eine eigene Seite erstellt haben, verwenden Sie deren Slug. Bestimmt, wo das Feld erscheint.

$section (optional), der Slug des Abschnitts, zu dem das Feld gehört. Standard ist 'default', der oberste Abschnitt auf der Seite. Wenn Sie über add_settings_section() einen eigenen Abschnitt erstellt haben, geben Sie hier dessen ID an.

$args (optional), ein Array mit zusätzlichen Einstellungen. Unterstützte Schlüssel sind label_for (der Wert des HTML-for-Attributs am <label>) und class (eine CSS-Klasse für den Feld-Wrapper).

Alle Parameter und ihr Verhalten sind im offiziellen Settings-API-Leitfaden auf WordPress.org beschrieben.

Praxisbeispiel: Ein Textfeld zu den Allgemeinen Einstellungen hinzufügen

Setzen wir alles zusammen. Das Ziel: Ein Textfeld „Telefon Kontakt" auf der Seite Einstellungen → Allgemein ausgeben, den eingegebenen Wert speichern und mit get_option() abrufen.

Der Code kommt in die functions.php des Child-Themes oder über das Code Snippets-Plugin. Die zweite Option ist sicherer: Der Snippet wird bei einem Theme-Update nicht gelöscht.

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

Was hier Zeile für Zeile passiert. register_setting() teilt WordPress mit: Speichere den Wert des Feldes my_contact_phone als Option in der Tabelle wp_options, wenn auf der Seite general auf „Änderungen speichern" geklickt wird.

add_settings_section() erstellt einen neuen Block mit der Überschrift „Organisationskontakte" auf der Seite Allgemeine Einstellungen. Der Callback my_custom_section_callback() gibt den Beschreibungstext oberhalb der Abschnittsfelder aus.

add_settings_field() platziert unser Feld innerhalb dieses Abschnitts und verknüpft es mit dem Callback my_phone_field_callback(), der <input type="text"> rendert. Die Funktion get_option() fügt den gespeicherten Wert in das value-Attribut ein, und esc_attr() escaped die Ausgabe.

Der gesamte Code ist an admin_init gehängt, das beim Laden des Admins feuert und garantiert, dass Abschnitt und Feld bereits registriert sind, wenn die Einstellungsseite gerendert wird.

Nachdem Sie den Code hinzugefügt haben, öffnen Sie wp-admin/options-general.php und Sie sehen das Ergebnis:

Geben Sie eine Nummer ein, klicken Sie auf Änderungen speichern, und der Wert wird in die Datenbank geschrieben. Um die Telefonnummer auf der Website anzuzeigen, verwenden Sie get_option() an beliebiger Stelle in einem Template:

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

Wo der Code platziert wird und wie man testet

Drei Platzierungsoptionen, von der schlechtesten zur besten.

Parent-Theme (functions.php). Tun Sie das nicht. Wenn das Theme aktualisiert wird, wird die Datei überschrieben und Ihre Anpassung verschwindet.

Child-Theme (****functions.php** des Child-Themes).** Eine brauchbare Option für Änderungen, die an eine bestimmte Website gebunden sind. Der Code überlebt Updates des Parent-Themes.

Code Snippets Plugin. Die beste Wahl für Tests und langfristige Wartung. Sie können den Snippet mit einem Klick aktivieren/deaktivieren, ohne das Dateisystem zu berühren. Zudem erhalten Sie Isolation: Verursacht der Snippet einen fatalen Fehler, deaktiviert WordPress ihn automatisch und die Website geht nicht offline.

Testverfahren. Erstellen Sie ein vollständiges Backup der Website (Datenbank + Dateien), das ist die übliche Vorsichtsmaßnahme bei jeder Admin-Bearbeitung. Fügen Sie den Code mit der von Ihnen gewählten Methode hinzu. Öffnen Sie die Einstellungsseite und prüfen Sie, ob das Feld angezeigt wird. Geben Sie einen Wert ein und speichern Sie. Prüfen Sie die Persistenz: Aktualisieren Sie die Seite, das Feld sollte mit dem von Ihnen eingegebenen Wert gefüllt sein.

Wenn das Feld nicht erscheint, prüfen Sie, ob Sie die Abschnitts-ID im Parameter $section von add_settings_field() nicht verwechselt haben. Ein häufiger Fehler: Der Abschnitt wird mit einer ID erstellt, aber eine andere wird an das Feld übergeben.

Video-Tutorial zum Thema

Zur Vertiefung des Stoffs sehen Sie sich eine Video-Anleitung zur Settings API von einem WordPress-Entwickler an. Sie zeigt den vollständigen Zyklus: Abschnitt registrieren, Feld hinzufügen, speichern und auf der Website ausgeben.

⁉️🤔 Häufig gestellte Fragen

Kann ich einem Abschnitt mehrere Felder hinzufügen?

Ja. Rufen Sie add_settings_field() so oft auf, wie Sie Felder benötigen. Übergeben Sie dieselbe Abschnitts-ID im Parameter $section. Jedes Feld erhält eine eindeutige $id und einen eigenen Callback. Die Reihenfolge der add_settings_field()-Aufrufe bestimmt die Feldreihenfolge auf der Seite.

Wie füge ich ein Select, eine Textarea oder eine Checkbox anstelle eines Textfelds hinzu?

Der Feldtyp wird innerhalb der Callback-Funktion per HTML festgelegt. Für ein Select erstellen Sie ein <select> mit <option>-Tags; für eine Textarea ein <textarea>-Tag; für eine Checkbox <input type="checkbox">. Der Wert wird auf dieselbe Weise über register_setting() gespeichert und über get_option() abgerufen. Die Besonderheiten liegen nur im HTML.

Muss ich die Ausgabe im Callback escapen?

Ja, unbedingt. Verwenden Sie esc_attr() für Attributwerte (value, name, id) und esc_html() für Text zwischen Tags. Dies schützt vor XSS und stellt sicher, dass Sonderzeichen im gespeicherten Wert das Layout nicht zerstören.

Kann ich ein Feld zur Seite meines eigenen Plugins hinzufügen?

Ja. Erstellen Sie eine Seite über add_options_page() oder add_menu_page() und registrieren Sie dann Abschnitte und Felder auf dieselbe Weise. Verwenden Sie den Slug Ihrer Seite im Parameter $page von add_settings_field(). Die Mechanik unterscheidet sich nicht von Standardseiten.

Was tun, wenn der Wert nach dem Klick auf „Änderungen speichern" nicht gespeichert wird?

Sie haben mit ziemlicher Sicherheit register_setting() ausgelassen. Ohne diese Funktion weiß WordPress nicht, dass das Feld gespeichert werden muss, und ignoriert es beim Absenden. Prüfen Sie: Der erste Parameter von register_setting() muss mit dem Seitennamen übereinstimmen (z. B. 'general'), und der zweite muss mit dem name-Attribut Ihres Feldes übereinstimmen.

Fazit: Wann die Erweiterung der Admin-Einstellungen sinnvoll ist

Die WordPress Settings API ist ein ausgereifter und stabiler Mechanismus: add_settings_field() hat sich seit Version 2.7 nicht verändert und ist auch 2026 noch relevant. Das Hinzufügen eigener Felder zum Admin ist in drei Fällen gerechtfertigt:

• Sie entwickeln ein Theme oder Plugin und möchten dem Nutzer eine Oberfläche zur Dateneingabe bieten, ohne dass er Code bearbeiten muss.
• Sie benötigen ein Einstellungsfeld auf Website-Ebene (Telefonnummer, API-Schlüssel, Katalog-ID) und es soll über den Admin zugänglich sein, nicht über wp-config.php.
• Sie passen eine Kunden-Website an und möchten, dass der Manager Daten selbst ändern kann, ohne den Entwickler kontaktieren zu müssen.

Wenn das Feld nur für Sie ist und sich einmal im Jahr ändert, ist es einfacher, den Wert fest zu codieren. Die Settings API glänzt dort, wo Einstellungen von jemand anderem als dem Entwickler genutzt werden.

Fangen Sie einfach an: Fügen Sie ein Textfeld nach dem obigen Beispiel hinzu. Wenn Sie den grundlegenden Ablauf beherrschen, Registrierung, Callback, Speichern, Ausgabe,, gehen Sie zu Selects, Feldgruppen und benutzerdefinierten Einstellungsseiten über. Und mit welchem Feldtyp arbeiten Sie am häufigsten? Lassen Sie es uns in den Kommentaren wissen.