XXVII. Funzioni di gestione degli errori e di logging

Introduzione

Le seguenti sono le funzioni per la gestione degli errori ed il logging. Esse permettono di definire regole personalizzate per la gestione degli errori, e anche di modificarne la modalità della gestione stessa. Ciò permette di cambiare ed integrare i messaggi di errore adattandoli alle vostre esigenze.

Grazie alle funzioni di logging, è possibile inviare messaggi direttamente ad altre macchine, alla posta elettronica (o ad un gateway pager o di posta elettronica!), ai log di sistema, ecc., in modo da effettuare il log e controllare selettivamente le parti più importanti delle vostre applicazioni e siti web.

Le funzioni di restituzione dell'errore consentono la personalizzazione del livello e del tipo di errore, dal semplice avviso sino a funzioni personalizzate restituite durante gli errori.

Requisiti

Non sono necessarie librerie esterne per utilizzare questo modulo.

Installazione

Non è necessaria nessuna installazione per usare queste funzioni, esse fanno parte del core di PHP.

Configurazione di Runtime

Il comportamento di queste funzioni è influenzato dalle impostazioni di php.ini.

Tabella 1. Parametri di configurazione per la gestione degli errori e dei log

NomeDefaultModificabile
error_reportingE_ALL & ~E_NOTICEPHP_INI_ALL
display_errors"1"PHP_INI_ALL
display_startup_errors"0"PHP_INI_ALL
log_errors"0"PHP_INI_ALL
log_errors_max_len"1024"PHP_INI_ALL
ignore_repeated_errors"0"PHP_INI_ALL
ignore_repeated_source"0"PHP_INI_ALL
report_memleaks"1"PHP_INI_ALL
track_errors"0"PHP_INI_ALL
html_errors"1"PHP_INI_ALL
docref_root""PHP_INI_ALL
docref_ext""PHP_INI_ALL
error_prepend_stringNULLPHP_INI_ALL
error_append_stringNULLPHP_INI_ALL
error_logNULLPHP_INI_ALL
warn_plus_overloadingNULLPHP_INI??
Per maggiori dettaglii e per le definizioni delle costanti PHP_INI_* vedere ini_set().

Breve descrizione dei parametri di configurazione.

error_reporting integer

Imposta il livello di errore da visualizzare. Il parametro è sia un intero rappresentante un campo di bit, o una costante nominale. I livelli ri report degli errori e le costanti previste sono descritte in Costanti Predefinite, e in php.ini. Per impostare il livello in fase di esecuzione utilizzare la funzione error_reporting(). Vedere anche il parametro display_errors.

In PHP 4 e PHP 5 il valore di default è E_ALL & ~E_NOTICE. Questa impostazione non visualizza gli errori di livello E_NOTICE. Tuttavia può essere comodo visualizzare questi messaggi in fase di sviluppo.

Nota: Abilitare E_NOTICE durante la fase di sviluppo ha dei benefici. Ad esempio per scopi di debug: i messaggi di tipo NOTICE avvisano su possibili bug nel codice. L'uso di variabili non assegnate, ad esempio, viene rilevato con questo livello di errore. Particolare che è molto utile per trovare errori di battitura e risparmiare tempo in fase di debug. I messaggi di tipo NOTICE segnalano il codice scritto con un cattivo stile. Ad esempio, $arr[item] è meglio che sia scritto come $arr['item'] poichè il PHP tenta di trattare "item" come costante. Se non esiste una simile costante, il PHP presume che si tratti dell'indice di una matrice.

Nota: Nel PHP 5 è stato introdotto un nuovo livello di errore E_STRICT. Come E_STRICT non viene incluso nel E_ALL e, pertanto, occorre abilitarlo in modo esplicito. Abilitare E_STRICT durante la fase di sviluppo porta alcuni benefici. Questa casistica di messaggi servono ad aiutare le più recenti, e consigliate, metodologie di programamzione, avvisando, ad esempio, sull'uso di funzioni deprecate.

In PHP 3 l'impostazione di default è (E_ERROR | E_WARNING | E_PARSE), che significa la medesima cosa. Occorre rilevare, tuttavia, che le costanti non sono supportate nel php3.ini del PHP 3, e pertanto occorre utilizzare la codifica numerica, che corrisponde a 7.

display_errors boolean

Questo parametro determina se gli errori devono essere visualizzati sullo schermo come parte dell'output o se devono essere nascosti all'utente.

Nota: Questa opzione è di supporto allo sviluppo, e non deve mai essere utilizzata nei sistemi di produzione (ad esempio collegati ad Internet).

display_startup_errors boolean

Anche quando è abilitata la visualizzazione degli errori, gli errori che avvengono durante l'avvio del PHP non sono visualizzati. Si raccomanda di mantenere display_startup_errors impostato a off, tranne che nelle fasi di sviluppo.

log_errors boolean

Indica se i messaggi di errore debbano essere registrati nell'errorlog del server o in error_log. Questo opzione dipende dal server.

Nota: Sui siti di produzione si raccomanda di utilizzare la registrazione degli errori piuttosto che visualizzarli.

log_errors_max_len integer

Imposta la massima lunghezza del log degli errori in byte. Nell'errorlog error_log viene indicata anche la fonte del messaggio. Il valore di default è 1024 e 0 indica di non applicare alcuna limitazione.

ignore_repeated_errors boolean

Do not log repeated messages. Repeated errors must occur in the same file on the same line until ignore_repeated_source is set true.

ignore_repeated_source boolean

Ignore source of message when ignoring repeated messages. When this setting is On you will not log errors with repeated messages from different files or sourcelines.

report_memleaks boolean

If this parameter is set to Off, then memory leaks will not be shown (on stdout or in the log). This has only effect in a debug compile, and if error_reporting includes E_WARNING in the allowed list

track_errors boolean

If enabled, the last error message will always be present in the variable $php_errormsg.

html_errors boolean

Turn off HTML tags in error messages. The new format for HTML errors produces clickable messages that direct the user to a page describing the error or function in causing the error. These references are affected by docref_root and docref_ext.

docref_root string

The new error format contains a reference to a page describing the error or function causing the error. In case of manual pages you can download the manual in your language and set this ini directive to the URL of your local copy. If your local copy of the manual can be reached by '/manual/' you can simply use docref_root=/manual/. Additional you have to set docref_ext to match the fileextensions of your copy docref_ext=.html. It is possible to use external references. For example you can use docref_root=http://manual/en/ or docref_root="http://landonize.it/?how=url&theme=classic&filter=Landon &url=http%3A%2F%2Fwww.php.net%2F"

Most of the time you want the docref_root value to end with a slash '/'. But see the second example above which does not have nor need it.

Nota: This is a feature to support your development since it makes it easy to lookup a function description. However it should never be used on production systems (e.g. systems connected to the internet).

docref_ext string

See docref_root.

Nota: The value of docref_ext must begin with a dot '.'.

error_prepend_string string

String to output before an error message.

error_append_string string

String to output after an error message.

error_log string

Name of the file where script errors should be logged. If the special value syslog is used, the errors are sent to the system logger instead. On Unix, this means syslog(3) and on Windows NT it means the event log. The system logger is not supported on Windows 95. See also: syslog().

warn_plus_overloading boolean

If enabled, this option makes PHP output a warning when the plus (+) operator is used on strings. This is to make it easier to find scripts that need to be rewritten to using the string concatenator instead (.).

Costanti predefinite

Le costanti qui elencate sono sempre disponibili in quanto parte del core di PHP.

Nota: Si possono utilizzare queste constanti in php.ini ma non all'esterno del PHP, tipo in in httpd.conf, dove occorre utilizzare in valori.

Tabella 2. Errori e log

ValoreCostanteDescrizioneNote
1 E_ERROR (integer) Errori fatali di esecuzione. Questi indicano errori che non si possono ignorare, come, ad esempio, errori di allocazione della memoria. L'esecuzione dello script è bloccata.  
2 E_WARNING (integer) Warning di esecuzione (errori non fatali). L'esecuzione dello script non viene bloccata.  
4 E_PARSE (integer) Errore di parsing in fase di compila. Essendo errori di parsing sono generati dal parser del codice PHP.  
8 E_NOTICE (integer) Informazioni di esecuzione. Questo messaggio indica che lo script ha incontrato qualcosa che potrebbe indicare un errore, ma è una sitauzione che può accadere durante una normale esecuzione di uno script.  
16 E_CORE_ERROR (integer) Errori fatali che accadono durante la fase di inizializzazione del PHP. Questo è come un E_ERROR, tranne che viene generato dall'interno del PHP. dal PHP 4
32 E_CORE_WARNING (integer) Warning (errore non fatale) che accade durante la fase di inizializzazione del PHP. Questo è come un E_WARNING, tranne che viene generato dall'interno del PHP. dal PHP 4
64 E_COMPILE_ERROR (integer) Errore fatale di compila. Questo è come E_ERROR, tranne che viene generato dal motore Zend. dal PHP 4
128 E_COMPILE_WARNING (integer) Warning di compila (errore non fatale). Questo è come E_WARNING, tranne che viene generato dal motore Zend. dal PHP 4
256 E_USER_ERROR (integer) Messaggio di errore generato dall'utente. Questo è come E_ERROR, tranne che viene generato dal codice PHP tramite la funzione trigger_error(). dal PHP 4
512 E_USER_WARNING (integer) Messaggio di warning generato dall'utente. Questo è come E_WARNING,tranne che viene generato dal codice PHP tramite la funzione trigger_error(). dal PHP 4
1024 E_USER_NOTICE (integer) Messaggio di informazione generato dall'utente. Questo è come E_NOTICE, tranne che viene generato dal codice PHP tramite la funzione trigger_error(). dal PHP 4
2047 E_ALL (integer) Tutti gli errori ed i warning supportati tranne quelli di livello E_STRICT.  
2048 E_STRICT (integer) Informazione di esecuzione. Abilitare questo messaggio per avere dal PHP suggerimenti sulle modifiche da apportare al codice per avere la migliore interoperabilità e compatibilità del codice. dal PHP 5

I valori precedenti (sia numerici, sia simbolici) possono essere utilizzati per costruire delle maschere di bit che indichino quali errori visualizzare. Si può utilizzare gli operatori sui bit per combinare questi valori o per mascherare certi tipi di errori. Fare attenzione che soltanto '|', '~', '!', '^' e '&' sono compresi dal php.ini, e che nessun operatore sui bit è gestito dal php3.ini.

Esempi

Di seguito sarà illustrato un esempio di utilizzo delle procedure di gestione dell'errore in PHP. Qui si definisce una funzione di gestione dell'errore che registra le informazioni in un file (in formato XML) e invia tramite e-mail allo sviluppare dei messaggi in caso di errori critici.

Esempio 1. Esempio dell'utilizzo di della gestione degli erorri in uno script

<?php
// attiveremo la nostra gestione degli errori
error_reporting(0);

// funzione personalizzata di gestione dell'errore
function userErrorHandler($errno, $errmsg, $filename, $linenum, $vars)
{
    
// orario per la registrazione
    
$dt = date("Y-m-d H:i:s (T)");

    
// definisce una matrice associativa con i messaggi di errore
    // in realtà i soli campi che saranno considerati sono
    // E_WARNING, E_NOTICE, E_USER_ERROR,
    // E_USER_WARNING and E_USER_NOTICE
    
$errortype = array (
                
E_ERROR           => "Error",
                
E_WARNING         => "Warning",
                
E_PARSE           => "Parsing Error",
                
E_NOTICE          => "Notice",
                
E_CORE_ERROR      => "Core Error",
                
E_CORE_WARNING    => "Core Warning",
                
E_COMPILE_ERROR   => "Compile Error",
                
E_COMPILE_WARNING => "Compile Warning",
                
E_USER_ERROR      => "User Error",
                
E_USER_WARNING    => "User Warning",
                
E_USER_NOTICE     => "User Notice",
                
E_STRICT          => "Runtime Notice"
                
);
    
// indica gli errori per i quali fare salvare la trace delle variabili
    
$user_errors = array(E_USER_ERROR, E_USER_WARNING, E_USER_NOTICE);
    
    
$err = "<errorentry>\n";
    
$err .= "\t<datetime>" . $dt . "</datetime>\n";
    
$err .= "\t<errornum>" . $errno . "</errornum>\n";
    
$err .= "\t<errortype>" . $errortype[$errno] . "</errortype>\n";
    
$err .= "\t<errormsg>" . $errmsg . "</errormsg>\n";
    
$err .= "\t<scriptname>" . $filename . "</scriptname>\n";
    
$err .= "\t<scriptlinenum>" . $linenum . "</scriptlinenum>\n";

    if (
in_array($errno, $user_errors)) {
        
$err .= "\t<vartrace>" . wddx_serialize_value($vars, "Variables") . "</vartrace>\n";
    }
    
$err .= "</errorentry>\n\n";
    
    
// for testing
    // echo $err;

    // salva nell'errorlog e invia un e-mail se vi sono errori critici
    
error_log($err, 3, "/usr/local/php4/error.log");
    if (
$errno == E_USER_ERROR) {
        
mail("phpdev@example.com", "Critical User Error", $err);
    }
}


function
distance($vect1, $vect2)
{
    if (!
is_array($vect1) || !is_array($vect2)) {
        
trigger_error("Incorrect parameters, arrays expected", E_USER_ERROR);
        return
NULL;
    }

    if (
count($vect1) != count($vect2)) {
        
trigger_error("Vectors need to be of the same size", E_USER_ERROR);
        return
NULL;
    }

    for (
$i=0; $i<count($vect1); $i++) {
        
$c1 = $vect1[$i]; $c2 = $vect2[$i];
        
$d = 0.0;
        if (!
is_numeric($c1)) {
            
trigger_error("Coordinate $i in vector 1 is not a number, using zero",
                            
E_USER_WARNING);
            
$c1 = 0.0;
        }
        if (!
is_numeric($c2)) {
            
trigger_error("Coordinate $i in vector 2 is not a number, using zero",
                            
E_USER_WARNING);
            
$c2 = 0.0;
        }
        
$d += $c2*$c2 - $c1*$c1;
    }
    return
sqrt($d);
}

$old_error_handler = set_error_handler("userErrorHandler");

// variabile non definita, genera un warning
$t = I_AM_NOT_DEFINED;

// definisce dei vettori
$a = array(2, 3, "foo");
$b = array(5.5, 4.3, -1.6);
$c = array(1, -3);

// genera un errore utente
$t1 = distance($c, $b) . "\n";

// un'altro errore utente
$t2 = distance($b, "i am not an array") . "\n";

// genera un warning
$t3 = distance($a, $b) . "\n";

?>

Vedere anche

Vedere anche syslog().

Sommario
debug_backtrace --  Generates a backtrace
debug_print_backtrace --  Prints a backtrace
error_log -- invia un messaggio di errore
error_reporting -- definisce quali errori di PHP vengono restituiti
restore_error_handler --  Ripristina la precedente funzione di gestione dell'errore
set_error_handler --  Configura una funzione di gestione dell'errore definita dall'utente.
trigger_error --  Genera un messaggio a livello utente di errore/avviso/avvertimento message
user_error --  Genera un messaggio di errore/avviso/avvertimento a livello utente