restore_exception_handler()

Introduzione

PHP permette di installare un handler di eccezioni globale con set_exception_handler() — una callback che viene eseguita ogni volta che un'eccezione si propaga senza essere catturata. restore_exception_handler() è la controparte: rimuove l'handler attualmente in cima allo stack e riattiva quello che era attivo in precedenza. Questa pagina spiega cosa fa la funzione, il suo valore di ritorno preciso e quando è la scelta giusta utilizzarla.

Come funziona lo stack degli handler di eccezioni

Ogni chiamata a set_exception_handler() inserisce un handler in uno stack interno. Solo l'elemento in cima allo stack è attivo in un dato momento. restore_exception_handler() rimuove l'elemento in cima, così l'handler installato in precedenza (o il comportamento predefinito di PHP, se lo stack è vuoto) torna ad essere attivo.

Questo modello push/pop è ciò che rende la funzione utile: una libreria o un blocco di codice può installare temporaneamente il proprio handler, poi ripristinare quello del chiamante quando ha finito — senza dover sapere quale fosse quell'handler.

Se sei nuovo alle eccezioni, inizia con PHP Exceptions e il capitolo su try/catch; restore_exception_handler() gestisce solo l'handler globale delle eccezioni non catturate, non i blocchi catch che scrivi inline.

Sintassi

restore_exception_handler(): true

La funzione non accetta parametri e restituisce sempre true. Non restituisce l'handler rimosso — per leggere l'handler precedente, cattura il valore restituito da set_exception_handler() (che fornisce l'handler attivo prima che esso stesso venisse impostato).

Esempio: sovrascrittura temporanea dell'handler

Il frammento di codice seguente installa un handler base, poi lo sovrascrive temporaneamente per una sezione di codice e ripristina l'handler base successivamente:

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

Output:

Base: something failed

Il temp_handler è stato rimosso da restore_exception_handler(), quindi quando l'eccezione non catturata raggiunge la cima dello script, viene eseguito base_handler. Nota che l'handler globale si attiva solo per le eccezioni non catturate — qualsiasi eccezione racchiusa in un try/catch corrispondente non lo raggiunge mai.

Leggere l'handler precedente

restore_exception_handler() di per sé non restituisce l'handler rimosso. Se hai bisogno di sapere quale callable era attivo prima della sovrascrittura, salva il valore restituito da 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 usarla

• Override con scope limitato. Una routine installa il proprio handler per la durata di un'operazione, poi chiama restore_exception_handler() in modo che il resto del programma mantenga il comportamento originale.
• Librerie. Il codice che non possiede l'handler globale può prenderlo temporaneamente in prestito e restituirlo educatamente.
• Logica di cleanup e shutdown. Annulla un handler temporaneo prima che lo script termini, così non si propaga al codice successivo.

Influisce solo sugli handler di eccezioni — per ripristinare un handler di errori standard impostato con set_error_handler(), usa invece restore_error_handler().

Diagramma

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]

Esercizio