wp_die avec un tableau d’arguments : une page d’erreur sans thème complet

« Are you sure you want to do this? » : ce message générique, produit par un appel à wp_die() sans argument de personnalisation, s’affiche par défaut dès qu’une vérification de sécurité échoue sans message explicite fourni. Il fait le travail, mais il reste peu informatif pour la personne qui le voit, et il ne dit rien du code de réponse HTTP réellement envoyé.

Le troisième paramètre de wp_die(), souvent oublié, permet de corriger les deux points en un seul appel, sans reconstruire une page d’erreur complète ni dépendre du thème actif.

La signature complète de wp_die

wp_die( string|WP_Error $message = '', string|int $title = '', string|array $args = array() ) accepte, dans son tableau d’arguments, plusieurs clés utiles : response pour fixer explicitement le code de statut HTTP renvoyé, back_link pour afficher un lien de retour, et exit pour contrôler si le script doit s’arrêter après l’affichage — utile notamment dans le contexte d’exécution des tests automatisés, où interrompre le processus PHP n’est pas souhaitable.

Sans ce troisième paramètre, wp_die() renvoie par défaut un code 200 pour un message simple, ce qui n’est presque jamais ce qu’attend un client HTTP, un navigateur ou un outil de supervision qui surveille les codes de réponse du site.

Bloquer un accès avec un code de réponse correct

Une extension qui protège un point de terminaison REST personnalisé, réservé à un usage interne, peut refuser proprement une requête non autorisée :

function extension_verifier_acces_point_terminaison( $requete ) {
    if ( ! current_user_can( 'manage_options' ) ) {
        wp_die(
            esc_html__( 'Cette ressource est réservée aux administrateurs du site.', 'extension-api-interne' ),
            esc_html__( 'Accès refusé', 'extension-api-interne' ),
            array(
                'response'  => 403,
                'back_link' => true,
            )
        );
    }

    // Traitement de la requête autorisée…
}

Le code 403 transmis dans response informe correctement tout client — navigateur, outil de test, service de supervision — que l’accès a été refusé pour une raison d’autorisation, plutôt que de laisser croire à une réponse réussie avec un contenu inattendu.

Un titre qui aide vraiment le lecteur

Le second paramètre, $title, alimente la balise <title> de la page d’erreur générée. Un titre par défaut générique — « WordPress › Erreur » — donne peu d’indication, alors qu’un titre spécifique au contexte oriente immédiatement la personne qui consulte le message, en particulier si elle a ouvert cette page depuis un onglet séparé après avoir suivi un lien.

Ce que wp_die ne remplace pas

• Elle ne remplace pas la page 404 gérée par le gabarit du thème actif : ce cas correspond à un contenu introuvable, pas à un blocage volontaire décidé par le code.
• Elle n’est pas pensée pour un usage répété à haute fréquence sur des pages publiques : son rôle reste de stopper un traitement en cours suite à une condition anormale, pas d’afficher un contenu structuré destiné aux visiteurs.
• Elle ne journalise rien automatiquement : si le blocage doit être tracé, un appel à error_log() ou à un service de journalisation dédié doit précéder l’appel à wp_die().

Toujours renseigner la clé response du tableau d’arguments : sans elle, un blocage volontaire risque d’être interprété comme une réponse réussie par un client HTTP automatisé.

Le cas particulier d’une requête AJAX ou REST

Face à une requête AJAX classique ou à un point de terminaison REST, wp_die() adapte automatiquement sa sortie : plutôt que la page HTML complète produite pour une requête de navigation classique, elle renvoie une réponse plus adaptée au contexte, tout en respectant le code indiqué dans response. Ce comportement dispense généralement d’écrire une logique différente selon le type de requête reçue, le tableau d’arguments restant le même dans les deux cas.

En résumé

Le troisième paramètre de wp_die() reste sous-utilisé alors qu’il règle en un seul appel deux problèmes fréquents : un titre de page générique et un code de réponse HTTP par défaut rarement adapté à un blocage volontaire. Pour toute vérification de sécurité qui interrompt un traitement — capacité insuffisante, jeton invalide, ressource protégée — ce tableau d’arguments permet de rester précis sans construire une page d’erreur complète à partir de zéro.