restore_exception_handler()

Introdução

O PHP permite instalar um manipulador de exceções global com set_exception_handler() — um callback que é executado sempre que uma exceção sobe sem ser capturada. restore_exception_handler() é o seu contraparte: remove o manipulador que está no topo da pilha e reativa o que estava ativo antes. Esta página explica o que a função faz, seu valor de retorno exato e quando utilizá-la é a escolha certa.

Como funciona a pilha de manipuladores de exceções

Cada chamada a set_exception_handler() empurra um manipulador para uma pilha interna. Apenas o topo da pilha está ativo a qualquer momento. restore_exception_handler() retira a entrada do topo, de modo que o manipulador instalado anteriormente (ou o padrão interno do PHP, se a pilha ficar vazia) assume o controle novamente.

Este modelo de empilhamento é o que torna a função útil: uma biblioteca ou um bloco de código pode instalar temporariamente seu próprio manipulador e, depois, restaurar o manipulador do chamador quando terminar — sem precisar saber qual era esse manipulador.

Se você é novo em exceções, comece com Exceções PHP e o capítulo try/catch; restore_exception_handler() lida apenas com o manipulador global de exceções não capturadas, não com os blocos catch escritos inline.

Sintaxe

restore_exception_handler(): true

A função não aceita nenhum parâmetro e sempre retorna true. Ela não retorna o manipulador removido — para ler o manipulador anterior, capture o valor retornado por set_exception_handler() (que fornece o manipulador que estava ativo antes de ele ser definido).

Exemplo: substituindo temporariamente o manipulador

O trecho abaixo instala um manipulador base, depois o substitui temporariamente para uma seção do código e restaura o manipulador base em seguida:

<?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");

Saída:

Base: something failed

O temp_handler foi removido por restore_exception_handler(), portanto, quando a exceção não capturada chega ao topo do script, base_handler é executado em vez dele. Note que o manipulador global só é acionado para exceções não capturadas — qualquer coisa envolvida em um try/catch correspondente nunca o alcança.

Lendo o manipulador anterior

restore_exception_handler() em si não devolve o manipulador removido. Se você precisar saber qual callable estava ativo antes de substituí-lo, salve o 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

Quando usar

• Substituições com escopo. Uma rotina instala seu próprio manipulador durante a execução de uma tarefa e depois chama restore_exception_handler() para que o restante do programa mantenha o comportamento original.
• Bibliotecas. Código que não é dono do manipulador global pode emprestá-lo temporariamente e devolvê-lo adequadamente.
• Lógica de limpeza e encerramento. Desfaça um manipulador temporário antes de o script terminar para que ele não vaze para o código posterior.

Isso afeta apenas os manipuladores de exceções — para restaurar um manipulador de erros padrão definido com set_error_handler(), use restore_error_handler().

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ática