set-error-handler.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 80872147aa52367137bd3d168412f70cbe2ddf9c Maintainer: reghe Status: ready -->
<refentry xml:id="function.set-error-handler" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>set_error_handler</refname>
  <refpurpose>Configura una funzione di gestione dell'errore definita dall'utente</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>mixed</type><methodname>set_error_handler</methodname>
   <methodparam><type>callable</type><parameter>error_handler</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>error_types</parameter><initializer>E_ALL | E_STRICT</initializer></methodparam>
  </methodsynopsis>
  <para>
   Configura una funzione utente (<parameter>error_handler</parameter>) per 
   gestire gli errori in uno script.
  </para>
  <para>
   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
   <function>trigger_error</function>).
  </para>
  <para>
   È importante ricordare che il gestore degli errori standard di PHP viene completamente
   saltato per i tipi di errore specificati da <parameter>error_types</parameter> 
   salvo che la funzione di callback non restituisca &false;.
   La configurazione di <link linkend="ini.error-reporting">error_reporting</link> non avrà effetto e il proprio
   gestore di errore sarà richiamato senza considerarla - in ogni caso sarà possibile leggere
   il valore corrente di
   <function>error_reporting</function> ed agire
   di conseguenza. È di particolare rilevanza il fatto che questo valore sarà 0 se l'
   istruzione che causa l'errore viene preceduta dall'
   <link linkend="language.operators.errorcontrol">operatore di controllo
   errore @</link>.
  </para>
  <para>
   Notare anche che è vostra responsabilità richiamare <function>die</function>
   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.
  </para>
  <para>
   I seguenti tipi di errori non saranno gestiti dalla funzione definita dall'utente:
   <constant>E_ERROR</constant>, <constant>E_PARSE</constant>,
   <constant>E_CORE_ERROR</constant>, <constant>E_CORE_WARNING</constant>,
   <constant>E_COMPILE_ERROR</constant>,
   <constant>E_COMPILE_WARNING</constant> indipendentemente da dove sono stati sollevati, e
   buona parte degli <constant>E_STRICT</constant> sollevati nel file dove
   viene richiamata <function>set_error_handler</function>.
  </para>
  <para>
   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.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>error_handler</parameter></term>
     <listitem>
      <para>
       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.
      </para>
      <para>
       <methodsynopsis>
        <type>bool</type><methodname><replaceable>handler</replaceable></methodname>
        <methodparam><type>int</type><parameter>errno</parameter></methodparam>
        <methodparam><type>string</type><parameter>errstr</parameter></methodparam>
        <methodparam choice="opt"><type>string</type><parameter>errfile</parameter></methodparam>
        <methodparam choice="opt"><type>int</type><parameter>errline</parameter></methodparam>
        <methodparam choice="opt"><type>array</type><parameter>errcontext</parameter></methodparam>
       </methodsynopsis>
       <variablelist>
        <varlistentry>
         <term><parameter>errno</parameter></term>
         <listitem>
          <simpara>
           Il primo parametro, <parameter>errno</parameter>, contiene il
           livello dell'errore lanciato, come intero.
          </simpara>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>errstr</parameter></term>
         <listitem>
          <simpara>
           Il secondo parametro, <parameter>errstr</parameter>, contiene il
           messaggio di errore, come stringa.
          </simpara>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>errfile</parameter></term>
         <listitem>
          <simpara>
           Il terzo parametro opzionale, <parameter>errfile</parameter>,
           contiene il nome del file che ha generato l'errore, come stringa.
          </simpara>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>errline</parameter></term>
         <listitem>
          <simpara>
           Il quarto parametro è opzionale, <parameter>errline</parameter>,
           che contiene il numero di riga relativo al file che ha generato l'errore, come intero.
          </simpara>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>errcontext</parameter></term>
         <listitem>
          <simpara>
           Il quinto parametro è opzionale, <parameter>errcontext</parameter>,
           che è un array che punta alla tabella simboli al punto dove
           l'errore è stato generato. In altre parole, <parameter>errcontext</parameter>
           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.
          </simpara>
          <warning xmlns="http://docbook.org/ns/docbook">
           <simpara>
            Questo parametro è stato <emphasis>DEPRECATO</emphasis> da PHP 7.2.0.
            Fare affidamento su di esso è altamente scoraggiato.
           </simpara>
          </warning>
         </listitem>
        </varlistentry>
       </variablelist>
      </para>
      <para>
       Se la funzione ritorna &false; allora viene eseguito il normale gestore degli errori.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>error_types</parameter></term>
     <listitem>
      <para>
       Può essere usato per mascherare il triggering della
       funzione <parameter>error_handler</parameter> allo stesso modo
       dell'impostazione ini <link linkend="ini.error-reporting">error_reporting</link>
       che controlla quali errori mostrare. Senza questa maschera settata l'
       <parameter>error_handler</parameter> verrà richiamata per ogni errore
       senza tener conto dell'impostazione di <link
       linkend="ini.error-reporting">error_reporting</link>.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   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.
  </para>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>7.2.0</entry>
       <entry>
        <parameter>errcontext</parameter> è diventato deprecato. L'utilizzo di questo parametro ora genera un avviso <constant>E_DEPRECATED</constant>.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Gestione degli errori con <function>set_error_handler</function> e <function>trigger_error</function></title>
    <para>
     L'esempio sottostante mostra la gestione delle eccezioni interne
     attivando gli errori e gestendoli tramite una funzione definita dall'utente:
    </para>
    <programlisting role="php">
<![CDATA[
<?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;
    }

    // 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
?>
]]>
    </programlisting>
    &example.outputs.similar;
    <screen>
<![CDATA[
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 />
]]>
    </screen>
   </example>
  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><classname>ErrorException</classname></member>
    <member><function>error_reporting</function></member>
    <member><function>restore_error_handler</function></member>
    <member><function>trigger_error</function></member>
    <member><link linkend="errorfunc.constants">error level constants</link></member>
   </simplelist>
  </para>
 </refsect1>
</refentry>

<!-- 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:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->