mirror of
https://github.com/php/doc-en.git
synced 2026-03-24 07:42:10 +01:00
21ce7d7f4f
For the method of the class as an error handler, the `set_error_handler` function may return a `callable`: a) a string b) a Closure c) an indexed array (with the name of the class or an instance of the class in the first element, and the name of the method in the second one) However, it is not limited to just "an indexed array with the class and method name". I suggest removing the mention of the array as a return value, otherwise we will have to list every possible type of callable value :)
372 lines
12 KiB
XML
372 lines
12 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!-- $Revision$ -->
|
|
<refentry xml:id="function.set-error-handler" xmlns="http://docbook.org/ns/docbook">
|
|
<refnamediv>
|
|
<refname>set_error_handler</refname>
|
|
<refpurpose>Sets a user-defined error handler function</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsect1 role="description">
|
|
&reftitle.description;
|
|
<methodsynopsis>
|
|
<type class="union"><type>callable</type><type>null</type></type><methodname>set_error_handler</methodname>
|
|
<methodparam><type class="union"><type>callable</type><type>null</type></type><parameter>callback</parameter></methodparam>
|
|
<methodparam choice="opt"><type>int</type><parameter>error_levels</parameter><initializer><constant>E_ALL</constant></initializer></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
Sets a user function (<parameter>callback</parameter>) to handle
|
|
errors in a script.
|
|
</para>
|
|
<para>
|
|
This function can be used to define custom error handlers during runtime,
|
|
for example in applications which need to do file/data cleanup when a critical
|
|
error happens, or when triggering an error in response to certain conditions
|
|
(using <function>trigger_error</function>).
|
|
</para>
|
|
<para>
|
|
It is important to remember that the standard PHP error handler is completely
|
|
bypassed for the error types specified by <parameter>error_levels</parameter>
|
|
unless the callback function returns &false;.
|
|
<function>error_reporting</function> settings will have no effect and the
|
|
error handler will be called regardless - however, it's still possible to
|
|
read the current value of
|
|
<link linkend="ini.error-reporting">error_reporting</link> and act
|
|
appropriately.
|
|
</para>
|
|
<para>
|
|
Also note that it is the handler's responsibility to stop the
|
|
script's execution if necessary by calling <function>exit</function>. If the error-handler
|
|
function returns, script execution will continue with the next statement
|
|
after the one that caused an error.
|
|
</para>
|
|
<para>
|
|
The following error types cannot be handled with a user defined
|
|
function: <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> independent of where they were raised, and
|
|
most of <constant>E_STRICT</constant> raised in the file where
|
|
<function>set_error_handler</function> is called.
|
|
</para>
|
|
<para>
|
|
If errors occur before the script is executed (e.g. on file uploads) the
|
|
custom error handler cannot be called since it is not registered at that
|
|
time.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="parameters">
|
|
&reftitle.parameters;
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>callback</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
If &null; is passed, the handler is reset to its default state.
|
|
Otherwise, the handler is a callback with the following signature:
|
|
</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>
|
|
The first parameter, <parameter>errno</parameter>, will be passed the
|
|
level of the error raised, as an integer.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>errstr</parameter></term>
|
|
<listitem>
|
|
<simpara>
|
|
The second parameter, <parameter>errstr</parameter>, will be passed the
|
|
error message, as a string.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>errfile</parameter></term>
|
|
<listitem>
|
|
<simpara>
|
|
If the callback accepts a third parameter, <parameter>errfile</parameter>,
|
|
it will be passed the filename that the error was raised in, as a string.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>errline</parameter></term>
|
|
<listitem>
|
|
<simpara>
|
|
If the callback accepts a fourth parameter, <parameter>errline</parameter>,
|
|
it will be passed the line number where the error was raised, as an integer.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>errcontext</parameter></term>
|
|
<listitem>
|
|
<simpara>
|
|
If the callback accepts a fifth parameter, <parameter>errcontext</parameter>,
|
|
it will be passed an array that points to the active symbol table at the
|
|
point the error occurred. In other words, <parameter>errcontext</parameter>
|
|
will contain an array of every variable that existed in the scope the
|
|
error was triggered in.
|
|
User error handlers must not modify the error context.
|
|
</simpara>
|
|
<warning xmlns="http://docbook.org/ns/docbook">
|
|
<simpara>
|
|
This parameter has been <emphasis>DEPRECATED</emphasis> as of PHP 7.2.0,
|
|
and <emphasis>REMOVED</emphasis> as of PHP 8.0.0. If the function defines
|
|
this parameter without a default, an error of "too few arguments" will be
|
|
raised when it is called.
|
|
</simpara>
|
|
</warning>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
<para>
|
|
If the function returns &false; then the normal error handler continues.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>error_levels</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Can be used to mask the triggering of the
|
|
<parameter>callback</parameter> function just like the <link linkend="ini.error-reporting">error_reporting</link> ini setting
|
|
controls which errors are shown. Without this mask set the
|
|
<parameter>callback</parameter> will be called for every error
|
|
regardless to the setting of the <link linkend="ini.error-reporting">error_reporting</link> setting.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="returnvalues">
|
|
&reftitle.returnvalues;
|
|
<para>
|
|
Returns the previously defined error handler (if any) as a <type>callable</type>.
|
|
If the built-in error handler is used &null; is returned.
|
|
</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>8.0.0</entry>
|
|
<entry>
|
|
<parameter>errcontext</parameter> was removed, and will no longer be passed to user callbacks.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>7.2.0</entry>
|
|
<entry>
|
|
<parameter>errcontext</parameter> became deprecated. Usage of this parameter now emits an <constant>E_DEPRECATED</constant> notice.
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="examples">
|
|
&reftitle.examples;
|
|
<para>
|
|
<example>
|
|
<title>Error handling with <function>set_error_handler</function> and <function>trigger_error</function></title>
|
|
<para>
|
|
The example below shows the handling of internal exceptions by
|
|
triggering errors and handling them with a user defined function:
|
|
</para>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
// error handler function
|
|
function myErrorHandler($errno, $errstr, $errfile, $errline)
|
|
{
|
|
if (!(error_reporting() & $errno)) {
|
|
// This error code is not included in error_reporting, so let it fall
|
|
// through to the standard PHP error handler
|
|
return false;
|
|
}
|
|
|
|
// $errstr may need to be escaped:
|
|
$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;
|
|
}
|
|
|
|
/* Don't execute PHP internal error handler */
|
|
return true;
|
|
}
|
|
|
|
// function to test the error handling
|
|
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;
|
|
}
|
|
|
|
// set to the user defined error handler
|
|
$old_error_handler = set_error_handler("myErrorHandler");
|
|
|
|
// trigger some errors, first define a mixed array with a non-numeric item
|
|
echo "vector a\n";
|
|
$a = array(2, 3, "foo", 5.5, 43.3, 21.11);
|
|
print_r($a);
|
|
|
|
// now generate second 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);
|
|
|
|
// this is trouble, we pass a string instead of an 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
|
|
|
|
// this is a critical error, log of zero or negative number is 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); // Never reached
|
|
?>
|
|
]]>
|
|
</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>get_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
|
|
-->
|