set_exception_handler()

Introduction

set_exception_handler() enregistre une fonction que PHP appelle chaque fois qu'une exception non capturée atteint le sommet du script. Normalement, une exception non capturée produit une erreur fatale et une trace de pile par défaut ; un gestionnaire global vous permet de remplacer cela par une journalisation cohérente, une page d'erreur conviviale ou des alertes — en un seul endroit, pour toute l'application. Cette page couvre la signature de la fonction, ce qu'elle retourne, un exemple exécutable, les cas qu'elle ne couvre pas et les pièges à connaître.

Si vous avez d'abord besoin des bases sur le lancement et la capture d'exceptions, commencez par PHP Exceptions et le chapitre try/catch.

Quand le gestionnaire est-il appelé ?

Une exception normale est capturée par le bloc catch correspondant le plus proche. Le gestionnaire global ne s'exécute que lorsqu'aucun bloc catch ne correspond — l'exception « s'échappe » jusqu'en dehors du script :

try {
    throw new RuntimeException('handled here');
} catch (RuntimeException $e) {
    // caught locally — the global handler never runs
}

throw new RuntimeException('nothing catches this'); // → global handler runs, then script ends

Après le retour du gestionnaire, l'exécution ne reprend pas — le script se termine. Le gestionnaire est donc votre dernière chance de journaliser et de présenter l'échec proprement, et non un moyen de récupérer et de continuer.

Signature et valeur de retour

set_exception_handler(?callable $callback): ?callable

• $callback — un callable qui accepte l'objet lancé comme unique argument. Depuis PHP 7, chaque exception et erreur implémente Throwable, donc typez le paramètre en Throwable (pas seulement Exception) pour capturer également les instances d'Error comme TypeError.
• Retourne le gestionnaire précédemment enregistré (ou null si aucun n'était défini), que vous pouvez conserver pour le restaurer ultérieurement. Passer null supprime le gestionnaire.

Exemple exécutable

Le script ci-dessous enregistre un gestionnaire, le déclenche avec une exception non capturée et affiche un message formaté. Il écrit sur l'erreur standard via error_log() sans destination, ce qui le rend entièrement portable :

<?php

function appExceptionHandler(Throwable $e): void
{
    $message = sprintf(
        "Uncaught %s: %s in %s on line %d",
        get_class($e),
        $e->getMessage(),
        $e->getFile(),
        $e->getLine()
    );

    error_log($message);            // goes to the SAPI error log / stderr
    echo "Something went wrong.\n"; // user-facing message
}

set_exception_handler('appExceptionHandler');

throw new RuntimeException('Database is unreachable');

Sortie (la ligne error_log va vers stderr, le echo vers stdout) :

Something went wrong.

avec une ligne comme Uncaught RuntimeException: Database is unreachable in /path/to/script.php on line 19 dans le journal des erreurs.

Ce qu'il ne gère PAS

set_exception_handler() n'intercepte que les exceptions non capturées. Il ne capture pas :

• Les erreurs fatales, les erreurs d'analyse ou les avertissements — ceux-ci passent par set_error_handler() (pour les erreurs capturables) ou register_shutdown_function() (pour les erreurs fatales).
• Les exceptions déjà capturées par un bloc local try/catch.

Pour les erreurs non-exception telles que les avertissements et les notices, enregistrez un gestionnaire séparé avec set_error_handler().

Restaurer le gestionnaire précédent

restore_exception_handler() revient au gestionnaire actif avant votre dernier appel à set_exception_handler(). Utilisez-le lorsqu'un gestionnaire personnalisé ne doit s'appliquer qu'à un bloc de code spécifique :

<?php

set_exception_handler(function (Throwable $e) {
    echo "Custom: {$e->getMessage()}\n";
});

// ... code that should use the custom handler ...

restore_exception_handler(); // back to the default behavior

Important : votre gestionnaire ne doit pas lancer une nouvelle exception. S'il le fait, PHP ne peut pas la dispatcher à nouveau et génère une erreur fatale à la place.

Bonnes pratiques pour utiliser set_exception_handler

Lorsque vous utilisez set_exception_handler, quelques bonnes pratiques à suivre pour garantir que votre application gère efficacement les erreurs :

1. Typez le paramètre du gestionnaire en Throwable pour qu'il capture à la fois les sous-types d'Exception et d'Error (PHP 7+).
2. Assurez-vous que le gestionnaire ne lance jamais une nouvelle exception — cela déclencherait une erreur fatale irrécupérable.
3. Journalisez suffisamment de contexte pour diagnostiquer l'échec : classe de l'exception, message, fichier, ligne et la trace de pile via $e->getTraceAsString().
4. Gardez le message destiné à l'utilisateur générique ; ne divulguez jamais des traces de pile ou des messages aux utilisateurs finaux en production.
5. Enregistrez le gestionnaire le plus tôt possible (par exemple dans un fichier de démarrage) pour qu'il couvre toute la requête.
6. Associez-le à set_error_handler() et register_shutdown_function() pour couvrir également les avertissements, les notices et les erreurs fatales.
7. Utilisez restore_exception_handler() pour revenir au gestionnaire précédent lorsqu'un gestionnaire personnalisé doit être limité à un bloc de code.

Conclusion

set_exception_handler() vous offre un seul endroit pour gérer toutes les exceptions non capturées dans une application — transformant une erreur fatale brute en journalisation cohérente et en message convivial pour l'utilisateur. N'oubliez pas ses limites : il ne s'exécute que pour les exceptions non capturées, l'exécution s'arrête après, et le gestionnaire lui-même ne doit jamais lancer d'exception. Combinez-le avec set_error_handler() pour les avertissements, trigger-error pour les signaux d'erreur personnalisés, et restore_exception_handler() pour la gestion délimitée afin de construire un rapport d'erreurs robuste.

Pratique