check_ajax_referer()

Définition : check_ajax_referer() vérifie le nonce envoyé avec une requête AJAX WordPress. Malgré son nom, elle contrôle un jeton de sécurité et ne constitue pas une vérification fiable de l’en-tête Referer.

Terminologie

Terme officiel : check_ajax_referer()

Autres appellations : Contrôle AJAX CSRF

À quoi cela sert

Elle aide à refuser les appels asynchrones déclenchés sans jeton approprié, notamment ceux qui modifient des réglages ou des métadonnées.

Comment cela fonctionne

La fonction reçoit l’action attendue, la clé du paramètre et éventuellement un indicateur de gestion automatique de l’échec. Elle s’utilise dans le callback PHP d’un endpoint AJAX.

Dans quel contexte l’utiliser

À placer au début d’un handler AJAX, avec un contrôle de capacité indépendant et une validation des entrées.

Exemple concret

Une interface ATOOLPHA veut enregistrer un état documentaire sans recharger la page.

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
add_action( 'wp_ajax_atoolpha_demo_statut', function () {
    check_ajax_referer( 'atoolpha_demo_ajax', 'nonce' );
    if ( ! current_user_can( 'manage_options' ) ) {
        wp_send_json_error( array( 'message' => 'Interdit.' ), 403 );
    }
    wp_send_json_success( array( 'message' => 'Contrôles réussis.' ) );
} );
// Le JS doit envoyer action=atoolpha_demo_statut et nonce=...

Explication pas à pas de l’exemple

1. WordPress oriente la requête grâce au paramètre action. 2. Le nonce transmis est vérifié. 3. La capacité est contrôlée. 4. Une réponse JSON est émise seulement après ces contrôles.

Résultat attendu

Une requête valide reçoit une réponse de succès pédagogique ; cet exemple ne modifie aucune métadonnée.

Mise en pratique guidée

Depuis un bouton de démonstration en administration, transmettre action et nonce à admin-ajax.php. Observer la réponse lorsque le nonce est valide, puis absent. Tester enfin un compte sans la capacité requise. Le scénario distingue une erreur de jeton d’un refus de permission, et aide à concevoir des messages fiables côté navigateur.

Précautions et limites

Le contrôle du nonce ne dispense pas des contrôles de droit et d’entrée. La fonction peut interrompre automatiquement une requête invalide avec une réponse non JSON uniforme.