<?xml version="1.0" encoding="iso-8859-1"?>
<!-- EN-Revision: 1.24 Maintainer: cortesi Status: ready -->
 <chapter id="features.error-handling">
  <title>Gestione degli errori</title>
 
  <para>
   In PHP sono presenti diversi tipi di errori e avvertimenti (warning):

   <table>
    <title>PHP - Tipi di errore</title>
    <tgroup cols="4">
     <thead>
      <row>
       <entry>valore</entry>
       <entry>simbolo</entry>
       <entry>descrizione</entry>
       <entry>note</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>1</entry>
       <entry>E_ERROR</entry>
       <entry>Errore run-time fatale</entry>
       <entry></entry>
      </row>
      <row>
       <entry>2</entry>
       <entry>E_WARNING</entry>
       <entry>Warning run-time(errore non fatale)</entry>
       <entry></entry>
      </row>
      <row>
       <entry>4</entry>
       <entry>E_PARSE</entry>
       <entry>Errore nel parsing in compilazione</entry>
       <entry></entry>
      </row>
      <row>
       <entry>8</entry>
       <entry>E_NOTICE	</entry>
       <entry>
        Notifiche run-time (meno serie dei warning)
       </entry>
       <entry></entry>
      </row>
      <row>
       <entry>16</entry>
       <entry>E_CORE_ERROR</entry>
       <entry>Errore fatale nella fase di startup inizale di PHP</entry>
       <entry>Solo PHP 4</entry>
      </row>
      <row>
       <entry>32</entry>
       <entry>E_CORE_WARNING</entry>
       <entry>
  Warning (errore non fatale) nella fase di startup inizale di 
    PHP
       </entry>
       <entry>Solo PHP 4</entry>
      </row>
      <row>
       <entry>64</entry>
       <entry>E_COMPILE_ERROR</entry>
       <entry>Errore fatale in fase di compilazione</entry>
       <entry>Solo PHP 4</entry>
      </row>
      <row>
       <entry>128</entry>
       <entry>E_COMPILE_WARNING</entry>
       <entry>Warning (errore non fatale) in fase di compilazione</entry>
       <entry>Solo PHP 4</entry>
      </row>
      <row>
       <entry>256</entry>
       <entry>E_USER_ERROR</entry>
       <entry>Messagio di errore generato dall'utente</entry>
       <entry>Solo PHP 4</entry>
      </row>
      <row>
       <entry>512</entry>
       <entry>E_USER_WARNING</entry>
       <entry>Messaggio di avvertimento (warning) generato dall'utente</entry>
       <entry>Solo PHP 4</entry>
      </row>
      <row>
       <entry>1024</entry>
       <entry>E_USER_NOTICE</entry>
       <entry>Messagio di notifica generato dall'utente</entry>
       <entry>Solo PHP 4</entry>
      </row>
      <row>
       <entry></entry>
       <entry>E_ALL</entry>
       <entry>Tutti i precedenti</entry>
       <entry>Solo PHP 4</entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>
 
  <para>
   I valori presenti nella tabella (sia numerici che simbolici) sono utilizzati
   per creare delle bitmask per specificare quali errori segnalare. Si possono
   usare gli <link linkend="language.operators.bitwise">operatori sui bit</link> '|','&amp;' e '~' per combinare questi valori e 
   mascherare certi tipi di errori. Nota che 
   solo  '|', '~', '!', e '&amp;' verranno interpretati correttamente all'interno del 
   file <filename>php.ini</filename> e che gli operatori sui bit non
   saranno interpretati nel file  <filename>php3.ini</filename>.
  </para>
  <para>
   Nel PHP 4 la configurazione predefinita di <link
   linkend="ini.error-reporting">error_reporting</link> 
   <literal>E_ALL &amp; ~E_NOTICE</literal> che fa si che vengano visualizzati tutti gli errori
   e avvertimenti che non siano di livello E_NOTICE. Nel PHP 3 la configurazione predefinita
    <literal>(E_ERROR | E_WARNING | E_PARSE)</literal>,
   che ha lo stesso effetto. Si noti che, dato che le costanti non sono
   supportate nel file <filename>php3.ini</filename> presente nel PHP 3, la configurazione di <link
   linkend="ini.error-reporting">error_reporting</link> va effettuata usando un valore
   numerico, ad esempio <literal>7</literal>.
  </para>

  <para>
   Le configurazioni predefinite possono essere cambiate nel file ini con la direttiva <link
   linkend="ini.error-reporting">error_reporting</link>. Si pu anche utilizzare il file di configurazione di
   Apache <filename>httpd.conf</filename> con la 
   direttiva php_error_reporting (php3_error_reporting per PHP 3) oppure ancora 
   in fase di esecuzione di uno script con la
   funzione <function>error_reporting</function>.
  </para>

  <warning>
   <para>
    Quando si esegue un upgrade del codice o dei server da PHP3 a PHP4 
    necessario controllare questi settaggi e le chiamate 
    a <function>error_reporting</function>
    oppure potrebbe disabilitarsi il report dei nuovi tipi di errore, specialmente
    E_COMPILE_ERROR.  Questo potrebbe portare a documenti vuoti senza alcun
    feedback sulle cause o dove guardare per trovare il problema.
   </para>
  </warning>

   <para>	
    Tutte le <link linkend="language.expressions">espressioni PHP</link> possono anche
    venir chiamate con il prefisso "@", che disabilita il report degli errori per quella
    particolare espressione.  Se capita un errore in una di 
    queste espressioni e l'opzione <link 
    linkend="ini.track-errors">track_errors</link>  attivata, 
    si pu trovare il messaggio d'errore nella variabile 
    globale <literal>$php_errormsg</literal>.
   </para>

  <note>
   <para>
    Il prefisso <link linkend="language.operators.errorcontrol">@
    </link> non disabilita i messaggi
    che sono il risultato di errori di parsing.
   </para>
  </note>

  <warning>
   <para>
    Attualmente il prefisso <link linkend="language.operators.errorcontrol">@</link>
    disabilita anche il report 
    per gli errori critici che terminano l'esecuzione dello 
    script. Fra le altre cose, questo significa che se si usa <link
    linkend="language.operators.errorcontrol">@</link> per sopprimere
    gli errori di una determinata funzione e questa  ad esempio non disponibile oppure
     stata chiamata in maniera non corretta, lo script terminer e non 
    ci sar nessuna indicazione del perch.
   </para>
  </warning>

  <para>
   Di seguito si pu vedere un esempio di come si possono usare le possibilit di gestione degli errori del 
   PHP. Definiamo una funzione per la gestione degli errori che registra le informazioni in un
   file (utilizzando un formato XML) e invia una email allo sviluppatore quando si verifica un
   errore critico nella logica.
   <example>
    <title>Usare la gestione degli errori in uno script</title>
    <programlisting role="php">
<![CDATA[
<?php
// sviluppiamo la nostra gestione degli errori
error_reporting(0);

// funzione per la gestione degli errori definita dall'utente
function userErrorHandler ($errno, $errmsg, $filename, $linenum, $vars) {
    // data e ora della annotazione dell'errore
    $dt = date("Y-m-d H:i:s (T)");

    // define an assoc array of error string
    // in reality the only entries we should
    // consider are 2,8,256,512 and 1024
    $errortype = array (
                1   =>  "Error",
                2   =>  "Warning",
                4   =>  "Parsing Error",
                8   =>  "Notice",
                16  =>  "Core Error",
                32  =>  "Core Warning",
                64  =>  "Compile Error",
                128 =>  "Compile Warning",
                256 =>  "User Error",
                512 =>  "User Warning",
                1024=>  "User Notice"
                );
    // set of errors for which a var trace will be saved
    $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;

    // save to the error log, and e-mail me if there is a critical user error
    error_log($err, 3, "/usr/local/php4/error.log");
    if ($errno == E_USER_ERROR)
        mail("phpdev@mydomain.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");

// undefined constant, generates a warning
$t = I_AM_NOT_DEFINED;

// define some "vectors"
$a = array(2,3,"foo");
$b = array(5.5, 4.3, -1.6);
$c = array (1,-3);

// generate a user error
$t1 = distance($c,$b)."\n";

// generate another user error
$t2 = distance($b,"i am not an array")."\n";

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

?>
]]>
    </programlisting>
   </example>
   Questo  un semplice esempio che mostra come usare le
   <link linkend="ref.errorfunc">funzioni per la gestione degli errori e per 
   loggare</link>.
  </para>

  <para>
   Vedere anche <function>error_reporting</function>,
   <function>error_log</function>,
   <function>set_error_handler</function>,
   <function>restore_error_handler</function>, 
   <function>trigger_error</function>,
   <function>user_error</function>
  </para>

 </chapter>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->