« wp_die() arrête l'exécution du script et affiche un message d'erreur. » C’est ainsi que la documentation officielle de WordPress résume cette fonction. Ce résumé cache une fonction bien plus riche qu’un simple die() de PHP : elle peut habiller l’écran affiché, fixer un code de statut HTTP précis, et même déclencher un comportement différent selon que la requête vient d’un navigateur classique ou d’un appel AJAX.
Pourtant, dans la grande majorité des thèmes, l’appel par défaut produit un écran blanc, une police système et un lien « Retour » qui ne ressemble à rien du site visité. Pour un client qui tombe dessus pendant une opération de maintenance planifiée, l’effet est déroutant. Voici comment obtenir un rendu cohérent, sans plugin.
Comprendre ce que wp_die() affiche par défaut
Sans intervention, wp_die() charge un gabarit minimal défini dans wp-includes/functions.php, avec un style inline très sommaire. Ce comportement est volontaire : la fonction doit pouvoir s’exécuter même si le thème est cassé ou totalement absent, situation dans laquelle elle sert justement d’affichage de secours.
if ( wp_get_environment_type() === 'production' && site_en_maintenance() ) {
wp_die(
'Le site est en cours de mise à jour, merci de revenir dans quelques minutes.',
'Maintenance en cours',
array( 'response' => 503 )
);
}
Le troisième argument, un tableau, accepte notamment response pour fixer le code HTTP renvoyé. Utiliser 503 plutôt que le 200 par défaut est important : cela indique aux moteurs de recherche qu’il s’agit d’une indisponibilité temporaire, pas d’un contenu supprimé.
Filtrer le gabarit affiché
Deux filtres permettent de reprendre la main sur le rendu : wp_die_handler pour remplacer entièrement la fonction de rendu, et une approche plus légère consistant à injecter du CSS via le filtre wp_die_ajax_handler uniquement quand la requête n’est pas AJAX.
function monthème_die_handler( $handler ) {
return 'monthème_afficher_maintenance';
}
add_filter( 'wp_die_handler', 'monthème_die_handler' );
function monthème_afficher_maintenance( $message, $title = '', $args = array() ) {
status_header( isset( $args['response'] ) ? $args['response'] : 500 );
get_header();
echo '<div class="maintenance-message">';
echo '<h2>' . esc_html( $title ) . '</h2>';
echo wp_kses_post( $message );
echo '</div>';
get_footer();
die();
}
En rappelant get_header() et get_footer(), l’écran affiché reprend la charte graphique du thème : logo, menu, pied de page. Le visiteur comprend qu’il est toujours sur le bon site, simplement dans une situation temporaire.
Adapter le message selon le contexte
Il est tentant d’utiliser wp_die() partout, mais chaque contexte mérite un message différent. Une liste des cas les plus fréquents rencontrés dans un thème classique :
- Maintenance planifiée : message rassurant, code 503, éventuellement une durée estimée.
- Fonctionnalité désactivée volontairement (formulaire fermé, inscriptions closes) : code 200, message explicatif, pas d’alarme inutile.
- Accès refusé à une zone protégée : code 403, ton neutre, pas de détail sur la raison exacte du refus.
Le piège de l’appel trop précoce
Un appel à get_header() depuis un gestionnaire de wp_die() ne fonctionne que si les fonctions de thème sont déjà chargées, ce qui n’est pas garanti dans certains contextes très précoces d’exécution, par exemple pendant l’installation ou une mise à jour de base de données. Dans ces cas rares, mieux vaut détecter le contexte avec defined( 'WP_INSTALLING' ) et retomber sur un affichage minimal plutôt que de provoquer une erreur en cascade.
Sur nos projets, on réserve ce gestionnaire personnalisé aux interruptions visibles côté visiteur ; pour les erreurs strictement internes à l’administration, l’écran par défaut de WordPress reste préférable, car il n’a pas besoin du thème pour s’afficher correctement.
En résumé
wp_die() mérite d’être traité comme un élément de design à part entière, pas comme un simple filet de sécurité technique. Un gestionnaire personnalisé, quelques lignes de style, et un code HTTP correctement choisi transforment un écran d’interruption en un moment cohérent avec le reste de l’expérience du site.
