Chapitre 7.5 — Settings API & pages d’administration

⏱️ TL;DR — Pour offrir une page de réglages à votre plugin, deux briques : add_menu_page/add_submenu_page/add_options_page (sur admin_menu) créent l’entrée de menu et la page ; la Settings API (register_setting, add_settings_section, add_settings_field, sur admin_init) gère l’affichage des champs, la validation et l’enregistrement de façon standardisée et sécurisée. La Settings API prend en charge le nonce, l’option et la sanitize pour vous — c’est la manière correcte (vs bricoler un formulaire à la main).

🎯 Objectifs

• Ajouter une page (ou sous-page) d’administration.
• Utiliser la Settings API pour des réglages robustes.
• Comprendre register_setting (option + sanitize) et l’affichage des champs.
• Vérifier la capability d’accès à la page.

1. Ajouter une page d’admin

Sur le hook admin_menu :

add_action( 'admin_menu', 'wpr_books_menu' );
function wpr_books_menu() {
    add_options_page(                       // sous "Réglages"
        __( 'Réglages WPR Books', 'wpr-books' ), // <title>
        __( 'WPR Books', 'wpr-books' ),          // libellé du menu
        'manage_options',                        // CAPABILITY requise
        'wpr-books',                             // slug de la page
        'wpr_books_settings_page'                // callback de rendu
    );
}

• add_options_page place la page sous Réglages ; add_menu_page crée un menu de premier niveau ; add_submenu_page un sous-menu arbitraire.
• 3ᵉ argument = la capability : qui peut voir/accéder à la page (manage_options = admin). Toujours la vérifier.

⚠️ Piège n°1 — page d’admin sans contrôle de capability. La capability passée à add_*_page filtre l’affichage du menu, mais revérifiez dans le callback de rendu (if ( ! current_user_can('manage_options') ) { return; }) : une page d’admin est accessible par URL, la vérif du menu ne suffit pas toujours.

2. La Settings API : champs, sections, option

Sur admin_init, on déclare : l’option (avec sa sanitize), les sections et les champs.

add_action( 'admin_init', 'wpr_books_settings_init' );
function wpr_books_settings_init() {
    // 1) Enregistrer l'option + sa fonction de nettoyage
    register_setting( 'wpr_books_group', 'wpr_books_options', array(
        'type'              => 'array',
        'sanitize_callback' => 'wpr_books_sanitize_options',
        'default'           => array( 'par_page' => 12, 'devise' => '€' ),
    ) );
 
    // 2) Une section
    add_settings_section(
        'wpr_books_main',
        __( 'Affichage', 'wpr-books' ),
        '__return_false',
        'wpr-books'
    );
 
    // 3) Un champ
    add_settings_field(
        'par_page',
        __( 'Livres par page', 'wpr-books' ),
        'wpr_books_field_par_page',
        'wpr-books',
        'wpr_books_main'
    );
}
 
// Rendu du champ (lit l'option courante)
function wpr_books_field_par_page() {
    $opts  = get_option( 'wpr_books_options' );
    $value = isset( $opts['par_page'] ) ? (int) $opts['par_page'] : 12;
    printf(
        '<input type="number" name="wpr_books_options[par_page]" value="%d" min="1" max="100" />',
        $value
    );
}
 
// Sanitize : nettoyer CHAQUE champ
function wpr_books_sanitize_options( $input ) {
    return array(
        'par_page' => isset( $input['par_page'] ) ? max( 1, absint( $input['par_page'] ) ) : 12,
        'devise'   => isset( $input['devise'] ) ? sanitize_text_field( $input['devise'] ) : '€',
    );
}

3. Rendre la page (le formulaire)

Le callback de la page utilise les fonctions de la Settings API, qui génèrent champs, sections et le nonce :

function wpr_books_settings_page() {
    if ( ! current_user_can( 'manage_options' ) ) { return; } // re-vérif capability
    ?>
    <div class="wrap">
        <h1><?php echo esc_html( get_admin_page_title() ); ?></h1>
        <form action="options.php" method="post">
            <?php
            settings_fields( 'wpr_books_group' );      // nonce + champs cachés
            do_settings_sections( 'wpr-books' );       // sections + champs déclarés
            submit_button();                           // bouton "Enregistrer"
            ?>
        </form>
    </div>
    <?php
}

Le formulaire poste vers options.php (le gestionnaire natif) : WordPress vérifie le nonce, appelle votre sanitize_callback, puis enregistre l’option. Vous n’écrivez aucune logique de sauvegarde manuelle.

💡 Pour un dev React — La Settings API est un framework de formulaire déclaratif : vous déclarez des champs (nom, rendu, section) et une fonction de validation (sanitize_callback), et le « moteur » gère soumission, CSRF (nonce) et persistance. Comme un <Form> avec un resolver de validation, mais côté serveur. Vous gagnez la sécurité et la cohérence UI d’admin gratuitement — ne réinventez pas un formulaire à la main.

⚠️ Piège n°2 — le formulaire fait maison. Bricoler un <form> qui poste vers votre page et enregistre l’option « à la main » vous oblige à gérer vous-même nonce + sanitize + capability (et on en oublie toujours un). La Settings API le fait correctement. Utilisez-la sauf besoin très spécifique.

4. Stocker une seule option (bonne pratique)

Regroupez vos réglages dans une seule option (un tableau wpr_books_options) plutôt qu’une option par champ : moins d’entrées dans wp_options, une seule sanitize, chargement simple. Rappel (ch. 5.7) : attention à l’autoload si l’option grossit.

5. Au-delà de la Settings API

Pour des interfaces d’admin riches (tableaux, onglets, drag-and-drop), on construit une page custom en React (@wordpress/components, @wordpress/element), servie via add_menu_page et alimentée par la REST API (endpoints custom, Partie 9). C’est le pont naturel pour un dev React qui veut des admin modernes — mais la Settings API reste le choix par défaut pour des réglages simples.

✏️ Exercices

1. Quels hooks utilisez-vous pour (a) créer la page de menu, (b) déclarer les réglages ?
2. Pourquoi utiliser la Settings API plutôt qu’un formulaire fait main ?
3. Où et pourquoi re-vérifier la capability, en plus de celle passée à add_options_page ?

🧠 Quiz de révision

Chapitre suivant : Shortcodes & widgets.