new WP_Error( 'invalid_id', "L'identifiant fourni n'existe pas." ) : voilà à quoi ressemble la majorité des erreurs qu’on lève dans un plugin. Le problème apparaît dès qu’on doit renvoyer cette erreur à un client REST ou Ajax : sans indication de statut, l’appelant ne sait pas s’il doit afficher un message, rediriger l’utilisateur ou réessayer plus tard.
La classe WP_Error propose justement une méthode pensée pour ce cas précis : add_data(). Elle permet d’associer des données arbitraires — dont un code HTTP — à un code d’erreur donné, sans toucher à la structure de la classe ni écrire de sous-classe dédiée.
Ce que WP_Error stocke par défaut
Un objet WP_Error repose sur trois propriétés internes : un tableau de codes, un tableau de messages associés à ces codes, et un tableau de données additionnelles. Quand on écrit new WP_Error( 'code_erreur', 'Message lisible' ), seules les deux premières sont renseignées. La troisième reste vide tant qu’on n’appelle pas explicitement une méthode pour la remplir.
C’est là que beaucoup de développeurs s’arrêtent, en se contentant de vérifier is_wp_error() côté appelant puis en renvoyant un statut 400 fixe, quelle que soit la nature réelle du problème. Un identifiant introuvable et une permission refusée méritent pourtant des codes différents.
Utiliser add_data() pour attacher un statut
La signature est volontairement simple : add_data( $data, $code = '' ). Le second paramètre est facultatif : s’il est omis, WordPress associe la donnée au dernier code d’erreur ajouté à l’objet. Dans la pratique, on l’explicite presque toujours pour éviter toute ambiguïté quand plusieurs erreurs cohabitent.
function trouver_commande( $id ) {
$commande = get_post( $id );
if ( ! $commande || 'commande' !== $commande->post_type ) {
$erreur = new WP_Error(
'commande_introuvable',
'Aucune commande ne correspond à cet identifiant.'
);
$erreur->add_data( array( 'status' => 404 ), 'commande_introuvable' );
return $erreur;
}
return $commande;
}
La clé status n’a rien de magique en elle-même : c’est une convention que l’écosystème WordPress a adoptée, notamment dans l’API REST, pour signifier « voici le code HTTP à renvoyer ». On peut tout à fait y ajouter d’autres clés utiles, comme un identifiant de journalisation interne ou un champ destiné au front.
Relire la donnée associée
Côté appelant, la lecture se fait avec get_error_data(), qui accepte lui aussi un code d’erreur optionnel :
$resultat = trouver_commande( $id );
if ( is_wp_error( $resultat ) ) {
$donnees = $resultat->get_error_data( 'commande_introuvable' );
$statut = isset( $donnees['status'] ) ? $donnees['status'] : 500;
wp_send_json_error( $resultat->get_error_message(), $statut );
}
Ce petit détour évite d’écrire une classe My_Custom_Error extends WP_Error juste pour ajouter une propriété de statut : la classe native suffit largement, et rester dessus garantit la compatibilité avec toutes les fonctions qui manipulent déjà des objets WP_Error dans le cœur.
Plusieurs jeux de données sur une même erreur
Un point souvent ignoré : add_data() peut être appelée plusieurs fois pour des codes différents sur le même objet. WordPress autorise en effet un objet WP_Error unique à porter plusieurs codes d’erreur, chacun avec son propre message et ses propres données.
- Un code par type de problème rencontré (validation, permission, ressource manquante).
- Une donnée
statuspropre à chaque code, pour renvoyer le bon statut selon le cas déclenché. - Une méthode
get_error_codes()pour lister tous les codes présents avant de choisir lequel traiter en priorité.
Cette souplesse est particulièrement utile dans une fonction de validation qui accumule plusieurs erreurs avant de les renvoyer d’un coup, plutôt que de s’arrêter à la première anomalie détectée.
Éviter les pièges classiques
Une erreur fréquente consiste à appeler add_data() sans préciser le code alors que l’objet en contient déjà plusieurs : la donnée finit alors attachée au dernier code ajouté, pas forcément à celui qu’on visait. Autre piège : oublier que get_error_data() sans argument renvoie la donnée du premier code enregistré, ce qui peut surprendre si l’ordre d’ajout n’est pas celui qu’on imaginait.
Sur un projet où plusieurs fonctions de validation s’enchaînent, mieux vaut donc toujours passer le code explicitement, dans les deux sens, écriture comme lecture. Le gain en clarté du code compense largement les quelques caractères supplémentaires.
Systématiser une clé
statussur toutes les erreurs métier d’un projet évite de retomber, six mois plus tard, sur un statut 500 générique là où un 404 ou un 409 aurait mieux renseigné le client.
Notre verdict
add_data() ne réinvente rien de spectaculaire, mais elle règle un vrai manque : donner du sens HTTP à une erreur métier sans complexifier la hiérarchie de classes du projet. Sur une API interne construite avec les briques natives de WordPress, adopter systématiquement cette convention rend chaque retour d’erreur immédiatement exploitable côté client, sans dictionnaire de correspondance à maintenir à part.
