<?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 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

?>

]]>

</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

-->