ref.errorfunc: Implemented the new doc style, and rewording where appropriate.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@185011 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Philip Olson 2005-04-24 23:19:35 +00:00
parent dd998381ca
commit a0fb692b2c
8 changed files with 579 additions and 366 deletions

View file

@ -1,20 +1,27 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.14 $ -->
<!-- $Revision: 1.15 $ -->
<refentry id="function.debug-backtrace">
<refnamediv>
<refname>debug_backtrace</refname>
<refpurpose>Generates a backtrace</refpurpose>
</refnamediv>
<refsect1>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>array</type><methodname>debug_backtrace</methodname>
<void/>
</methodsynopsis>
<para>
<function>debug_backtrace</function> generates a PHP backtrace
and returns this information as an associative <type>array</type>. The
possible returned elements are listed in the following table:
<function>debug_backtrace</function> generates a PHP backtrace.
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns an associative <type>array</type>. The possible returned elements
are as follows:
</para>
<para>
<table>
@ -80,14 +87,13 @@
</tgroup>
</table>
</para>
<para>
The following is a simple example.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>
<function>debug_backtrace</function> example
</title>
<title><function>debug_backtrace</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
@ -109,7 +115,8 @@ include_once '/tmp/a.php';
]]>
</programlisting>
<para>
Results when executing <filename>/tmp/b.php</filename>:
Results similar to the following when executing
<filename>/tmp/b.php</filename>:
</para>
<screen>
<![CDATA[
@ -140,9 +147,15 @@ array(4) {
</screen>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
See also <function>trigger_error</function> and
<function>debug_print_backtrace</function>.
<simplelist>
<member><function>trigger_error</function></member>
<member><function>debug_print_backtrace</function></member>
</simplelist>
</para>
</refsect1>
</refentry>

View file

@ -1,12 +1,13 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.11 $ -->
<!-- $Revision: 1.12 $ -->
<!-- splitted from ./en/functions/errorfunc.xml, last change in rev 1.1 -->
<refentry id="function.error-log">
<refnamediv>
<refname>error_log</refname>
<refpurpose>Send an error message somewhere</refpurpose>
</refnamediv>
<refsect1>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>int</type><methodname>error_log</methodname>
@ -17,69 +18,104 @@
</methodsynopsis>
<para>
Sends an error message to the web server's error log, a
<acronym>TCP</acronym> port or to a file. The first parameter,
<parameter>message</parameter>, is the error message that should be
logged. The second parameter, <parameter>message_type</parameter> says
where the message should go:
<table>
<title><function>error_log</function> log types</title>
<tgroup cols="2">
<tbody>
<row>
<entry>0</entry>
<entry>
<parameter>message</parameter> is sent to PHP's system logger, using
the Operating System's system logging mechanism or a file, depending
on what the <link linkend="ini.error-log">error_log</link>
configuration directive is set to. This is the default option.
</entry>
</row>
<row>
<entry>1</entry>
<entry>
<parameter>message</parameter> is sent by email to the address in
the <parameter>destination</parameter> parameter. This is the only
message type where the fourth parameter,
<parameter>extra_headers</parameter> is used. This message type
uses the same internal function as <function>mail</function> does.
</entry>
</row>
<row>
<entry>2</entry>
<entry>
<parameter>message</parameter> is sent through the PHP debugging
connection. This option is only available if <link
linkend="configure.enable-debugger">remote debugging has
been enabled</link>. In this case, the
<parameter>destination</parameter> parameter specifies the host name
or IP address and optionally, port number, of the socket receiving
the debug information.
</entry>
</row>
<row>
<entry>3</entry>
<entry>
<parameter>message</parameter> is appended to the file
<parameter>destination</parameter>.
</entry>
</row>
</tbody>
</tgroup>
</table>
<acronym>TCP</acronym> port or to a file.
</para>
<note>
<simpara>
When explicitly specifying the <parameter>message_type</parameter> as
<literal>3</literal>, a newline is not automatically added to the end of
the <parameter>message</parameter> string.
</simpara>
</note>
<warning>
<para>
Remote debugging via TCP/IP is a PHP 3 feature that is
<emphasis>not</emphasis> available in PHP 4.
</para>
</warning>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>message</parameter></term>
<listitem>
<para>
The error message that should be logged.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>message_type</parameter></term>
<listitem>
<para>
Says where the error should go. The possible message types are as
follows:
</para>
<para>
<table>
<title><function>error_log</function> log types</title>
<tgroup cols="2">
<tbody>
<row>
<entry>0</entry>
<entry>
<parameter>message</parameter> is sent to PHP's system logger, using
the Operating System's system logging mechanism or a file, depending
on what the <link linkend="ini.error-log">error_log</link>
configuration directive is set to. This is the default option.
</entry>
</row>
<row>
<entry>1</entry>
<entry>
<parameter>message</parameter> is sent by email to the address in
the <parameter>destination</parameter> parameter. This is the only
message type where the fourth parameter,
<parameter>extra_headers</parameter> is used.
</entry>
</row>
<row>
<entry>2</entry>
<entry>
<parameter>message</parameter> is sent through the PHP debugging
connection. This option is only available if <link
linkend="configure.enable-debugger">remote debugging has
been enabled</link>. In this case, the
<parameter>destination</parameter> parameter specifies the host name
or IP address and optionally, port number, of the socket receiving
the debug information. This option is only available in PHP 3.
</entry>
</row>
<row>
<entry>3</entry>
<entry>
<parameter>message</parameter> is appended to the file
<parameter>destination</parameter>. A newline is not automatically
added to the end of the <parameter>message</parameter> string.
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>destination</parameter></term>
<listitem>
<para>
The destination. Its meaning depends on the
<parameter>message</parameter> parameter as described above.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>extra_headers</parameter></term>
<listitem>
<para>
The extra headers. It's used when the <parameter>message</parameter>
parameter is set to <literal>1</literal>.
This message type uses the same internal function as
<function>mail</function> does.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example role="php">
<title><function>error_log</function> examples</title>

View file

@ -1,12 +1,13 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.13 $ -->
<!-- $Revision: 1.14 $ -->
<!-- splitted from ./en/functions/errorfunc.xml, last change in rev 1.1 -->
<refentry id="function.error-reporting">
<refnamediv>
<refname>error_reporting</refname>
<refpurpose>Sets which PHP errors are reported</refpurpose>
</refnamediv>
<refsect1>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>int</type><methodname>error_reporting</methodname>
@ -19,16 +20,136 @@
this function sets that level for the duration (runtime) of
your script.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<function>error_reporting</function> sets PHP's error reporting level,
and returns the old level. The <parameter>level</parameter> parameter
takes on either a bitmask, or named constants. Using named constants
is strongly encouraged to ensure compatibility for future versions. As
error levels are added, the range of integers increases, so older
integer-based error levels will not always behave as expected.
<variablelist>
<varlistentry>
<term><parameter>level</parameter></term>
<listitem>
<para>
The new <link linkend="ini.error-reporting">error_reporting</link>
level. It takes on either a bitmask, or named constants. Using named
constants is strongly encouraged to ensure compatibility for future
versions. As error levels are added, the range of integers increases,
so older integer-based error levels will not always behave as expected.
</para>
<para>
The available error level constants are listed below. The actual
meanings of these error levels are described in the
<link linkend="errorfunc.constants">predefined constants</link>.
<table>
<title><function>error_reporting</function> level constants and bit values</title>
<tgroup cols="2">
<thead>
<row>
<entry>value</entry>
<entry>constant</entry>
</row>
</thead>
<tbody>
<row>
<entry>1</entry>
<entry>
<link linkend="e-error">E_ERROR</link>
</entry>
</row>
<row>
<entry>2</entry>
<entry>
<link linkend="e-warning">E_WARNING</link>
</entry>
</row>
<row>
<entry>4</entry>
<entry>
<link linkend="e-parse">E_PARSE</link>
</entry>
</row>
<row>
<entry>8</entry>
<entry>
<link linkend="e-notice">E_NOTICE</link>
</entry>
</row>
<row>
<entry>16</entry>
<entry>
<link linkend="e-core-error">E_CORE_ERROR</link>
</entry>
</row>
<row>
<entry>32</entry>
<entry>
<link linkend="e-core-warning">E_CORE_WARNING</link>
</entry>
</row>
<row>
<entry>64</entry>
<entry>
<link linkend="e-compile-error">E_COMPILE_ERROR</link>
</entry>
</row>
<row>
<entry>128</entry>
<entry>
<link linkend="e-compile-warning">E_COMPILE_WARNING</link>
</entry>
</row>
<row>
<entry>256</entry>
<entry>
<link linkend="e-user-error">E_USER_ERROR</link>
</entry>
</row>
<row>
<entry>512</entry>
<entry>
<link linkend="e-user-warning">E_USER_WARNING</link>
</entry>
</row>
<row>
<entry>1024</entry>
<entry>
<link linkend="e-user-error">E_USER_NOTICE</link>
</entry>
</row>
<row>
<entry>2047</entry>
<entry>
<link linkend="e-all">E_ALL</link>
</entry>
</row>
<row>
<entry>2048</entry>
<entry>
<link linkend="e-strict">E_STRICT</link>
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<example role="php">
Returns the old <link linkend="ini.error-reporting">error_reporting</link>
level.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>error_reporting</function> examples</title>
<programlisting role="php">
<![CDATA[
@ -59,102 +180,10 @@ ini_set('error_reporting', E_ALL);
</programlisting>
</example>
</para>
<para>
The available error level constants are listed below. The actual
meanings of these error levels are described in the
<link linkend="errorfunc.constants">predefined constants</link>.
<table>
<title><function>error_reporting</function> level constants and bit values</title>
<tgroup cols="2">
<thead>
<row>
<entry>value</entry>
<entry>constant</entry>
</row>
</thead>
<tbody>
<row>
<entry>1</entry>
<entry>
<link linkend="e-error">E_ERROR</link>
</entry>
</row>
<row>
<entry>2</entry>
<entry>
<link linkend="e-warning">E_WARNING</link>
</entry>
</row>
<row>
<entry>4</entry>
<entry>
<link linkend="e-parse">E_PARSE</link>
</entry>
</row>
<row>
<entry>8</entry>
<entry>
<link linkend="e-notice">E_NOTICE</link>
</entry>
</row>
<row>
<entry>16</entry>
<entry>
<link linkend="e-core-error">E_CORE_ERROR</link>
</entry>
</row>
<row>
<entry>32</entry>
<entry>
<link linkend="e-core-warning">E_CORE_WARNING</link>
</entry>
</row>
<row>
<entry>64</entry>
<entry>
<link linkend="e-compile-error">E_COMPILE_ERROR</link>
</entry>
</row>
<row>
<entry>128</entry>
<entry>
<link linkend="e-compile-warning">E_COMPILE_WARNING</link>
</entry>
</row>
<row>
<entry>256</entry>
<entry>
<link linkend="e-user-error">E_USER_ERROR</link>
</entry>
</row>
<row>
<entry>512</entry>
<entry>
<link linkend="e-user-warning">E_USER_WARNING</link>
</entry>
</row>
<row>
<entry>1024</entry>
<entry>
<link linkend="e-user-error">E_USER_NOTICE</link>
</entry>
</row>
<row>
<entry>2047</entry>
<entry>
<link linkend="e-all">E_ALL</link>
</entry>
</row>
<row>
<entry>2048</entry>
<entry>
<link linkend="e-strict">E_STRICT</link>
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
</refsect1>
<refsect1 role="notes">
&reftitle.notes;
<warning>
<simpara>
With PHP &gt; 5.0.0 <constant>E_STRICT</constant> with value 2048 is
@ -166,9 +195,15 @@ ini_set('error_reporting', E_ALL);
to include <constant>E_STRICT</constant> errors.
</simpara>
</warning>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
See also the <link linkend="ini.display-errors">display_errors</link>
directive and <function>ini_set</function>.
<simplelist>
<member>The <link linkend="ini.display-errors">display_errors</link> directive</member>
<member><function>ini_set</function></member>
</simplelist>
</para>
</refsect1>
</refentry>

View file

@ -1,14 +1,13 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.11 $ -->
<!-- $Revision: 1.12 $ -->
<!-- splitted from ./en/functions/errorfunc.xml, last change in rev 1.1 -->
<refentry id="function.restore-error-handler">
<refnamediv>
<refname>restore_error_handler</refname>
<refpurpose>
Restores the previous error handler function
</refpurpose>
<refpurpose>Restores the previous error handler function</refpurpose>
</refnamediv>
<refsect1>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>bool</type><methodname>restore_error_handler</methodname>
@ -17,27 +16,26 @@
<para>
Used after changing the error handler function using
<function>set_error_handler</function>, to revert to the previous error
handler (which could be the built-in or a user defined function). This
function always returns &true;.
handler (which could be the built-in or a user defined function).
</para>
<note>
<para>
Calling <function>restore_error_handler</function> from the
<literal>error_handler</literal> function is ignored.
</para>
</note>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
See also <function>error_reporting</function>,
<function>set_error_handler</function>,
<function>restore_exception_handler</function>,
<function>trigger_error</function>.
This function always returns &true;
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>
<title><function>restore_error_handler</function> example</title>
<para>
Decide if <function>unserialize</function> caused an error, then
restore the original error handler.
</title>
</para>
<programlisting role="php">
<![CDATA[
<?php
@ -62,6 +60,28 @@ Invalid serialized value.
</example>
</para>
</refsect1>
<refsect1 role="notes">
&reftitle.notes;
<note>
<para>
Calling <function>restore_error_handler</function> from the
<literal>error_handler</literal> function is ignored.
</para>
</note>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>error_reporting</function></member>
<member><function>set_error_handler</function></member>
<member><function>restore_exception_handler</function></member>
<member><function>trigger_error</function></member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file

View file

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.4 $ -->
<!-- $Revision: 1.5 $ -->
<refentry id="function.restore-exception-handler">
<refnamediv>
<refname>restore_exception_handler</refname>
@ -7,7 +7,8 @@
Restores the previously defined exception handler function
</refpurpose>
</refnamediv>
<refsect1>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>bool</type><methodname>restore_exception_handler</methodname>
@ -17,14 +18,26 @@
Used after changing the exception handler function using
<function>set_exception_handler</function>, to revert to the previous
exception handler (which could be the built-in or a user defined
function). This function always returns &true;.
function).
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
See also
<function>set_exception_handler</function>,
<function>set_error_handler</function>,
<function>restore_error_handler</function>
<function>error_reporting</function>
This function always returns &true;
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>set_exception_handler</function></member>
<member><function>set_error_handler</function></member>
<member><function>restore_error_handler</function></member>
<member><function>error_reporting</function></member>
</simplelist>
</para>
</refsect1>
</refentry>

View file

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.29 $ -->
<!-- $Revision: 1.30 $ -->
<!-- splitted from ./en/functions/errorfunc.xml, last change in rev 1.1 -->
<refentry id="function.set-error-handler">
<refnamediv>
@ -8,7 +8,8 @@
Sets a user-defined error handler function
</refpurpose>
</refnamediv>
<refsect1>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>mixed</type><methodname>set_error_handler</methodname>
@ -17,10 +18,7 @@
</methodsynopsis>
<para>
Sets a user function (<parameter>error_handler</parameter>) to handle
errors in a script. Returns a string containing the previously defined
error handler (if any), or &false; on error. If the previous handler
was a class method, this function will return an indexed array with
the class and the method name.
errors in a script.
</para>
<para>
This function can be used for defining your own way of handling errors
@ -30,106 +28,190 @@
<function>trigger_error</function>).
</para>
<para>
The second parameter <parameter>error_types</parameter> was introduced in
PHP 5 and can be used to mask the triggering of the
<parameter>error_handler</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>error_handler</parameter> will be called for every error
regardless to the setting of the <link
linkend="ini.error-reporting">error_reporting</link> setting.
It is important to remember that the standard PHP error handler is completely
bypassed. <function>error_reporting</function> settings will have no effect
and your error handler will be called regardless - however you are still
able to read the current value of <link linkend="ini.error-reporting">error_reporting</link> and
act appropriately. Of particular note is that this value will be 0 if the
statement that caused the error was prepended by the
<link linkend="language.operators.errorcontrol">@ error-control
operator</link>.
</para>
<para>
The user function needs to accept two parameters: the error code, and a
string describing the error. From PHP 4.0.2, three optional
parameters are supplied: the filename in which the error occurred, the
line number in which the error occurred, and the context in which the
error occurred (an array that points to the active symbol table at the
point the error occurred). The function can be shown as:
<methodsynopsis>
<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>
Also note that it is your responsibility to <function>die</function> if
necessary. 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>, 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>errno</parameter></term>
<term><parameter>error_handler</parameter></term>
<listitem>
<simpara>
The first parameter, <parameter>errno</parameter>, contains the
level of the error raised, as an integer.
</simpara>
<para>
The user function needs to accept two parameters: the error code, and a
string describing the error. Then there are three optional parameters
that may be supplied: the filename in which the error occurred, the
line number in which the error occurred, and the context in which the
error occurred (an array that points to the active symbol table at the
point the error occurred). The function can be shown as:
</para>
<para>
<methodsynopsis>
<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>, contains 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>, contains the
error message, as a string.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>errfile</parameter></term>
<listitem>
<simpara>
The third parameter is optional, <parameter>errfile</parameter>,
which contains the filename that the error was raised in, as a string.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>errline</parameter></term>
<listitem>
<simpara>
The fourth parameter is optional, <parameter>errline</parameter>,
which contains the line number the error was raised at, as an integer.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>errcontext</parameter></term>
<listitem>
<simpara>
The fifth parameter is optional, <parameter>errcontext</parameter>,
which is 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.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>errstr</parameter></term>
<term><parameter>error_types</parameter></term>
<listitem>
<simpara>
The second parameter, <parameter>errstr</parameter>, contains the
error message, as a string.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>errfile</parameter></term>
<listitem>
<simpara>
The third parameter is optional, <parameter>errfile</parameter>,
which contains the filename that the error was raised in, as a string.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>errline</parameter></term>
<listitem>
<simpara>
The fourth parameter is optional, <parameter>errline</parameter>,
which contains the line number the error was raised at, as an integer.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>errcontext</parameter></term>
<listitem>
<simpara>
The fifth parameter is optional, <parameter>errcontext</parameter>,
which is 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.
</simpara>
<para>
Can be used to mask the triggering of the
<parameter>error_handler</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>error_handler</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>
<note>
<simpara>
Instead of a function name, an array containing an object reference and
a method name can also be supplied. (Since PHP 4.3.0)
</simpara>
</note>
<note>
<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>, and
most of <constant>E_STRICT</constant> raised in the file where
<function>set_error_handler</function> is called.
</para>
</note>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns a string containing the previously defined
error handler (if any), or &false; on error. If the previous handler
was a class method, this function will return an indexed array with
the class and the method name.
</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>5.0.0</entry>
<entry>
The <parameter>error_types</parameter> parameter was introduced.
</entry>
</row>
<row>
<entry>4.3.0</entry>
<entry>
Instead of a function name, an array containing an object reference
and a method name can also be supplied as the
<parameter>error_handler</parameter>.
</entry>
</row>
<row>
<entry>4.0.2</entry>
<entry>
Three optional parameters for the <parameter>error_handler</parameter>
user function was introduced. These are the filename, the line number,
and the context.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
The example below shows the handling of internal exceptions by
triggering errors and handling them with a user defined function:
<example>
<title>
Error handling with <function>set_error_handler</function> and
<function>trigger_error</function>
</title>
<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
@ -204,7 +286,7 @@ $d = scale_by_log($a, -2.5);
?>
]]>
</programlisting>
&example.outputs;
&example.outputs.similar;
<screen>
<![CDATA[
vector a
@ -242,39 +324,18 @@ Aborting...<br />
</screen>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
It is important to remember that the standard PHP error handler is completely
bypassed. <function>error_reporting</function> settings will have no effect
and your error handler will be called regardless - however you are still
able to read the current value of <link linkend="ini.error-reporting">error_reporting</link> and
act appropriately. Of particular note is that this value will be 0 if the
statement that caused the error was prepended by the
<link linkend="language.operators.errorcontrol">@ error-control
operator</link>.
</para>
<para>
Also note that it is your responsibility to <function>die</function> if
necessary. If the error-handler function returns, script execution
will continue with the next statement after the one that caused an error.
</para>
<note>
<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>
</note>
<note>
<para>
The second parameter <parameter>error_types</parameter> was introduced
in PHP 5.
</para>
</note>
<para>
See also <function>error_reporting</function>,
<function>restore_error_handler</function>,
<function>trigger_error</function>,
<link linkend="errorfunc.constants">error level constants</link>,
&listendand; &seealso.callback;.
<simplelist>
<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>
<member>&seealso.callback;</member>
</simplelist>
</para>
</refsect1>
</refentry>

View file

@ -1,14 +1,13 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.11 $ -->
<!-- $Revision: 1.12 $ -->
<!-- splitted from ./en/functions/errorfunc.xml, last change in rev 1.1 -->
<refentry id="function.trigger-error">
<refnamediv>
<refname>trigger_error</refname>
<refpurpose>
Generates a user-level error/warning/notice message
</refpurpose>
<refpurpose>Generates a user-level error/warning/notice message</refpurpose>
</refnamediv>
<refsect1>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>bool</type><methodname>trigger_error</methodname>
@ -19,18 +18,57 @@
Used to trigger a user error condition, it can be used by in conjunction
with the built-in error handler, or with a user defined function that has
been set as the new error handler
(<function>set_error_handler</function>). It only works with the E_USER
family of constants, and will default to <constant>E_USER_NOTICE</constant>.
(<function>set_error_handler</function>).
</para>
<para>
This function is useful when you need to generate a particular response to
an exception at runtime.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>error_msg</parameter></term>
<listitem>
<para>
The designated error message for this error. It's limited to 1024
characters in length. Any additional characters beyond 1024 will be
truncated.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>error_type</parameter></term>
<listitem>
<para>
The designated error type for this error. It only works with the E_USER
family of constants, and will default to <constant>E_USER_NOTICE</constant>.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
This function returns &false; if wrong <parameter>error_type</parameter> is
specified, &true; otherwise.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
This function is useful when
you need to generate a particular response to an exception at runtime.
For example:
<informalexample>
<example>
<title><function>trigger_error</function> example</title>
<para>
See <function>set_error_handler</function> for a more extensive example.
</para>
<programlisting role="php">
<![CDATA[
<?php
@ -40,24 +78,19 @@ if (assert($divisor == 0)) {
?>
]]>
</programlisting>
</informalexample>
<note>
<para>
See <function>set_error_handler</function> for a more extensive example.
</para>
</note>
<note>
<para>
<parameter>error_msg</parameter> is limited to 1024 characters in length.
Any additional characters beyond 1024 will be truncated.
</para>
</note>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
See also <function>error_reporting</function>,
<function>set_error_handler</function>,
<function>restore_error_handler</function>, and
<link linkend="errorfunc.constants">error level constants</link>.
<simplelist>
<member><function>error_reporting</function></member>
<member><function>set_error_handler</function></member>
<member><function>restore_error_handler</function></member>
<member>The <link linkend="errorfunc.constants">error level constants</link></member>
</simplelist>
</para>
</refsect1>
</refentry>

View file

@ -1,15 +1,17 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.5 $ -->
<!-- $Revision: 1.6 $ -->
<!-- splitted from ./en/functions/errorfunc.xml, last change in rev 1.1 -->
<refentry id="function.user-error">
<refnamediv>
<refname>user_error</refname>
<refpurpose>Alias of <function>trigger_error</function></refpurpose>
</refnamediv>
<refsect1>
<refsect1 role="description">
&reftitle.description;
<para>
This function is an alias of <function>trigger_error</function>.
&info.function.alias;
<function>trigger_error</function>.
</para>
</refsect1>
</refentry>