restore_exception_handler()

Introducción

PHP permite instalar un manejador de excepciones global con set_exception_handler() — una función de retorno que se ejecuta cada vez que una excepción sube sin ser capturada. restore_exception_handler() es su contraparte: elimina el manejador que está en la cima de la pila y reactiva el que estaba activo antes. Esta página explica qué hace la función, su valor de retorno exacto y cuándo es la elección adecuada.

Cómo funciona la pila de manejadores de excepciones

Cada llamada a set_exception_handler() apila un manejador en una pila interna. Solo la cima de la pila está activa en cada momento. restore_exception_handler() extrae la entrada superior, de modo que el manejador instalado previamente (o el predeterminado de PHP, si la pila queda vacía) toma el control.

Este modelo de apilado/extracción es lo que hace útil a la función: una biblioteca o un bloque de código puede instalar temporalmente su propio manejador y luego restaurar el del llamante cuando termina, sin necesidad de saber cuál era ese manejador.

Si eres nuevo en las excepciones, comienza con Excepciones de PHP y el capítulo try/catch; restore_exception_handler() solo trabaja con el manejador global de excepciones no capturadas, no con los bloques catch que escribes en línea.

Sintaxis

restore_exception_handler(): true

La función no acepta ningún parámetro y siempre devuelve true. No devuelve el manejador que eliminó — para obtener el manejador anterior, captura el valor devuelto por set_exception_handler() (que te da el manejador que estaba activo antes de que este se estableciera).

Ejemplo: sobreescritura temporal del manejador

El fragmento a continuación instala un manejador base, luego lo sobreescribe temporalmente para una sección del código y después restaura el manejador 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");

Salida:

Base: something failed

temp_handler fue extraído por restore_exception_handler(), por lo que cuando la excepción no capturada llega a la cima del script, se ejecuta base_handler en su lugar. Ten en cuenta que el manejador global solo se activa para excepciones no capturadas — cualquier cosa envuelta en un bloque try/catch coincidente nunca llega a él.

Leer el manejador anterior

restore_exception_handler() en sí mismo no devuelve el manejador eliminado. Si necesitas saber qué callable estaba activo antes de sobreescribirlo, guarda el valor de retorno 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

Cuándo usarla

• Sobreescrituras con alcance delimitado. Una rutina instala su propio manejador durante la ejecución de una tarea y luego llama a restore_exception_handler() para que el resto del programa conserve el comportamiento original.
• Bibliotecas. El código que no es propietario del manejador global puede tomarlo prestado temporalmente y devolverlo con cortesía.
• Lógica de limpieza y cierre. Deshacer un manejador temporal antes de que el script termine para que no se filtre al código posterior.

Solo afecta a los manejadores de excepciones — para restaurar un manejador de errores estándar establecido con set_error_handler(), usa restore_error_handler() en su lugar.

Diagrama

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]

Práctica