register_setting()

Définition : register_setting() déclare un paramètre WordPress auprès de la Settings API, avec son groupe, son nom et ses règles éventuelles. Elle encadre la validation et l’enregistrement de données provenant des formulaires administratifs.

Terminologie

Terme officiel : register_setting()

Autres appellations : Déclaration de réglage

À quoi cela sert

Elle crée le contrat de gestion d’une option : type attendu, valeur par défaut, nettoyage et exposition REST éventuelle. Elle facilite une intégration cohérente avec la page de réglages native.

Comment cela fonctionne

L’enregistrement s’effectue généralement à admin_init pour l’administration. Le groupe doit correspondre à celui utilisé par settings_fields(). Le traitement effectif d’un formulaire peut ensuite mettre à jour la valeur avec les contrôles de WordPress.

Dans quel contexte l’utiliser

À employer avant de construire un champ administrable, en particulier si la valeur vient d’un formulaire et doit respecter un format.

Exemple concret

Une extension souhaite que l’administrateur règle un nombre d’éléments affichés, compris entre 1 et 50.

Exemple de code commenté

<?php
add_action( 'admin_init', function () {
    register_setting( 'atoolpha_demo', 'atoolpha_demo_nombre', array(
        'type'              => 'integer',
        'default'           => 10,
        'sanitize_callback' => function ( $value ) {
            return max( 1, min( 50, absint( $value ) ) );
        },
    ) );
} );

Explication pas à pas de l’exemple

Le paramètre est enregistré dans le groupe atoolpha_demo. Le callback convertit la valeur en entier non négatif, puis la borne à 1–50. Le formulaire associé doit utiliser le même groupe pour l’enregistrement.

Résultat attendu

Une saisie telle que 999 est ramenée à 50 lors du traitement du réglage ; une valeur négative est normalisée selon la logique absint utilisée ici.

Précautions et limites

Une validation correcte dépend du besoin métier : absint() transforme -5 en 5, ce qui peut ne pas convenir à toutes les politiques. Tester séparément la création des écrans et les autorisations.