Beaucoup d’extensions WordPress affichent encore une page de réglages construite à la main : un formulaire HTML, un traitement du $_POST directement dans le fichier d’administration, et une sauvegarde via update_option() sans vérification de nonce ni de capability. Cela fonctionne, jusqu’au jour où un audit de sécurité ou un test avec WordPress multisite révèle les failles de cette approche artisanale.

La Settings API, présente depuis WordPress 2.7, résout ce problème depuis longtemps mais reste sous-utilisée. Elle prend en charge la génération du nonce, la vérification de la capability, la sanitisation des valeurs et l’affichage des erreurs de validation, pour un coût d’apprentissage finalement modeste.

Les trois briques de la Settings API

Trois fonctions suffisent à construire n’importe quelle page de réglages :

• register_setting() déclare une option, sa sanitisation et son groupe
• add_settings_section() déclare un regroupement visuel de champs
• add_settings_field() déclare un champ individuel, avec son callback d’affichage

add_action( 'admin_init', function () {
    register_setting(
        'acme_options_group',      // groupe d'options
        'acme_api_key',            // nom de l'option en base
        [
            'type'              => 'string',
            'sanitize_callback' => 'sanitize_text_field',
            'default'           => '',
        ]
    );

    add_settings_section(
        'acme_section_api',
        __( 'Connexion à l\'API', 'acme' ),
        function () {
            echo '
' . esc_html__( 'Renseignez votre clé d\'API personnelle.', 'acme' ) . '
';
        },
        'acme-page'
    );

    add_settings_field(
        'acme_api_key_field',
        __( 'Clé API', 'acme' ),
        function () {
            $value = get_option( 'acme_api_key', '' );
            printf(
                '',
                esc_attr( $value )
            );
        },
        'acme-page',
        'acme_section_api'
    );
} );

La page d’administration qui affiche le tout

La page elle-même reste très courte : les fonctions settings_fields() et do_settings_sections() génèrent respectivement les champs cachés (nonce, action, option_page) et l’ensemble des sections déclarées.

add_action( 'admin_menu', function () {
    add_options_page(
        __( 'Réglages Acme', 'acme' ),
        'Acme',
        'manage_options',
        'acme-page',
        function () {
            echo '
' . esc_html__( 'Réglages Acme', 'acme' ) . '
';
            settings_fields( 'acme_options_group' );
            do_settings_sections( 'acme-page' );
            submit_button();
            echo '
';
        }
    );
} );

C’est options.php, un fichier interne à WordPress, qui traite la soumission : vérification du nonce généré par settings_fields(), contrôle de la capability associée au groupe d’options, sanitisation via le sanitize_callback déclaré, puis redirection vers la page d’origine avec un message de confirmation. Aucune de ces étapes n’est à écrire soi-même.

Sanitiser correctement selon le type de donnée

Le sanitize_callback mérite d’être choisi avec soin selon la nature de la donnée :

Type de champ	Fonction de sanitisation adaptée
Texte simple	sanitize_text_field
Adresse e-mail	sanitize_email
URL	esc_url_raw
Nombre entier	absint
Contenu HTML limité	wp_kses_post
Case à cocher	fonction personnalisée retournant un booléen strict

Pour une case à cocher, la sanitisation par défaut ne suffit pas toujours : un callback maison garantit une valeur propre en base plutôt qu’une chaîne "on" ou une valeur vide selon les navigateurs.

register_setting( 'acme_options_group', 'acme_notifications', [
    'type'              => 'boolean',
    'sanitize_callback' => function ( $value ) {
        return (bool) $value;
    },
    'default' => false,
] );

Valider et afficher une erreur

Au-delà de la sanitisation, la Settings API permet une vraie validation avec message d’erreur via add_settings_error(), appelée depuis le sanitize_callback :

register_setting( 'acme_options_group', 'acme_api_key', [
    'sanitize_callback' => function ( $value ) {
        $value = sanitize_text_field( $value );
        if ( strlen( $value ) < 20 ) {
            add_settings_error(
                'acme_api_key',
                'acme_api_key_invalide',
                __( 'La clé API semble trop courte, vérifiez votre copier-coller.', 'acme' )
            );
            return get_option( 'acme_api_key' ); // on conserve l'ancienne valeur
        }
        return $value;
    },
] ) );

Cette approche évite d'enregistrer une valeur manifestement invalide tout en informant l'utilisateur de façon native, avec le même style visuel que les messages d'erreur du cœur de WordPress.

Sur les projets où l'on reprend une extension existante, remplacer un formulaire fait maison par la Settings API est souvent le chantier de sécurité le plus rentable : quelques heures de travail suppriment une classe entière de failles CSRF potentielles.

Compatibilité multisite et REST

Un avantage moins connu : une option déclarée avec register_setting() et l'argument show_in_rest devient automatiquement disponible via l'endpoint REST /wp/v2/settings, sous réserve que l'utilisateur ait la capability manage_options. Cela évite d'écrire un contrôleur REST personnalisé pour de simples options globales.

register_setting( 'acme_options_group', 'acme_api_key', [
    'type'         => 'string',
    'show_in_rest' => true,
    'default'      => '',
] );

En résumé

La Settings API demande un peu plus de code qu'un formulaire artisanal pour un champ unique, mais elle devient rentable dès la deuxième option et incontournable au-delà de cinq. Nonce, capability, sanitisation, validation et exposition REST sont pris en charge par le cœur de WordPress : autant de code que vous n'avez pas à maintenir ni à sécuriser vous-même.