⌨️ Comment ajouter votre propre section à la page des réglages WordPress

Les pages de réglages standard de WordPress, «Général», «Lecture» et «Discussions», couvrent les besoins de base d’un site. Mais dès que vous écrivez un plugin ou personnalisez un thème pour un client, le jeu de champs intégré ne suffit plus. Vous avez besoin d’un bloc avec vos propres options: une clé API, un texte de pied de page, un bouton de basculement de mode.

Créer une page d’administration séparée pour seulement deux champs est disproportionné. Il est bien plus propre d’ajouter votre propre section à une page de réglages existante, là où se trouvent les options WordPress par défaut. L’API Settings fournit une fonction unique pour cela: add_settings_section.

Parcourons sa syntaxe, ses paramètres et construisons un exemple fonctionnel avec une section et un champ, depuis le hook admin_init jusqu’à l’affichage dans le panneau d’administration. Pas d’abstractions inutiles: uniquement ce que vous pouvez copier et exécuter vous-même.

💡 Aperçu rapide:

• Définissez la page cible (general, reading, writing, discussion, media ou une page personnalisée), vous aurez besoin de son slug dans le quatrième paramètre
• Enregistrez la section via add_settings_section() sur le hook admin_init: fournissez un ID, un titre et une fonction de callback pour le texte descriptif
• Attachez les champs à la section via add_settings_field(), et enregistrez l’option elle-même via register_setting()
• Appelez do_settings_sections() dans la fonction de callback de la page pour les pages personnalisées, la section s’affichera automatiquement

Ce qu’est l’API Settings et pourquoi vous en avez besoin

L’API Settings est apparue dans WordPress 2.7 et est restée depuis la méthode standard pour ajouter des réglages au panneau d’administration. L’idée est simple: au lieu d’écrire manuellement un <form> et de traiter $_POST, vous décrivez des sections et des champs via des fonctions, et WordPress lui-même génère le balisage, gère la sauvegarde et vérifie le nonce.

Les trois piliers de l’API Settings:

• register_setting(), enregistre une option dans wp_options;
• add_settings_section(), crée un bloc (section) avec un titre;
• add_settings_field(), ajoute un champ spécifique à une section.

C’est add_settings_section qui est responsable du «conteneur», le bloc visuel qui regroupe plusieurs champs sous un titre commun sur la page de réglages. Sans lui, il n’y a tout simplement aucun endroit où placer les champs.

Syntaxe de add_settings_section

La signature de la fonction est concise, quatre paramètres obligatoires et un tableau optionnel:

1
add_settings_section(
2
    string $id,
3
    string $title,
4
    callable $callback,
5
    string $page,
6
    array  $args = array()
7
);

La fonction ne retourne rien. Elle enregistre la section dans le tableau global $wp_settings_sections, à partir duquel WordPress la récupère lorsque do_settings_sections() est appelée sur la page cible. Si vous appelez add_settings_section sans un do_settings_sections ultérieur sur une page personnalisée, la section ne s’affiche pas, silencieusement.

Une nuance importante: add_settings_section décrit uniquement le bloc. Les champs eux-mêmes sont ajoutés par des appels séparés à add_settings_field, en spécifiant l’ID de la section dans le cinquième paramètre. Sans champs, la section reste un conteneur vide, ce qui est parfois utile pour une explication textuelle, mais en pratique, au moins un champ est presque toujours placé à côté.

Paramètres de la fonction, quoi passer

$id (chaîne, obligatoire), le slug unique de la section. Utilisez des lettres minuscules, des chiffres et des underscores: my_plugin_main_section. Vous spécifierez ce même ID dans add_settings_field pour «attacher» le champ à la section, et il apparaît également dans l’attribut HTML id de la balise conteneur.

$title (chaîne, obligatoire), le titre de la section que l’administrateur voit. Il est affiché en tant que <h2> à l’intérieur de la page de réglages. Rédigez-le en langage clair pour l’administrateur: «Настройки интеграции с CRM», pas my_plugin_crm_settings.

$callback (callable, obligatoire), le nom de la fonction qui affiche le texte descriptif entre le titre de la section et les champs. Signature: function my_callback($args), où $args est un tableau avec les clés id, title et callback. Si aucune explication n’est nécessaire, passez '__return_false'.

$page (chaîne, obligatoire), le slug de la page de réglages où la section est ajoutée. Pages WordPress intégrées: general, reading, writing, discussion, media. Pour une page personnalisée, le slug passé à add_options_page(). ⚠ Les pages misc et privacy ont été supprimées du cœur (obsolètes), WordPress redirigera automatiquement misc → general, privacy → reading, mais il est préférable de ne pas se fier à ce comportement.

$args (tableau, optionnel, depuis WordPress 6.1.0), un tableau pour personnaliser le conteneur HTML de la section:

L’argument $args ne fonctionne que lorsque do_settings_sections() est appelée. Si do_settings_fields() est utilisée par erreur, le tableau est ignoré et before_section/after_section restent silencieusement sans effet.

Exemple pratique: une section avec un champ sur la page «Général»

Assemblons un extrait prêt à l’emploi pour functions.php ou votre propre plugin. Le code ajoute une section «Réglages du site vitrine» à la page options-general.php avec un champ texte, par exemple pour un numéro de téléphone dans le pied de page.

1
/**
2
 * Adds a custom section and field to the «General» page.
3
 */
4
function sdstudio_add_visiting_card_section() {
5
    // 1. Section
6
    add_settings_section(
7
        'visiting_card_section',               // Section ID
8
        'Visiting Card Settings',             // Title
9
        'sdstudio_visiting_card_section_cb',   // Callback explanation
10
        'general',                             // «General» page
11
        array(
12
            'before_section' => '<div class="visiting-card-wrapper">',
13
            'after_section'  => '</div>',
14
        )
15
    );
16
 
17
    // 2. Field
18
    add_settings_field(
19
        'footer_phone',                        // Field ID
20
        'Footer Phone Number',                    // Label
21
        'sdstudio_footer_phone_field_cb',      // Callback — renders <input>
22
        'general',                             // Same page
23
        'visiting_card_section'                // Which section to attach to
24
    );
25
 
26
    // 3. Registering the option
27
    register_setting( 'general', 'footer_phone' );
28
}
29
add_action( 'admin_init', 'sdstudio_add_visiting_card_section' );
30
 
31
/**
32
 * Explanatory text above the section fields.
33
 */
34
function sdstudio_visiting_card_section_cb( $args ) {
35
    ?>
36
    <p id="<?php echo esc_attr( $args['id'] ); ?>">
37
        Contact details displayed in the site footer.
38
    </p>
39
    <?php
40
}
41
 
42
/**
43
 * Renders a text input field.
44
 */
45
function sdstudio_footer_phone_field_cb() {
46
    $value = get_option( 'footer_phone', '' );
47
    printf(
48
        '<input type="text" id="footer_phone" name="footer_phone" value="%s" class="regular-text" />',
49
        esc_attr( $value )
50
    );
51
}

Après avoir ajouté le code, allez dans le panneau d’administration: Réglages → Général, et en dessous des champs standard, vous verrez la section «Réglages du site vitrine» avec le champ «Numéro de téléphone du pied de page». Sauvegardez la page, et la valeur sera écrite dans wp_options.

Le code se place dans le functions.php du thème actif ou, plus correctement, dans un plugin séparé. Un plugin survit à un changement de thème, contrairement à functions.php. Si la section n’est nécessaire que lorsqu’un thème spécifique est actif, functions.php est acceptable; dans tous les autres cas, uniquement un plugin.

L’argument $args: ce qui a changé dans WordPress 6.1

Avant la version 6.1, add_settings_section avait exactement quatre paramètres, et vous deviez «retoucher» le conteneur de la section via CSS par ID, ou intervenir dans le tampon de sortie. À partir de la 6.1, un cinquième paramètre $args a été ajouté, et désormais l’encadrement HTML se définit directement lors de l’enregistrement de la section:

• before_section, un conteneur div ou une bannière explicative AVANT le contenu;
• after_section, une balise fermante ou une indication APRÈS le contenu;
• section_class, une classe personnalisée si la classe standard form-table ne suffit pas.

Un exemple avec une bannière explicative et une classe personnalisée:

1
add_settings_section(
2
    'api_keys_section',
3
    'API Keys',
4
    'sdstudio_api_keys_section_cb',
5
    'general',
6
    array(
7
        'before_section' => '<div class="notice notice-info inline"><p>Store keys in wp-config.php, override here only.</p></div>',
8
        'after_section'  => '',
9
        'section_class'  => 'api-keys-section',
10
    )
11
);

Ce qu’il est important de retenir: after_section n’est pas affiché si la section est vide, c’est-à-dire lorsqu’il n’y a pas de champs enregistrés à l’intérieur. Si vous comptez sur un </div> fermant, assurez-vous qu’au moins un champ est ajouté via add_settings_field. Et surtout: utilisez do_settings_sections(), pas do_settings_fields(), car cette dernière ignorera complètement $args.

Avant d’utiliser before_section / after_section, vérifiez la version de WordPress, sur les sites antérieurs à la 6.1, passer le cinquième paramètre provoquera une erreur fatale. Une approche sûre: enveloppez l’appel dans une vérification global $wp_version ou utilisez function_exists pour vérifier la présence des hooks.

⁉️🤔 Questions fréquentes

Puis-je sauter add_settings_section et ajouter des champs directement?

Formellement, non. Les champs sont enregistrés via add_settings_field(), et le cinquième paramètre de cette fonction nécessite un ID de section. Si la section n’existe pas, le champ ne s’affichera pas. Pour un champ unique, vous pouvez créer une section avec un titre vide et une fonction de callback '__return_false', la section sera invisible et le champ fonctionnera.

Quelle est la différence entre add_settings_section et add_settings_field?

Une section est un conteneur avec un titre et un texte descriptif. Un champ est un élément de saisie spécifique (input, select, checkbox) à l’intérieur d’une section. Une section peut contenir un nombre quelconque de champs, tous regroupés sous un même titre et sauvegardés en un seul clic sur le bouton «Enregistrer».

Que se passe-t-il si je spécifie un slug de page inexistant dans $page?

La section sera enregistrée dans $wp_settings_sections mais ne s’affichera jamais, car WordPress ne sait pas sur quelle page l’afficher. Il n’y aura pas d’erreur, la section restera simplement «en suspens». Vérifiez le slug: pour les pages intégrées, c’est general / reading / writing / discussion / media; pour les pages personnalisées, le slug exact de add_menu_page ou add_options_page.

Puis-je ajouter une section à la page d’un autre plugin?

Oui, si vous connaissez son slug de page. Passez-le dans $page, et la section apparaîtra sur la page de réglages de l’autre plugin. Mais c’est une solution fragile: l’auteur du plugin peut changer le slug lors d’une mise à jour, et votre section «tombera». Utilisez-la uniquement pour vos propres projets ou lorsqu’il n’y a pas d’alternative.

Que fait le hook admin_init et pourquoi add_settings_section y est-il appelé?

admin_init se déclenche à chaque requête vers le panneau d’administration AVANT que la page ne soit générée. C’est le bon moment pour enregistrer les réglages: les sections et les champs doivent être déclarés avant que WordPress ne commence à assembler le formulaire. Si vous appelez add_settings_section plus tard, par exemple à l’intérieur de la fonction de callback de la page, la section n’arrivera pas dans $wp_settings_sections et ne sera pas affichée.

Votre propre section ou une page séparée, que choisir

Ajouter une section à general est plus simple: moins de code, et l’utilisateur voit les réglages au même endroit où il modifie le titre du site. Mais lorsqu’il y a plus de trois ou quatre options, la section alourdit la page standard et perturbe l’administrateur.

La règle est simple: une ou deux options, logiquement liées à la page générale (numéro de téléphone du pied de page, clé API pour les commentaires), utilisez une section sur general. Trois options ou plus, une fonctionnalité autonome (un slider, une intégration CRM, une grille tarifaire), utilisez une page séparée via add_options_page(). Dans les deux cas, add_settings_section est la brique de base par laquelle commence l’assemblage.

Avant de copier le code, assurez-vous que WordPress est mis à jour vers la dernière version. Le tableau $args, section_class et les conteneurs before_section/after_section nécessitent au moins la version 6.1, tandis que la fonction elle-même est présente dans le cœur depuis la version 2.7. Deux décennies de rétrocompatibilité ne sont pas une raison pour rester sur un moteur obsolète.