wp_send_json_error()

Définition : wp_send_json_error() renvoie une réponse JSON WordPress signalant l’échec d’une opération. La propriété success prend la valeur false, et des informations complémentaires ou un code HTTP peuvent préciser le problème.

Terminologie

Terme officiel : wp_send_json_error()

Autres appellations : Réponse AJAX d’erreur

À quoi cela sert

Elle permet aux interfaces AJAX de traiter de manière cohérente les échecs : permission insuffisante, saisie invalide ou ressource non trouvée.

Comment cela fonctionne

La fonction construit et envoie une structure JSON contenant success=false et éventuellement data. Elle termine le traitement ; le code HTTP reste à choisir explicitement lorsque l’échec doit également être signalé au niveau du protocole.

Dans quel contexte l’utiliser

À utiliser dans un handler AJAX lorsqu’une opération a échoué ou ne peut être exécutée, avec un message compréhensible.

Exemple concret

Une interface tente de déclencher un contrôle réservé aux administrateurs ; le serveur doit refuser et fournir un statut exploitable.

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_refus', function () {
    check_ajax_referer( 'atoolpha_demo_refus', 'nonce' );
    if ( ! current_user_can( 'manage_options' ) ) {
        wp_send_json_error(
            array( 'message' => 'Droit insuffisant.' ), 403
        );
    }
    wp_send_json_success( array( 'message' => 'Autorisé.' ) );
} );

Explication pas à pas de l’exemple

1. Le handler contrôle le nonce. 2. La permission manage_options est évaluée. 3. En cas de refus, wp_send_json_error() génère success=false et un HTTP 403. 4. Sinon, la réponse est positive.

Résultat attendu

Le navigateur peut distinguer un succès métier d’un refus d’accès et afficher un message adapté à l’utilisateur.

Mise en pratique guidée

Comparer deux réponses d’échec : wp_send_json_error([…]) sans code HTTP explicite, puis avec 403. Examiner dans le navigateur la propriété success et le statut réseau. Le premier peut être transporté en HTTP 200 malgré l’échec métier. Cette distinction aide les interfaces à traiter correctement les contrôles d’accès et la gestion des erreurs.

Précautions et limites

Sans argument de statut HTTP, une réponse avec success=false peut malgré tout recevoir HTTP 200. Éviter d’exposer des détails techniques privés dans le champ message.