check_admin_referer()

Définition : check_admin_referer() contrôle le nonce d’une requête d’administration WordPress pour une action donnée. En cas d’échec, elle peut interrompre automatiquement le traitement avec une réponse d’erreur.

Terminologie

Terme officiel : check_admin_referer()

Autres appellations : Contrôle de formulaire administrateur

À quoi cela sert

Elle facilite la protection des formulaires et actions administratives dont le serveur doit refuser la soumission lorsqu’un jeton attendu manque ou n’est pas valide.

Comment cela fonctionne

La fonction recherche le nonce dans le champ prévu et compare sa valeur à l’action transmise. Le nom du champ peut être précisé pour correspondre à wp_nonce_field().

Dans quel contexte l’utiliser

À utiliser dans une routine de traitement d’administration qui reçoit une action déjà authentifiée, avant tout changement de données.

Exemple concret

Un administrateur soumet une action « clôturer fiche » avec le champ nonce défini à l’affichage du formulaire.

Exemple de code commenté

Extrait pédagogique PHP pour extension WordPress : adapter au contexte et tester sur un environnement de développement avant tout usage.

<?php
// Dans un handler administratif, après accès à WordPress.
if ( ! current_user_can( 'edit_posts' ) ) {
    wp_die( 'Accès refusé.', '', array( 'response' => 403 ) );
}
check_admin_referer( 'atoolpha_cloturer_fiche', 'atoolpha_nonce' );
// La modification elle-même vient ensuite, après validation métier.

Explication pas à pas de l’exemple

1. Le rôle fonctionnel est évalué par une capacité. 2. check_admin_referer() vérifie l’action et le champ explicitement nommés. 3. Le traitement ne poursuit que si les contrôles réussissent.

Résultat attendu

Une requête sans jeton valide est interrompue, et aucune mise à jour n’est réalisée par cet extrait.

Mise en pratique guidée

Construire un formulaire avec wp_nonce_field('atoolpha_cloturer_fiche','atoolpha_nonce') et un endpoint administratif de test. Vérifier le chemin nominal et le rejet d’une soumission sans nonce. Tester ensuite avec un profil dépourvu de la capacité attendue : même avec un jeton acceptable, la modification doit rester interdite.

Précautions et limites

Pour une action portant sur un post précis, utiliser une capacité contextualisée comme edit_post avec son ID. Ne pas confondre vérification de nonce et autorisation.