« Pourquoi faut-il appeler quatre fonctions différentes pour afficher un simple champ texte dans un écran de réglages ? » — c’est la question que se pose presque chaque développeur découvrant la Settings API pour la première fois. La réponse ne tient pas à un défaut de conception récent, mais à une contrainte de compatibilité posée bien avant l’arrivée de cette API elle-même.
La Settings API a été introduite pour remplacer une pratique bien plus rudimentaire : des extensions qui affichaient leurs propres formulaires HTML, traitaient elles-mêmes la soumission via $_POST, et géraient à la main la validation, l’affichage des erreurs et l’enregistrement en base. Cette liberté totale produisait des écrans incohérents d’une extension à l’autre, sans aucune garantie de sécurité homogène. La Settings API a imposé un cadre commun, mais en s’appuyant sur un formulaire déjà existant dans le cœur : celui des pages d’options natives.
Un formulaire hérité, pas conçu pour l’API
Le formulaire utilisé par les écrans de réglages (options.php en traitement) existait avant la Settings API elle-même, pour gérer les réglages natifs de WordPress — titre du site, adresse d’email, format de date. La Settings API a été construite pour permettre à des extensions tierces de s’y greffer, plutôt que de créer un nouveau mécanisme de traitement de formulaire. Ce choix a évité une duplication de logique, mais il a aussi hérité de contraintes propres à ce formulaire ancien : chaque champ doit être enregistré individuellement, chaque section doit être associée à une page existante, et chaque groupe de réglages doit être déclaré séparément.
La mécanique complète, illustrée
add_action( 'admin_init', function () {
register_setting( 'mon_extension_options', 'mon_extension_delai' );
add_settings_section(
'mon_extension_section_generale',
'Réglages généraux',
'__return_false',
'mon-extension-reglages'
);
add_settings_field(
'mon_extension_delai',
'Délai de purge (jours)',
function () {
$valeur = get_option( 'mon_extension_delai', 30 );
printf(
'<input type="number" name="mon_extension_delai" value="%d">',
(int) $valeur
);
},
'mon-extension-reglages',
'mon_extension_section_generale'
);
} );Quatre fonctions pour un seul champ : register_setting() déclare le réglage et le rattache à un groupe, add_settings_section() crée un regroupement visuel, add_settings_field() associe un rappel d’affichage à ce regroupement, et le rappel lui-même construit le HTML du champ. Cette verbosité n’est pas un oubli d’ergonomie : elle reflète la structure du formulaire natif, pensée à l’origine pour des réglages simples du cœur, pas pour des interfaces riches d’extensions modernes.
Pourquoi ce choix n’a jamais été remplacé
Remplacer la Settings API par un mécanisme plus concis casserait la compatibilité avec des milliers d’extensions publiées qui s’appuient dessus depuis des années. Le cœur privilégie systématiquement la stabilité de ce qui existe déjà à une simplification qui romprait cette compatibilité. C’est un compromis assumé : la verbosité de l’API est le prix payé pour que des extensions écrites il y a plus de dix ans continuent de fonctionner sans modification sur les versions récentes du logiciel.
Ce que cela signifie pour un développeur aujourd’hui
- Comprendre que cette verbosité vient d’une contrainte historique aide à ne pas chercher un raccourci qui n’existe pas dans l’API elle-même.
- Des bibliothèques d’abstraction existent pour réduire ce code répétitif, au prix d’une dépendance supplémentaire à maintenir.
- Pour un réglage unique et simple, écrire directement les quatre appels reste souvent plus lisible qu’une abstraction pour un seul cas d’usage.
Une API verbeuse n’est pas toujours une API mal pensée : elle porte parfois, sans le dire, quinze ans de compatibilité ascendante.
En résumé
La verbosité de la Settings API n’est pas un défaut de conception isolé : elle découle d’un choix délibéré de s’appuyer sur le formulaire d’options déjà existant dans le cœur plutôt que d’en créer un nouveau. Comprendre cet héritage change la façon dont on aborde l’API — non plus comme une contrainte arbitraire, mais comme le prix assumé d’une compatibilité qui traverse les versions sans jamais casser les extensions existantes.
