WS, preparation for the new doc style

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@184982 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Philip Olson 2005-04-24 15:36:00 +00:00
parent 5260e42dd9
commit 267173c6c0
8 changed files with 671 additions and 675 deletions

View file

@ -1,101 +1,99 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.13 $ -->
<refentry id="function.debug-backtrace">
<refnamediv>
<refname>debug_backtrace</refname>
<refpurpose>
Generates a backtrace
</refpurpose>
</refnamediv>
<refsect1>
&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:
</para>
<para>
<table>
<title>Possible returned elements from <function>debug_backtrace</function></title>
<tgroup cols="3">
<thead>
<row>
<entry>Name</entry>
<entry>Type</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>function</entry>
<entry><type>string</type></entry>
<entry>
The current function name. See also
<link linkend="language.constants.predefined">__FUNCTION__</link>.
</entry>
</row>
<row>
<entry>line</entry>
<entry><type>integer</type></entry>
<entry>
The current line number. See also
<link linkend="language.constants.predefined">__LINE__</link>.
</entry>
</row>
<row>
<entry>file</entry>
<entry><type>string</type></entry>
<entry>
The current file name. See also
<link linkend="language.constants.predefined">__FILE__</link>.
</entry>
</row>
<row>
<entry>class</entry>
<entry><type>string</type></entry>
<entry>
The current <link linkend="language.oop">class</link> name. See also
<link linkend="language.constants.predefined">__CLASS__</link>
</entry>
</row>
<row>
<entry>type</entry>
<entry><type>string</type></entry>
<entry>
The current call type. If a method call, "->" is returned. If a static
method call, "::" is returned. If a function call, nothing is returned.
</entry>
</row>
<row>
<entry>args</entry>
<entry><type>array</type></entry>
<entry>
If inside a function, this lists the functions arguments. If
inside an included file, this lists the included file name(s).
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<para>
The following is a simple example.
</para>
<para>
<example>
<title>
<function>debug_backtrace</function> example
</title>
<programlisting role="php">
<!-- $Revision: 1.14 $ -->
<refentry id="function.debug-backtrace">
<refnamediv>
<refname>debug_backtrace</refname>
<refpurpose>Generates a backtrace</refpurpose>
</refnamediv>
<refsect1>
&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:
</para>
<para>
<table>
<title>Possible returned elements from <function>debug_backtrace</function></title>
<tgroup cols="3">
<thead>
<row>
<entry>Name</entry>
<entry>Type</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>function</entry>
<entry><type>string</type></entry>
<entry>
The current function name. See also
<link linkend="language.constants.predefined">__FUNCTION__</link>.
</entry>
</row>
<row>
<entry>line</entry>
<entry><type>integer</type></entry>
<entry>
The current line number. See also
<link linkend="language.constants.predefined">__LINE__</link>.
</entry>
</row>
<row>
<entry>file</entry>
<entry><type>string</type></entry>
<entry>
The current file name. See also
<link linkend="language.constants.predefined">__FILE__</link>.
</entry>
</row>
<row>
<entry>class</entry>
<entry><type>string</type></entry>
<entry>
The current <link linkend="language.oop">class</link> name. See also
<link linkend="language.constants.predefined">__CLASS__</link>
</entry>
</row>
<row>
<entry>type</entry>
<entry><type>string</type></entry>
<entry>
The current call type. If a method call, "->" is returned. If a static
method call, "::" is returned. If a function call, nothing is returned.
</entry>
</row>
<row>
<entry>args</entry>
<entry><type>array</type></entry>
<entry>
If inside a function, this lists the functions arguments. If
inside an included file, this lists the included file name(s).
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<para>
The following is a simple example.
</para>
<para>
<example>
<title>
<function>debug_backtrace</function> example
</title>
<programlisting role="php">
<![CDATA[
<?php
// filename: a.php
function a_test($str)
function a_test($str)
{
echo "\nHi: $str";
var_dump(debug_backtrace());
@ -109,16 +107,16 @@ a_test('friend');
include_once '/tmp/a.php';
?>
]]>
</programlisting>
<para>
Results when executing <filename>/tmp/b.php</filename>:
</para>
<screen>
</programlisting>
<para>
Results when executing <filename>/tmp/b.php</filename>:
</para>
<screen>
<![CDATA[
Hi: friend
array(2) {
[0]=>
array(4) {
[0]=>
array(4) {
["file"] => string(10) "/tmp/a.php"
["line"] => int(10)
["function"] => string(6) "a_test"
@ -126,12 +124,12 @@ array(2) {
array(1) {
[0] => &string(6) "friend"
}
}
[1]=>
array(4) {
}
[1]=>
array(4) {
["file"] => string(10) "/tmp/b.php"
["line"] => int(2)
["args"] =>
["args"] =>
array(1) {
[0] => string(10) "/tmp/a.php"
}
@ -139,15 +137,15 @@ array(2) {
}
}
]]>
</screen>
</example>
</para>
<para>
See also <function>trigger_error</function> and
<function>debug_print_backtrace</function>.
</para>
</refsect1>
</refentry>
</screen>
</example>
</para>
<para>
See also <function>trigger_error</function> and
<function>debug_print_backtrace</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

View file

@ -1,89 +1,89 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.10 $ -->
<!-- $Revision: 1.11 $ -->
<!-- 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>
&reftitle.description;
<methodsynopsis>
<type>int</type><methodname>error_log</methodname>
<methodparam><type>string</type><parameter>message</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>message_type</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>destination</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>extra_headers</parameter></methodparam>
</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>
</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>
<para>
<example role="php">
<title><function>error_log</function> examples</title>
<programlisting role="php">
<refentry id="function.error-log">
<refnamediv>
<refname>error_log</refname>
<refpurpose>Send an error message somewhere</refpurpose>
</refnamediv>
<refsect1>
&reftitle.description;
<methodsynopsis>
<type>int</type><methodname>error_log</methodname>
<methodparam><type>string</type><parameter>message</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>message_type</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>destination</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>extra_headers</parameter></methodparam>
</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>
</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>
<para>
<example role="php">
<title><function>error_log</function> examples</title>
<programlisting role="php">
<![CDATA[
<?php
// Send notification through the server log if we can not
@ -104,11 +104,11 @@ error_log("You messed up!", 2, "loghost");
error_log("You messed up!", 3, "/var/tmp/my-errors.log");
?>
]]>
</programlisting>
</example>
</para>
</refsect1>
</refentry>
</programlisting>
</example>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

View file

@ -1,36 +1,36 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.12 $ -->
<!-- $Revision: 1.13 $ -->
<!-- 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>
&reftitle.description;
<methodsynopsis>
<type>int</type><methodname>error_reporting</methodname>
<methodparam choice="opt"><type>int</type><parameter>level</parameter></methodparam>
</methodsynopsis>
<para>
The <function>error_reporting</function> function sets the
<link linkend="ini.error-reporting">error_reporting</link>
directive at runtime. PHP has many levels of errors, using
this function sets that level for the duration (runtime) of
your script.
</para>
<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.
</para>
<para>
<example role="php">
<title><function>error_reporting</function> examples</title>
<programlisting role="php">
<refentry id="function.error-reporting">
<refnamediv>
<refname>error_reporting</refname>
<refpurpose>Sets which PHP errors are reported</refpurpose>
</refnamediv>
<refsect1>
&reftitle.description;
<methodsynopsis>
<type>int</type><methodname>error_reporting</methodname>
<methodparam choice="opt"><type>int</type><parameter>level</parameter></methodparam>
</methodsynopsis>
<para>
The <function>error_reporting</function> function sets the
<link linkend="ini.error-reporting">error_reporting</link>
directive at runtime. PHP has many levels of errors, using
this function sets that level for the duration (runtime) of
your script.
</para>
<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.
</para>
<para>
<example role="php">
<title><function>error_reporting</function> examples</title>
<programlisting role="php">
<![CDATA[
<?php
@ -40,7 +40,7 @@ error_reporting(0);
// Report simple running errors
error_reporting(E_ERROR | E_WARNING | E_PARSE);
// Reporting E_NOTICE can be good too (to report uninitialized
// Reporting E_NOTICE can be good too (to report uninitialized
// variables or catch variable name misspellings ...)
error_reporting(E_ERROR | E_WARNING | E_PARSE | E_NOTICE);
@ -56,122 +56,122 @@ 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>
<warning>
<simpara>
With PHP &gt; 5.0.0 <constant>E_STRICT</constant> with value 2048 is
available. <constant>E_ALL</constant> does <emphasis>NOT</emphasis>
include error level <constant>E_STRICT</constant>.
Most of <constant>E_STRICT</constant> errors are evaluated at the
compile time thus such errors are not reported in the file where
<link linkend="ini.error-reporting">error_reporting</link> is enhanced
to include <constant>E_STRICT</constant> errors.
</simpara>
</warning>
<para>
See also the <link linkend="ini.display-errors">display_errors</link>
directive and <function>ini_set</function>.
</para>
</refsect1>
</refentry>
</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>
<warning>
<simpara>
With PHP &gt; 5.0.0 <constant>E_STRICT</constant> with value 2048 is
available. <constant>E_ALL</constant> does <emphasis>NOT</emphasis>
include error level <constant>E_STRICT</constant>.
Most of <constant>E_STRICT</constant> errors are evaluated at the
compile time thus such errors are not reported in the file where
<link linkend="ini.error-reporting">error_reporting</link> is enhanced
to include <constant>E_STRICT</constant> errors.
</simpara>
</warning>
<para>
See also the <link linkend="ini.display-errors">display_errors</link>
directive and <function>ini_set</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

View file

@ -1,44 +1,44 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.10 $ -->
<!-- $Revision: 1.11 $ -->
<!-- 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>
</refnamediv>
<refsect1>
&reftitle.description;
<methodsynopsis>
<type>bool</type><methodname>restore_error_handler</methodname>
<void/>
</methodsynopsis>
<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;.
</para>
<note>
<para>
Calling <function>restore_error_handler</function> from the
<literal>error_handler</literal> function is ignored.
</para>
</note>
<para>
See also <function>error_reporting</function>,
<function>set_error_handler</function>,
<function>restore_exception_handler</function>,
<function>trigger_error</function>.
</para>
<para>
<example>
<title>
Decide if <function>unserialize</function> caused an error, then
restore the original error handler.
</title>
<programlisting role="php">
<refentry id="function.restore-error-handler">
<refnamediv>
<refname>restore_error_handler</refname>
<refpurpose>
Restores the previous error handler function
</refpurpose>
</refnamediv>
<refsect1>
&reftitle.description;
<methodsynopsis>
<type>bool</type><methodname>restore_error_handler</methodname>
<void/>
</methodsynopsis>
<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;.
</para>
<note>
<para>
Calling <function>restore_error_handler</function> from the
<literal>error_handler</literal> function is ignored.
</para>
</note>
<para>
See also <function>error_reporting</function>,
<function>set_error_handler</function>,
<function>restore_exception_handler</function>,
<function>trigger_error</function>.
</para>
<para>
<example>
<title>
Decide if <function>unserialize</function> caused an error, then
restore the original error handler.
</title>
<programlisting role="php">
<![CDATA[
<?php
function unserialize_handler($errno, $errstr)
@ -52,17 +52,17 @@ $original = unserialize($serialized);
restore_error_handler();
?>
]]>
</programlisting>
&example.outputs;
<screen>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
Invalid serialized value.
]]>
</screen>
</example>
</para>
</refsect1>
</refentry>
</screen>
</example>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

View file

@ -1,33 +1,33 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.3 $ -->
<refentry id="function.restore-exception-handler">
<refnamediv>
<refname>restore_exception_handler</refname>
<refpurpose>
Restores the previously defined exception handler function
</refpurpose>
</refnamediv>
<refsect1>
&reftitle.description;
<methodsynopsis>
<type>bool</type><methodname>restore_exception_handler</methodname>
<void/>
</methodsynopsis>
<para>
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;.
</para>
<para>
See also
<function>set_exception_handler</function>,
<function>set_error_handler</function>,
<function>restore_error_handler</function>
<function>error_reporting</function>
</para>
</refsect1>
</refentry>
<!-- $Revision: 1.4 $ -->
<refentry id="function.restore-exception-handler">
<refnamediv>
<refname>restore_exception_handler</refname>
<refpurpose>
Restores the previously defined exception handler function
</refpurpose>
</refnamediv>
<refsect1>
&reftitle.description;
<methodsynopsis>
<type>bool</type><methodname>restore_exception_handler</methodname>
<void/>
</methodsynopsis>
<para>
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;.
</para>
<para>
See also
<function>set_exception_handler</function>,
<function>set_error_handler</function>,
<function>restore_error_handler</function>
<function>error_reporting</function>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

View file

@ -1,143 +1,143 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.28 $ -->
<!-- $Revision: 1.29 $ -->
<!-- splitted from ./en/functions/errorfunc.xml, last change in rev 1.1 -->
<refentry id="function.set-error-handler">
<refnamediv>
<refname>set_error_handler</refname>
<refpurpose>
Sets a user-defined error handler function
</refpurpose>
</refnamediv>
<refsect1>
&reftitle.description;
<methodsynopsis>
<type>mixed</type><methodname>set_error_handler</methodname>
<methodparam><type>callback</type><parameter>error_handler</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>error_types</parameter></methodparam>
</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.
</para>
<para>
This function can be used for defining your own way of handling errors
during runtime, for example in applications in which you need to do
cleanup of data/files when a critical error happens, or when you need
to trigger an error under certain conditions (using
<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.
</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>
<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>
<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>
<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>
<programlisting role="php">
<refentry id="function.set-error-handler">
<refnamediv>
<refname>set_error_handler</refname>
<refpurpose>
Sets a user-defined error handler function
</refpurpose>
</refnamediv>
<refsect1>
&reftitle.description;
<methodsynopsis>
<type>mixed</type><methodname>set_error_handler</methodname>
<methodparam><type>callback</type><parameter>error_handler</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>error_types</parameter></methodparam>
</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.
</para>
<para>
This function can be used for defining your own way of handling errors
during runtime, for example in applications in which you need to do
cleanup of data/files when a critical error happens, or when you need
to trigger an error under certain conditions (using
<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.
</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>
<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>
<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>
<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>
<programlisting role="php">
<![CDATA[
<?php
// set the error reporting level for this script
error_reporting(E_USER_ERROR | E_USER_WARNING | E_USER_NOTICE);
// error handler function
function myErrorHandler($errno, $errstr, $errfile, $errline)
function myErrorHandler($errno, $errstr, $errfile, $errline)
{
switch ($errno) {
case E_USER_ERROR:
@ -160,11 +160,10 @@ function myErrorHandler($errno, $errstr, $errfile, $errline)
}
// function to test the error handling
function scale_by_log($vect, $scale)
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);
trigger_error("log(x) for x <= 0 is undefined, you used: scale = $scale", E_USER_ERROR);
}
if (!is_array($vect)) {
@ -174,12 +173,11 @@ function scale_by_log($vect, $scale)
for ($i=0; $i<count($vect); $i++) {
if (!is_numeric($vect[$i]))
trigger_error("Value at position $i is not a number, using 0 (zero)",
E_USER_NOTICE);
$temp[$i] = log($scale) * $vect[$i];
trigger_error("Value at position $i is not a number, using 0 (zero)", E_USER_NOTICE);
$temp[$i] = log($scale) * $vect[$i];
}
return $temp;
}
return $temp;
}
// set to the user defined error handler
$old_error_handler = set_error_handler("myErrorHandler");
@ -205,9 +203,9 @@ $d = scale_by_log($a, -2.5);
?>
]]>
</programlisting>
&example.outputs;
<screen>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
vector a
Array
@ -238,48 +236,48 @@ NULL
----
vector d - fatal error
<b>FATAL</b> [256] log(x) for x <= 0 is undefined, you used: scale = -2.5<br />
Fatal error in line 36 of file trigger_error.php, PHP 4.0.2 (Linux)<br />
Fatal error in line 36 of file trigger_error.php, PHP 4.0.2 (Linux)<br />
Aborting...<br />
]]>
</screen>
</example>
</para>
<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;.
</para>
</refsect1>
</refentry>
</screen>
</example>
</para>
<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;.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

View file

@ -1,66 +1,66 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.10 $ -->
<!-- $Revision: 1.11 $ -->
<!-- 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>
</refnamediv>
<refsect1>
&reftitle.description;
<methodsynopsis>
<type>bool</type><methodname>trigger_error</methodname>
<methodparam><type>string</type><parameter>error_msg</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>error_type</parameter></methodparam>
</methodsynopsis>
<para>
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>.
</para>
<para>
This function returns &false; if wrong <parameter>error_type</parameter> is
specified, &true; otherwise.
</para>
<para>
This function is useful when
you need to generate a particular response to an exception at runtime.
For example:
<informalexample>
<programlisting role="php">
<refentry id="function.trigger-error">
<refnamediv>
<refname>trigger_error</refname>
<refpurpose>
Generates a user-level error/warning/notice message
</refpurpose>
</refnamediv>
<refsect1>
&reftitle.description;
<methodsynopsis>
<type>bool</type><methodname>trigger_error</methodname>
<methodparam><type>string</type><parameter>error_msg</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>error_type</parameter></methodparam>
</methodsynopsis>
<para>
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>.
</para>
<para>
This function returns &false; if wrong <parameter>error_type</parameter> is
specified, &true; otherwise.
</para>
<para>
This function is useful when
you need to generate a particular response to an exception at runtime.
For example:
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
if (assert($divisor == 0)) {
trigger_error("Cannot divide by zero", E_USER_ERROR);
trigger_error("Cannot divide by zero", E_USER_ERROR);
}
?>
]]>
</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>
</para>
</programlisting>
</informalexample>
<note>
<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>.
See <function>set_error_handler</function> for a more extensive example.
</para>
</refsect1>
</refentry>
</note>
<note>
<para>
<parameter>error_msg</parameter> is limited to 1024 characters in length.
Any additional characters beyond 1024 will be truncated.
</para>
</note>
</para>
<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>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

View file

@ -1,18 +1,18 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.4 $ -->
<!-- $Revision: 1.5 $ -->
<!-- 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>
&reftitle.description;
<para>
This function is an alias of <function>trigger_error</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.user-error">
<refnamediv>
<refname>user_error</refname>
<refpurpose>Alias of <function>trigger_error</function></refpurpose>
</refnamediv>
<refsect1>
&reftitle.description;
<para>
This function is an alias of <function>trigger_error</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables: