restore_exception_handler()

Introduction

PHP vous permet d'installer un gestionnaire d'exceptions global avec set_exception_handler() — un callback qui s'exécute chaque fois qu'une exception remonte jusqu'au sommet sans être interceptée. restore_exception_handler() est son homologue : il supprime le gestionnaire actuellement en haut de la pile et réactive celui qui était actif avant. Cette page explique ce que fait la fonction, sa valeur de retour exacte et dans quels cas il est judicieux de l'utiliser.

Fonctionnement de la pile de gestionnaires d'exceptions

Chaque appel à set_exception_handler() empile un gestionnaire sur une pile interne. Seul le sommet de la pile est actif à tout moment. restore_exception_handler() dépile l'entrée du sommet, de sorte que le gestionnaire précédemment installé (ou le comportement par défaut intégré à PHP, si la pile devient vide) reprend la main.

Ce modèle d'empilement/dépilement est ce qui rend la fonction utile : une bibliothèque ou un bloc de code peut temporairement installer son propre gestionnaire, puis restaurer celui de l'appelant une fois terminé — sans avoir besoin de savoir quel était ce gestionnaire.

Si vous débutez avec les exceptions, commencez par PHP Exceptions et le chapitre try/catch ; restore_exception_handler() ne concerne que le gestionnaire d'exceptions global pour les exceptions non interceptées, pas les blocs catch que vous écrivez en ligne.

Syntaxe

restore_exception_handler(): true

La fonction ne prend aucun paramètre et retourne toujours true. Elle ne retourne pas le gestionnaire qu'elle a supprimé — pour lire le gestionnaire précédent, capturez la valeur retournée par set_exception_handler() (qui vous donne le gestionnaire qui était actif avant qu'il soit défini).

Exemple : remplacement temporaire du gestionnaire

L'extrait ci-dessous installe un gestionnaire de base, le remplace temporairement pour une section de code, puis restaure le gestionnaire de base :

<?php
function base_handler($e) {
    echo "Base: " . $e->getMessage() . "\n";
}

function temp_handler($e) {
    echo "Temp: " . $e->getMessage() . "\n";
}

set_exception_handler('base_handler');
set_exception_handler('temp_handler'); // pushes temp on top

restore_exception_handler();           // pops temp, base is active again

// Because this exception is never caught, the active global handler runs:
throw new Exception("something failed");

Résultat :

Base: something failed

Le temp_handler a été dépilé par restore_exception_handler(), donc lorsque l'exception non interceptée atteint le sommet du script, c'est base_handler qui s'exécute. Notez que le gestionnaire global ne se déclenche que pour les exceptions non interceptées — tout ce qui est enveloppé dans un try/catch correspondant ne l'atteint jamais.

Récupérer le gestionnaire précédent

restore_exception_handler() ne retourne pas le gestionnaire supprimé. Si vous avez besoin de savoir quel callable était actif avant de l'avoir remplacé, enregistrez la valeur de retour de set_exception_handler() :

<?php
set_exception_handler('base_handler');

// set_exception_handler() returns the handler it replaced:
$previous = set_exception_handler('temp_handler');

var_dump($previous); // string(12) "base_handler"

restore_exception_handler(); // back to base_handler

Quand l'utiliser

• Remplacements délimités. Une routine installe son propre gestionnaire pour la durée d'une tâche, puis appelle restore_exception_handler() pour que le reste du programme conserve le comportement original.
• Bibliothèques. Du code qui ne possède pas le gestionnaire global peut l'emprunter temporairement et le restituer proprement.
• Logique de nettoyage et d'arrêt. Annulez un gestionnaire temporaire avant la fin du script pour éviter qu'il ne se propage dans le code suivant.

Cela n'affecte que les gestionnaires d'exceptions — pour restaurer un gestionnaire d'erreurs standard défini avec set_error_handler(), utilisez restore_error_handler() à la place.

Diagramme

graph TD
A[set_exception_handler base] --> B[set_exception_handler temp pushes on top]
B --> C[restore_exception_handler pops temp]
C --> D[base handler active again]
D --> E[Uncaught exception runs base handler]

Pratique