Settings API

Définition : La Settings API de WordPress regroupe les fonctions utilisées pour déclarer, afficher, valider et enregistrer des paramètres administrables. Elle permet d’intégrer les réglages d’un plugin au fonctionnement natif de l’administration.

Terminologie

Terme officiel : Settings API

Autres appellations : API des réglages

À quoi cela sert

Elle évite d’écrire une procédure complète de réception et de stockage de formulaire. Elle standardise la déclaration des options, la création de sections et champs, la protection du formulaire et le traitement via options.php.

Comment cela fonctionne

register_setting() définit une option ; add_settings_section() et add_settings_field() construisent sa présentation. Dans le formulaire, settings_fields() insère les champs nécessaires et do_settings_sections() imprime les champs enregistrés pour la page.

Dans quel contexte l’utiliser

Pertinente dès qu’un plugin possède une page de configuration administrateur persistante, par exemple un titre d’interface, un nombre d’éléments ou une préférence d’affichage.

Exemple concret

Un plugin crée une préférence de titre éditable dans une page située sous Réglages, sans gérer lui-même le POST.

Exemple de code commenté

<?php
add_action( 'admin_init', function () {
    register_setting( 'atoolpha_demo', 'atoolpha_demo_titre', array(
        'type'              => 'string',
        'sanitize_callback' => 'sanitize_text_field',
        'default'           => 'Bienvenue',
    ) );
} );
// Dans le formulaire de réglages du plugin :
// settings_fields( 'atoolpha_demo' );
// do_settings_sections( 'atoolpha-demo-page' );

Explication pas à pas de l’exemple

Le groupe de réglages atoolpha_demo est enregistré à admin_init. Le callback de nettoyage encadre le texte enregistré et default définit une valeur de repli. Les fonctions de rendu du formulaire sont à associer à une vraie page autorisée.

Résultat attendu

Lorsqu’un formulaire complet est construit, WordPress peut recevoir et enregistrer le réglage via ses mécanismes standard.

Précautions et limites

La Settings API ne dispense pas de vérifier les capacités utilisateur sur l’écran d’administration ni d’échapper les valeurs lors de leur affichage. Les lignes de rendu commentées ne forment pas un formulaire complet.