Descrizione

set_error_handler(callable $error_handler, int $error_types = E_ALL | E_STRICT): mixed

Configura una funzione utente (error_handler) per gestire gli errori in uno script.

Questa funzione può essere utilizzata per definire un sistema personalizzato di gestione degli errori durante l'esecuzione, per esempio in applicazioni dove sia necessario svuotare dati o file in caso di un determinato errore critico, o quando sia necessario, in determinate condizioni, attivare un errore (con trigger_error()).

È importante ricordare che il gestore degli errori standard di PHP viene completamente saltato per i tipi di errore specificati da error_types salvo che la funzione di callback non restituisca false. La configurazione di error_reporting non avrà effetto e il proprio gestore di errore sarà richiamato senza considerarla - in ogni caso sarà possibile leggere il valore corrente di error_reporting() ed agire di conseguenza. È di particolare rilevanza il fatto che questo valore sarà 0 se l' istruzione che causa l'errore viene preceduta dall' operatore di controllo errore @.

Notare anche che è vostra responsabilità richiamare die() se necessario. Se la funzione di gestione dell'errore ritorna, lo script continuerà l'esecuzione con l'istruzione seguente a quella che ha causato un errore.

I seguenti tipi di errori non saranno gestiti dalla funzione definita dall'utente: E_ERROR, E_PARSE, E_CORE_ERROR, E_CORE_WARNING, E_COMPILE_ERROR, E_COMPILE_WARNING indipendentemente da dove sono stati sollevati, e buona parte degli E_STRICT sollevati nel file dove viene richiamata set_error_handler().

Se occorrono errori prima che lo script sia in esecuzione (ad esempio durante l'upload di file) la funzione definita dell'utente non può essere richiamata perché non è ancora stata registrata in quel momento.

Elenco dei parametri

error_handler

Una funzione di callback con la seguente firma. null può essere invece passato per ripristinare il gestore di default. Invece di un nome di funzione, possono anche essere forniti un array contenente un riferimento ad un oggetto ed un nome di metodo.

handler(
    int $errno,
    string $errstr,
    string $errfile = ?,
    int $errline = ?,
    array $errcontext = ?
): bool

errno: Il primo parametro, errno, contiene il livello dell'errore lanciato, come intero.
errstr: Il secondo parametro, errstr, contiene il messaggio di errore, come stringa.
errfile: Il terzo parametro opzionale, errfile, contiene il nome del file che ha generato l'errore, come stringa.
errline: Il quarto parametro è opzionale, errline, che contiene il numero di riga relativo al file che ha generato l'errore, come intero.
errcontext: Il quinto parametro è opzionale, errcontext, che è un array che punta alla tabella simboli al punto dove l'errore è stato generato. In altre parole, errcontext conterrà un vettore di tutte le variabili che esistono nello scope dove l'errore è avvenuto. La funzione utente che gestisce gli errori non dovrebbe mai modificare il contesto dell'errore.
Avviso
Questo parametro è stato DEPRECATO da PHP 7.2.0. Fare affidamento su di esso è altamente scoraggiato.

Se la funzione ritorna false allora viene eseguito il normale gestore degli errori.

error_types

Può essere usato per mascherare il triggering della funzione error_handler allo stesso modo dell'impostazione ini error_reporting che controlla quali errori mostrare. Senza questa maschera settata l' error_handler verrà richiamata per ogni errore senza tener conto dell'impostazione di error_reporting.

Valori restituiti

Ritorna una stringa contenente l'eventuale precedente funzione degli errori. Ritorna null se la funzione degli errori è quella built-in. Anche in caso di errore (come funzione di callback invalida) viene restituito null. Se il gestore precedente era un metodo di classe, allora il valore ritornato sarà un array con due elementi: nome della classe e nome del metodo.

Log delle modifiche

Versione Descrizione

7.2.0 errcontext è diventato deprecato. L'utilizzo di questo parametro ora genera un avviso E_DEPRECATED.

Versione	Descrizione
7.2.0	`errcontext` è diventato deprecato. L'utilizzo di questo parametro ora genera un avviso `E_DEPRECATED`.

Esempi

Example #1 Gestione degli errori con set_error_handler() e trigger_error()

L'esempio sottostante mostra la gestione delle eccezioni interne attivando gli errori e gestendoli tramite una funzione definita dall'utente:

<?php
// funzione di gestione dell'errore
function myErrorHandler($errno, $errstr, $errfile, $errline)
{
    if (!(error_reporting() & $errno)) {
        // Questo codice di errore non è incluso in error_reporting, quindi lascia che ricada
        // nel gestore degli errori PHP standard
        return false;
    }

    // potrebbe essere necessario effettuare l'escape di $errstr:
    $errstr = htmlspecialchars($errstr);

    switch ($errno) {
    case E_USER_ERROR:
        echo "<b>My ERROR</b> [$errno] $errstr<br />\n";
        echo "  Fatal error on line $errline in file $errfile";
        echo ", PHP " . PHP_VERSION . " (" . PHP_OS . ")<br />\n";
        echo "Aborting...<br />\n";
        exit(1);

    case E_USER_WARNING:
        echo "<b>My WARNING</b> [$errno] $errstr<br />\n";
        break;

    case E_USER_NOTICE:
        echo "<b>My NOTICE</b> [$errno] $errstr<br />\n";
        break;

    default:
        echo "Unknown error type: [$errno] $errstr<br />\n";
        break;
    }

    /* Non esegue il gestore degli errori interno di PHP */
    return true;
}

// funzione per testare la gestione degli errori
function scale_by_log($vect, $scale)
{
    if (!is_numeric($scale) || $scale <= 0) {
        trigger_error("log(x) for x <= 0 is undefined, you used: scale = $scale", E_USER_ERROR);
    }

    if (!is_array($vect)) {
        trigger_error("Incorrect input vector, array of values expected", E_USER_WARNING);
        return null;
    }

    $temp = array();
    foreach($vect as $pos => $value) {
        if (!is_numeric($value)) {
            trigger_error("Value at position $pos is not a number, using 0 (zero)", E_USER_NOTICE);
            $value = 0;
        }
        $temp[$pos] = log($scale) * $value;
    }

    return $temp;
}

// imposta al gestore degli errori definito dall'utente
$old_error_handler = set_error_handler("myErrorHandler");

// innesca qualche errore, prima definisce un array misto con un item non numerico
echo "vector a\n";
$a = array(2, 3, "foo", 5.5, 43.3, 21.11);
print_r($a);

// ora genera un secondo array
echo "----\nvector b - a notice (b = log(PI) * a)\n";
/* Value at position $pos is not a number, using 0 (zero) */
$b = scale_by_log($a, M_PI);
print_r($b);

// questo è un problema, viene passata una stringa al posto di un array
echo "----\nvector c - a warning\n";
/* Incorrect input vector, array of values expected */
$c = scale_by_log("not array", 2.3);
var_dump($c); // NULL

// questo è un errore critico, il log di zero o di un numero negativo è undefined
echo "----\nvector d - fatal error\n";
/* log(x) for x <= 0 is undefined, you used: scale = $scale" */
$d = scale_by_log($a, -2.5);
var_dump($d); // Mai raggiunto
?>

Il precedente esempio visualizzerà qualcosa simile a:

vector a
Array
(
    [0] => 2
    [1] => 3
    [2] => foo
    [3] => 5.5
    [4] => 43.3
    [5] => 21.11
)
----
vector b - a notice (b = log(PI) * a)
<b>My NOTICE</b> [1024] Value at position 2 is not a number, using 0 (zero)<br />
Array
(
    [0] => 2.2894597716988
    [1] => 3.4341896575482
    [2] => 0
    [3] => 6.2960143721717
    [4] => 49.566804057279
    [5] => 24.165247890281
)
----
vector c - a warning
<b>My WARNING</b> [512] Incorrect input vector, array of values expected<br />
NULL
----
vector d - fatal error
<b>My ERROR</b> [256] log(x) for x <= 0 is undefined, you used: scale = -2.5<br />
  Fatal error on line 35 in file trigger_error.php, PHP 5.2.1 (FreeBSD)<br />
Aborting...<br />

Vedere anche:

ErrorException
error_reporting() - definisce quali errori di PHP vengono restituiti
restore_error_handler() - Ripristina la precedente funzione di gestione dell'errore
trigger_error() - Genera un messaggio a livello utente di errore/avviso/avvertimento message
error level constants