API des réglages

Coder un formulaire de réglages « à la main » oblige à gérer soi-même la vérification du nonce, la sécurité et l’enregistrement en base : cette API évite ce travail répétitif en fournissant un squelette commun à toutes les extensions.

Les trois briques principales

Trois familles de fonctions structurent une page de réglages. D’abord register_setting(), qui déclare une option et, si besoin, une fonction de nettoyage des données saisies (sanitize_callback). Ensuite add_settings_section(), qui regroupe des champs sous un titre. Enfin add_settings_field(), qui ajoute un champ précis dans une section, avec sa fonction de rendu.

add_action( 'admin_init', function () {
  register_setting( 'mon_groupe', 'mon_option', array(
    'sanitize_callback' => 'sanitize_text_field',
  ) );
  add_settings_section( 'ma_section', 'Réglages généraux', '__return_false', 'ma-page' );
  add_settings_field( 'mon_champ', 'Clé API', 'afficher_champ_cb', 'ma-page', 'ma_section' );
} );

Dans le gabarit de la page, il suffit ensuite d’appeler settings_fields( 'mon_groupe' ) et do_settings_sections( 'ma-page' ) à l’intérieur d’une balise <form> pointant vers options.php.

Pièges fréquents

• Oublier le sanitize_callback laisse passer des données non filtrées jusqu’en base de données.
• La page de réglages elle-même doit être créée séparément avec add_options_page() ou une fonction équivalente ; l’API des réglages ne s’occupe que des champs, pas du menu d’administration.
• Depuis WordPress 5.5, on peut décrire un schéma pour l’API REST via l’argument show_in_rest de register_setting().