🛠 Ajouter un champ personnalisé aux réglages WordPress : add_settings_field

Les réglages standard de WordPress couvrent la plupart des tâches quotidiennes. Mais tôt ou tard, vous avez besoin d’un champ qui n’existe pas dans l’administration: un numéro de téléphone de l’entreprise dans la section Général, une clé API de service, un champ de numéro de licence ou un texte de pied de page.

Les développeurs de thèmes et d’extensions gèrent cela via l’API Settings, un ensemble de fonctions WordPress qui permettent d’enregistrer leurs propres sections et champs sur les pages de réglages standard. La fonction clé est add_settings_field(): elle ajoute un champ personnalisé à une section et une page spécifiées.

À la fin de ce tutoriel, vous disposerez d’un code fonctionnel qui affiche un champ texte dans l’administration, enregistre la valeur dans la base de données et l’affiche sur le site. Pas d’extension tierce, uniquement l’API native.

💡 Aperçu rapide:

• Préparez votre environnement: créez un thème enfant ou installez l’extension Code Snippets pour que votre code ne soit pas effacé lors de la mise à jour du thème parent.
• Enregistrez le réglage: appelez register_setting() sur le hook admin_init, sinon WordPress n’enregistrera pas la donnée du champ.
• Ajoutez une section et un champ: utilisez add_settings_section() pour un nouveau bloc et add_settings_field() pour le champ de saisie à l’intérieur.
• Affichez la valeur: utilisez get_option() n’importe où dans un template pour afficher la donnée enregistrée sur le site.

Qu’est-ce que add_settings_field et où l’utilise-t-on

La fonction add_settings_field() est apparue dans WordPress 2.7.0 et est restée depuis l’outil principal pour étendre les pages de réglages. Selon la documentation WordPress, elle ajoute un nouveau champ à une section existante sur l’une des pages d’administration.

Ce que cela signifie en pratique. Vous pouvez afficher un champ supplémentaire sur n’importe quelle page standard: Général (general), Écriture (writing), Lecture (reading), Discussion (discussion) ou Médias (media). Et si vous avez créé votre propre page de réglages via add_options_page(), le champ y sera également placé.

Scénarios typiques:

• Un champ «Téléphone de contact» dans la section des réglages généraux, pour que le responsable n’ait pas besoin de toucher au code pour mettre à jour le numéro.
• Un champ de clé API pour votre extension, où l’utilisateur saisit la clé dans l’administration au lieu de modifier wp-config.php.
• Un groupe de champs pour une section personnalisée (téléphone, email, adresse), en utilisant add_settings_section() et plusieurs appels à add_settings_field().

Remarque: add_settings_field() ne fait qu’afficher le HTML du champ. L’enregistrement effectif est géré par register_setting(); sans cela, WordPress ignorera la donnée saisie.

Syntaxe et paramètres de add_settings_field

La signature de la fonction, quatre paramètres obligatoires et deux optionnels:

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

Passons en revue chaque paramètre.

$id, l’identifiant unique du champ. Cette valeur devient l’attribut HTML id de la balise <input> que vous générez dans la fonction de callback. Utilisez un préfixe pour éviter les conflits, par exemple myplugin_phone_number.

$title, l’étiquette du champ affichée dans l’administration à gauche de la saisie elle-même. Rédigez-la clairement: «Téléphone de contact», «Clé API du service».

$callback, le nom de votre fonction qui génère le HTML du champ (input, textarea, select). C’est ici que vous écrivez echo. La fonction doit être déclarée au préalable; passez-la sous forme de chaîne: 'my_field_callback'.

$page, le slug de la page de réglages. Valeurs standard: general, reading, writing, discussion et media. Si vous avez créé une page personnalisée, utilisez son slug. Détermine où le champ apparaît.

$section (optionnel), le slug de la section à laquelle le champ appartient. La valeur par défaut est 'default', qui correspond à la section tout en haut de la page. Si vous avez créé votre propre section via add_settings_section(), indiquez son ID ici.

$args (optionnel), un tableau de paramètres supplémentaires. Les clés prises en charge sont label_for (la valeur de l’attribut HTML for sur le <label>) et class (une classe CSS pour le conteneur du champ).

Tous les paramètres et leur comportement sont décrits dans le guide officiel de l’API Settings sur WordPress.org.

Exemple pratique: ajouter un champ texte aux Réglages généraux

Mettons tout cela en pratique. L’objectif: afficher un champ texte «Téléphone de contact» sur la page Réglages → Général, enregistrer la valeur saisie et la récupérer avec get_option().

Le code se place dans le fichier functions.php du thème enfant ou via l’extension Code Snippets. La seconde option est plus sûre: le snippet ne sera pas effacé lors d’une mise à jour du thème.

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

Voici ce qui se passe ligne par ligne. register_setting() indique à WordPress: enregistre la valeur du champ my_contact_phone comme une option dans la table wp_options quand on clique sur «Enregistrer les modifications» sur la page general.

add_settings_section() crée un nouveau bloc avec le titre «Coordonnées de l’organisation» sur la page des réglages généraux. La fonction de callback my_custom_section_callback() affiche le texte de description au-dessus des champs de la section.

add_settings_field() place notre champ dans cette section et le lie à la fonction de callback my_phone_field_callback(), qui génère <input type="text">. La fonction get_option() insère la valeur enregistrée dans l’attribut value, et esc_attr() échappe la sortie.

Tout le code est accroché à admin_init, qui se déclenche au chargement de l’administration et garantit que la section et le champ sont déjà enregistrés au moment où la page de réglages s’affiche.

Après avoir ajouté le code, ouvrez wp-admin/options-general.php et vous verrez le résultat:

Saisissez un numéro, cliquez sur Enregistrer les modifications, et la valeur est écrite dans la base de données. Pour afficher le numéro de téléphone sur le site, utilisez get_option() n’importe où dans 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
}

Où placer le code et comment tester

Trois options de placement, de la moins bonne à la meilleure.

Thème parent (functions.php). Ne faites pas cela. Lorsque le thème se met à jour, le fichier est écrasé et votre personnalisation disparaît.

Thème enfant (****functions.php** du thème enfant).** Une option viable pour des modifications liées à un site spécifique. Le code survit aux mises à jour du thème parent.

Extension Code Snippets. Le meilleur choix pour les tests et la maintenance à long terme. Vous pouvez activer/désactiver le snippet en un clic, sans toucher au système de fichiers. De plus, vous bénéficiez d’une isolation: si le snippet provoque une erreur fatale, WordPress le désactive automatiquement et le site ne tombe pas.

Procédure de test. Créez une sauvegarde complète du site (base de données + fichiers), c’est une précaution standard pour toute modification de l’administration. Ajoutez le code en utilisant la méthode choisie. Ouvrez la page de réglages et vérifiez que le champ s’affiche. Saisissez une valeur et enregistrez. Vérifiez la persistance: actualisez la page, le champ doit contenir ce que vous avez saisi.

Si le champ n’apparaît pas, vérifiez que vous n’avez pas confondu l’ID de section dans le paramètre $section de add_settings_field(). Une erreur courante: la section est créée avec un ID, mais un ID différent est passé au champ.

Tutoriel vidéo sur le sujet

Pour consolider la matière, regardez une démonstration vidéo de l’API Settings par un développeur WordPress. Elle montre le cycle complet: enregistrement d’une section, ajout d’un champ, sauvegarde et affichage sur le site.

⁉️🤔 Foire aux questions

Puis-je ajouter plusieurs champs à une même section?

Oui. Appelez add_settings_field() autant de fois que vous avez besoin de champs. Passez le même ID de section dans le paramètre $section. Chaque champ reçoit un $id unique et son propre callback. L’ordre des appels à add_settings_field() détermine l’ordre des champs sur la page.

Comment ajouter une liste déroulante, une zone de texte ou une case à cocher au lieu d’un champ texte?

Le type de champ est défini dans la fonction de callback via le HTML. Pour une liste déroulante, construisez un <select> avec des balises <option>; pour une zone de texte, une balise <textarea>; pour une case à cocher, <input type="checkbox">. La valeur est enregistrée de la même manière via register_setting() et récupérée via get_option(). Les spécificités résident uniquement dans le HTML.

Dois-je échapper la sortie dans le callback?

Oui, absolument. Utilisez esc_attr() pour les valeurs d’attributs (value, name, id) et esc_html() pour le texte entre les balises. Cela protège contre les failles XSS et garantit que les caractères spéciaux dans la valeur enregistrée ne cassent pas la mise en page.

Puis-je ajouter un champ à la page de ma propre extension?

Oui. Créez une page via add_options_page() ou add_menu_page(), puis enregistrez les sections et les champs de la même manière. Utilisez le slug de votre page dans le paramètre $page de add_settings_field(). Le mécanisme est identique à celui des pages standard.

Que faire si la valeur ne s’enregistre pas après avoir cliqué sur «Enregistrer les modifications»?

Vous avez presque certainement omis register_setting(). Sans cette fonction, WordPress ne sait pas que le champ doit être enregistré et l’ignore lors de la soumission. Vérifiez: le premier paramètre de register_setting() doit correspondre au nom de la page (par exemple 'general'), et le second doit correspondre à l’attribut name de votre champ.

En résumé: quand étendre les réglages de l’administration a du sens

L’API Settings de WordPress est un mécanisme mature et stable: add_settings_field() n’a pas changé depuis la version 2.7 et reste pertinent en 2026. Ajouter vos propres champs à l’administration se justifie dans trois cas:

• Vous développez un thème ou une extension et souhaitez offrir à l’utilisateur une interface pour saisir des données, sans modifier le code.
• Vous avez besoin d’un champ de réglage au niveau du site (numéro de téléphone, clé API, ID de catalogue) et il doit être accessible via l’administration, pas via wp-config.php.
• Vous personnalisez le site d’un client et voulez que le responsable puisse modifier les données lui-même sans contacter le développeur.

Si le champ est uniquement pour vous et change une fois par an, il est plus simple de coder la valeur en dur. L’API Settings brille lorsque les réglages sont utilisés par quelqu’un d’autre que le développeur.

Commencez simplement: ajoutez un champ texte en suivant l’exemple ci-dessus. Une fois que vous maîtrisez le flux de base, enregistrement, callback, sauvegarde, affichage, passez aux listes déroulantes, aux groupes de champs et aux pages de réglages personnalisées. Et avec quel type de champ travaillez-vous le plus souvent? Dites-le-nous dans les commentaires.