Faut-il vraiment construire un contrôleur REST personnalisé pour exposer les réglages d’une extension à une interface d’administration découplée en JavaScript ? Dans la grande majorité des cas, la réponse est non : l’endpoint natif /wp/v2/settings, alimenté par register_setting(), couvre déjà ce besoin sans code supplémentaire côté serveur.
Ce réflexe de construire un endpoint sur mesure vient souvent d’une méconnaissance du paramètre show_in_rest disponible depuis plusieurs versions dans register_setting(), alors qu’il suffit à publier un réglage existant sans dupliquer la logique de lecture et d’écriture déjà gérée par le cœur.
Déclarer un réglage exposé à l’API REST
function wpm_enregistrer_reglages_extension() {
register_setting(
'wpm_options_groupe',
'wpm_delai_relance_jours',
array(
'type' => 'integer',
'description' => 'Délai en jours avant relance automatique',
'default' => 7,
'show_in_rest' => true,
)
);
}
add_action( 'init', 'wpm_enregistrer_reglages_extension' );Une fois ce réglage déclaré, il apparaît automatiquement dans les réponses de GET /wp/v2/settings, et devient modifiable via une requête POST sur ce même endpoint, sans qu’aucune route supplémentaire n’ait besoin d’être enregistrée.
Contrôler le type avec un schema précis
Comme pour register_meta(), il est possible de fournir un tableau plutôt qu’un simple booléen pour show_in_rest, ce qui permet de définir un schema de validation plus strict que le simple type de base :
'show_in_rest' => array(
'schema' => array(
'type' => 'integer',
'minimum' => 1,
'maximum' => 90,
),
),Ce schema empêche qu’une interface découplée, à cause d’un bug côté JavaScript, n’envoie une valeur négative ou disproportionnée qui viendrait perturber la logique métier construite autour de ce réglage.
Requête depuis une interface JavaScript
const reponse = await fetch( '/wp-json/wp/v2/settings', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-WP-Nonce': wpApiSettings.nonce,
},
body: JSON.stringify( {
wpm_delai_relance_jours: 14,
} ),
} );La capacité qui protège l’écriture
Par défaut, l’écriture sur l’endpoint /wp/v2/settings exige la capacité manage_options, ce qui correspond au rôle administrateur sur une installation standard. Ce comportement ne se paramètre pas réglage par réglage comme avec register_meta() : tous les réglages exposés via register_setting() partagent la même exigence de capacité pour l’écriture.
Ce que cette approche ne couvre pas
- Une logique métier déclenchée à l’enregistrement, qui nécessite d’accrocher un hook séparé comme
update_option_{nom} - Un contrôle d’accès différencié selon le réglage plutôt qu’un seuil unique
manage_options - Une structure de données complexe non représentable par un schema JSON simple
Dans ces situations plus spécifiques, un contrôleur REST personnalisé, construit avec WP_REST_Controller, redevient pertinent. Mais pour la majorité des réglages simples d’une extension – un délai, une clé d’API, une option d’activation/désactivation – register_setting() avec show_in_rest suffit largement.
| Besoin | register_setting suffit |
|---|---|
| Réglage simple, type scalaire | Oui |
| Contrôle d’accès par réglage | Non, capacité unique |
| Logique métier au changement | Avec un hook complémentaire |
| Structure complexe imbriquée | Possible mais limité |
Avant d’écrire un contrôleur REST personnalisé pour un simple réglage, la question à se poser est si register_setting avec show_in_rest ne couvre pas déjà tout le besoin sans une seule ligne de route supplémentaire.
En résumé
Publier les réglages d’une extension pour une interface découplée ne demande dans la plupart des cas ni endpoint personnalisé ni logique de sérialisation additionnelle : register_setting() avec show_in_rest activé et un schema précis suffit à couvrir le besoin de façon fiable, en s’appuyant sur l’API REST déjà présente dans le cœur de WordPress.
