🛠 Aggiungere un campo personalizzato alle impostazioni di WordPress: add_settings_field

Standard WordPress settings coprono la maggior parte delle attività quotidiane. Ma prima o poi serve un campo che non esiste nell'amministrazione: un numero di telefono aziendale nella sezione Generale, una chiave API di un servizio, un campo per il numero di licenza o il testo del footer.

Gli sviluppatori di temi e plugin gestiscono questa esigenza tramite la Settings API, un insieme di funzioni WordPress per registrare sezioni e campi personalizzati nelle pagine delle impostazioni standard. La funzione chiave è add_settings_field(): aggiunge un campo personalizzato a una sezione e a una pagina specificate.

Alla fine di questo tutorial avrai un codice funzionante che mostra un campo di testo nell'amministrazione, salva il valore nel database e lo visualizza sul sito. Nessun plugin di terze parti, solo l'API integrata.

💡 Panoramica rapida:

• Prepara l'ambiente: crea un tema child o installa il plugin Code Snippets così il tuo codice non verrà cancellato quando il tema principale si aggiorna.
• Registra l'impostazione: chiama register_setting() sull'hook admin_init, altrimenti WordPress non salverà i dati del campo.
• Aggiungi una sezione e un campo: usa add_settings_section() per un nuovo blocco e add_settings_field() per il campo di input al suo interno.
• Mostra il valore: usa get_option() in qualsiasi punto di un template per visualizzare il dato salvato sul sito.

Cos'è add_settings_field e dove si usa

La funzione add_settings_field() è comparsa in WordPress 2.7.0 e da allora è rimasta lo strumento principale per estendere le pagine delle impostazioni. Secondo la documentazione di WordPress, aggiunge un nuovo campo a una sezione esistente in una delle pagine di amministrazione.

Cosa significa in pratica. Puoi mostrare un campo extra su qualsiasi pagina standard: Generale (general), Scrittura (writing), Lettura (reading), Discussione (discussion) o Media (media). E se hai creato una tua pagina delle impostazioni tramite add_options_page(), il campo apparirà anche lì.

Scenari tipici:

• Un campo "Telefono di contatto" nelle impostazioni generali, così il manager non deve toccare il codice per aggiornare il numero.
• Un campo per la chiave API del tuo plugin, dove l'utente inserisce la chiave nell'amministrazione invece di modificare wp-config.php.
• Un gruppo di campi per una sezione personalizzata (telefono, email, indirizzo), usando add_settings_section() più chiamate multiple a add_settings_field().

Nota: add_settings_field() si occupa solo di generare l'HTML del campo. Il salvataggio effettivo è gestito da register_setting(); senza di essa WordPress ignorerà i dati inseriti.

Sintassi e parametri di add_settings_field

La firma della funzione, quattro parametri obbligatori e due opzionali:

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

Analizziamo ogni parametro.

$id, l'identificatore univoco del campo. Questo valore diventa l'attributo HTML id del tag <input> che generi nella funzione di callback. Usa un prefisso per evitare conflitti, ad esempio myplugin_phone_number.

$title, l'etichetta del campo mostrata nell'amministrazione a sinistra dell'input stesso. Scrivila in modo chiaro: "Telefono di contatto", "Chiave API del servizio".

$callback, il nome della tua funzione che genera l'HTML del campo (input, textarea, select). È qui che scrivi echo. La funzione deve essere dichiarata in precedenza; passala come stringa: 'my_field_callback'.

$page, lo slug della pagina delle impostazioni. Valori standard: general, reading, writing, discussion e media. Se hai creato una pagina personalizzata, usa il suo slug. Determina dove apparirà il campo.

$section (opzionale), lo slug della sezione a cui appartiene il campo. Il valore predefinito è 'default', che corrisponde alla sezione più in alto nella pagina. Se hai creato una tua sezione tramite add_settings_section(), specifica qui il suo ID.

$args (opzionale), un array di impostazioni extra. Le chiavi supportate sono label_for (il valore dell'attributo HTML for sul <label>) e class (una classe CSS per il contenitore del campo).

Tutti i parametri e il loro comportamento sono descritti nella guida ufficiale alla Settings API su WordPress.org.

Esempio pratico: aggiungere un campo di testo alle Impostazioni generali

Mettiamo tutto insieme. L'obiettivo: mostrare un campo di testo "Telefono di contatto" nella pagina Impostazioni → Generale, salvare il valore inserito e recuperarlo con get_option().

Il codice va nel functions.php del tema child o tramite il plugin Code Snippets. La seconda opzione è più sicura: lo snippet non verrà cancellato con un aggiornamento del tema.

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

Cosa succede qui riga per riga. register_setting() dice a WordPress: salva il valore del campo my_contact_phone come opzione nella tabella wp_options quando si clicca "Salva modifiche" sulla pagina general.

add_settings_section() crea un nuovo blocco con l'intestazione "Contatti dell'organizzazione" nella pagina delle impostazioni generali. La callback my_custom_section_callback() genera il testo descrittivo sopra i campi della sezione.

add_settings_field() posiziona il nostro campo all'interno di quella sezione e lo collega alla callback my_phone_field_callback(), che renderizza <input type="text">. La funzione get_option() inserisce il valore salvato nell'attributo value, e esc_attr() esegue l'escape dell'output.

Tutto il codice è agganciato a admin_init, che si attiva quando l'amministrazione viene caricata e garantisce che la sezione e il campo siano già registrati nel momento in cui la pagina delle impostazioni viene renderizzata.

Dopo aver aggiunto il codice, apri wp-admin/options-general.php e vedrai il risultato:

Inserisci un numero, clicca Salva modifiche e il valore viene scritto nel database. Per mostrare il numero di telefono sul sito, usa get_option() in qualsiasi punto di un template:

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

Dove inserire il codice e come testarlo

Tre opzioni di posizionamento, dalla peggiore alla migliore.

Tema principale (functions.php). Non farlo. Quando il tema si aggiorna, il file viene sovrascritto e la tua personalizzazione scompare.

Tema child (****functions.php** del tema child).** Un'opzione praticabile per modifiche legate a un sito specifico. Il codice sopravvive agli aggiornamenti del tema principale.

Plugin Code Snippets. La scelta migliore per test e manutenzione a lungo termine. Puoi attivare/disattivare lo snippet con un clic, senza toccare il filesystem. Inoltre hai isolamento: se lo snippet causa un errore fatale, WordPress lo disattiva automaticamente e il sito non andrà offline.

Procedura di test. Crea un backup completo del sito (database + file), questa è una precauzione standard per qualsiasi modifica all'amministrazione. Aggiungi il codice usando il metodo scelto. Apri la pagina delle impostazioni e verifica che il campo sia visualizzato. Inserisci un valore e salva. Verifica la persistenza: aggiorna la pagina, il campo dovrebbe essere popolato con ciò che hai inserito.

Se il campo non appare, controlla di non aver confuso l'ID della sezione nel parametro $section di add_settings_field(). Un errore comune: la sezione viene creata con un ID, ma ne viene passato uno diverso al campo.

Video tutorial sull'argomento

Per consolidare i concetti, guarda una dimostrazione video della Settings API tenuta da uno sviluppatore WordPress. Mostra il ciclo completo: registrazione di una sezione, aggiunta di un campo, salvataggio e visualizzazione sul sito.

⁉️🤔 Domande frequenti

Posso aggiungere più campi a una sezione?

Sì. Chiama add_settings_field() tante volte quanti sono i campi necessari. Passa lo stesso ID di sezione nel parametro $section. Ogni campo riceve un $id univoco e una propria callback. L'ordine delle chiamate a add_settings_field() determina l'ordine dei campi nella pagina.

Come aggiungo una select, una textarea o una checkbox invece di un campo di testo?

Il tipo di campo viene impostato all'interno della funzione di callback tramite HTML. Per una select, costruisci un <select> con tag <option>; per una textarea, un tag <textarea>; per una checkbox, <input type="checkbox">. Il valore viene salvato allo stesso modo tramite register_setting() e recuperato con get_option(). Le specificità sono solo nell'HTML.

Devo eseguire l'escape dell'output nella callback?

Sì, assolutamente. Usa esc_attr() per i valori degli attributi (value, name, id) e esc_html() per il testo tra i tag. Questo protegge da XSS e garantisce che i caratteri speciali nel valore salvato non rompano il layout.

Posso aggiungere un campo alla pagina del mio plugin?

Sì. Crea una pagina tramite add_options_page() o add_menu_page(), poi registra sezioni e campi allo stesso modo. Usa lo slug della tua pagina nel parametro $page di add_settings_field(). La meccanica non è diversa dalle pagine standard.

Cosa fare se il valore non viene salvato dopo aver cliccato "Salva modifiche"?

Quasi sicuramente hai saltato register_setting(). Senza questa funzione, WordPress non sa che il campo deve essere salvato e lo ignora all'invio. Verifica: il primo parametro di register_setting() deve corrispondere al nome della pagina (es. 'general'), e il secondo deve corrispondere all'attributo name del tuo campo.

Conclusione: quando ha senso estendere le impostazioni dell'amministrazione

La WordPress Settings API è un meccanismo maturo e stabile: add_settings_field() non è cambiata dalla versione 2.7 e rimane rilevante nel 2026. Aggiungere campi personalizzati all'amministrazione è giustificato in tre casi:

• Stai sviluppando un tema o un plugin e vuoi dare all'utente un'interfaccia per inserire dati, senza modificare il codice.
• Hai bisogno di un campo di impostazione a livello di sito (numero di telefono, chiave API, ID catalogo) e deve essere accessibile dall'amministrazione, non da wp-config.php.
• Stai personalizzando il sito di un cliente e vuoi che il manager possa modificare i dati in autonomia senza contattare lo sviluppatore.

Se il campo serve solo a te e cambia una volta all'anno, è più semplice inserire il valore direttamente nel codice. La Settings API dà il meglio di sé quando le impostazioni sono usate da qualcuno che non sia lo sviluppatore.

Inizia in modo semplice: aggiungi un campo di testo seguendo l'esempio sopra. Una volta padroneggiato il flusso di base, registrazione, callback, salvataggio, output, passa alle select, ai gruppi di campi e alle pagine delle impostazioni personalizzate. E con quale tipo di campo lavori più spesso? Faccelo sapere nei commenti.