 |
 |
 |
 |
|
|
Date: 09/07/00
- Next message: Jesus M. Castagnetto: "[PHP-DOC] cvs: phpdoc / manual.xml.in /en chapters.ent /en/features error-handling.xml"
- Previous message: Hartmut Holzgraefe: "[PHP-DOC] cvs: phpdoc / version.dsl"
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
jmcastagnetto Thu Sep 7 06:23:46 2000 EDT
Added files:
/phpdoc/en/functions errorfunc.xml
Modified files:
/phpdoc/en/functions info.xml misc.xml
Log:
Moved error handling/logging functiond from info.xml and misc.xml
to errorfunc.xml
Index: phpdoc/en/functions/info.xml
diff -u phpdoc/en/functions/info.xml:1.29 phpdoc/en/functions/info.xml:1.30
--- phpdoc/en/functions/info.xml:1.29 Wed Sep 6 21:48:18 2000
+++ phpdoc/en/functions/info.xml Thu Sep 7 06:23:46 2000
@@ -115,7 +115,7 @@
<entry>(null)</entry>
<entry>user function to call on failed assertions</entry>
</row>
- </tbody>
+ </tbody>
</tgroup>
</table>
<para>
@@ -125,230 +125,6 @@
</refsect1>
</refentry>
- <refentry id="function.error-log">
- <refnamediv>
- <refname>error_log</refname>
- <refpurpose>send an error message somewhere</refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>error_log</function></funcdef>
- <paramdef>string <parameter>message</parameter></paramdef>
- <paramdef>int <parameter>message_type</parameter></paramdef>
- <paramdef>string
- <parameter><optional>destination</optional></parameter>
- </paramdef>
- <paramdef>string
- <parameter><optional>extra_headers</optional></parameter>
- </paramdef>
- </funcprototype>
- </funcsynopsis>
- <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.
- </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="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>
- <para>
- <example role="php">
- <title><function>error_log</function> examples</title>
- <programlisting role="php">
-// Send notification through the server log if we can not
-// connect to the database.
-if (!Ora_Logon($username, $password)) {
- error_log("Oracle database not available!", 0);
-}
-
-// Notify administrator by email if we run out of FOO
-if (!($foo = allocate_new_foo()) {
- error_log ("Big trouble, we're all out of FOOs!", 1,
- "operator <email protected>");
-}
-
-// other ways of calling error_log():
-error_log ("You messed up!", 2, "127.0.0.1:7000");
-error_log ("You messed up!", 2, "loghost");
-error_log ("You messed up!", 3, "/var/tmp/my-errors.log");
- </programlisting>
- </example>
- </para>
- </refsect1>
- </refentry>
-
- <refentry id="function.error-reporting">
- <refnamediv>
- <refname>error_reporting</refname>
- <refpurpose>set which PHP errors are reported</refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>error_reporting</function></funcdef>
- <paramdef>int
- <parameter><optional>level</optional></parameter>
- </paramdef>
- </funcprototype>
- </funcsynopsis>
- <para>
- Sets PHP's error reporting level and returns the old level. The
- error reporting level is either a bitmask, or named constant. 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.
- <example role="php">
- <title>Error Integer changes</title>
- <programlisting role="php">
-error_reporting(55); // PHP 3 equivalent to E_ALL ^ E_NOTICE
-
-/* ...in PHP 4, '55' would mean (E_ERROR | E_WARNING | E_PARSE |
-E_CORE_ERROR | E_CORE_WARNING) */
-
-error_reporting(2039); // PHP 4 equivalent to E_ALL ^ E_NOTICE
-
-error_reporting(E_ALL ^ E_NOTICE); // The same in both PHP 3 and 4
- </programlisting>
- </example>
-
- Follow the links for the internal values to get their meanings:
- <table>
- <title><function>error_reporting</function> bit values</title>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>value</entry>
- <entry>internal name</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>1</entry>
- <entry>
- <link linkend="internal.e-error">E_ERROR</link>
- </entry>
- </row>
- <row>
- <entry>2</entry>
- <entry>
- <link linkend="internal.e-warning">E_WARNING</link>
- </entry>
- </row>
- <row>
- <entry>4</entry>
- <entry>
- <link linkend="internal.e-parse">E_PARSE</link>
- </entry>
- </row>
- <row>
- <entry>8</entry>
- <entry>
- <link linkend="internal.e-notice">E_NOTICE</link>
- </entry>
- </row>
- <row>
- <entry>16</entry>
- <entry>
- <link linkend="internal.e-core-error">E_CORE_ERROR</link>
- </entry>
- </row>
- <row>
- <entry>32</entry>
- <entry>
- <link linkend="internal.e-core-warning">E_CORE_WARNING</link>
- </entry>
- </row>
- <row>
- <entry>64</entry>
- <entry>
- <link linkend="internal.e-compile-error">E_COMPILE_ERROR</link>
- </entry>
- </row>
- <row>
- <entry>128</entry>
- <entry>
- <link linkend="internal.e-compile-warning">E_COMPILE_WARNING</link>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </para>
- <para>
- <example role="php">
- <title><function>error_reporting</function> examples</title>
- <programlisting role="php">
-error_reporting(0);
-/* Turn off all reporting */
-
-error_reporting(7); // Old syntax, PHP 2/3
-error_reporting(E_ERROR | E_WARNING | E_PARSE); // New syntax for PHP 3/4
-/* Good to use for simple running errors */
-
-error_reporting(15); // Old syntax, PHP 2/3
-error_reporting(E_ERROR | E_WARNING | E_PARSE | E_NOTICE); // New syntax for PHP 3/4
-/* good for code authoring to report uninitialized or (possibly mis-spelled) variables */
-
-error_reporting(63); // Old syntax, PHP 2/3
-error_reporting(E_ALL); // New syntax for PHP3/4
-/* report all PHP errors */
- </programlisting>
- </example>
- </para>
- </refsect1>
- </refentry>
-
<refentry id="function.extension-loaded">
<refnamediv>
<refname>extension_loaded</refname>
@@ -697,8 +473,8 @@
<title>Getrusage Example</title>
<programlisting role="php">
$dat = getrusage();
-echo $dat["ru_nswap"]; # number of swaps
-echo $dat["ru_majflt"]; # number of page faults
+echo $dat["ru_nswap"]; # number of swaps
+echo $dat["ru_majflt"]; # number of page faults
echo $dat["ru_utime.tv_sec"]; # user time used (seconds)
echo $dat["ru_utime.tv_usec"]; # user time used (microseconds)
</programlisting>
Index: phpdoc/en/functions/misc.xml
diff -u phpdoc/en/functions/misc.xml:1.30 phpdoc/en/functions/misc.xml:1.31
--- phpdoc/en/functions/misc.xml:1.30 Wed Sep 6 22:01:44 2000
+++ phpdoc/en/functions/misc.xml Thu Sep 7 06:23:46 2000
@@ -762,34 +762,6 @@
</refsect1>
</refentry>
- <refentry id="function.restore-error-handler">
- <refnamediv>
- <refname>restore_error_handler</refname>
- <refpurpose>
- Restores the previous error handler function
- </refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
- <funcsynopsis>
- <funcprototype>
- <funcdef>void <function>restore_error_handler</function></funcdef>
- <paramdef>void</paramdef>
- </funcprototype>
- </funcsynopsis>
- <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)
- </para>
- <para>
- See also <function>error_reporting</function>,
- <function>set_error_handler</function>,
- <function>trigger_error</function>, <function>user_error</function>
- </para>
- </refsect1>
- </refentry>
-
<refentry id="function.serialize">
<refnamediv>
<refname>serialize</refname>
@@ -847,161 +819,6 @@
</refsect1>
</refentry>
- <refentry id="function.set-error-handler">
- <refnamediv>
- <refname>set_error_handler</refname>
- <refpurpose>
- Sets a user-defined error handler function.
- </refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
- <funcsynopsis>
- <funcprototype>
- <funcdef>string <function>set_error_handler</function></funcdef>
- <paramdef>string <parameter>error_handler</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <para>
- Sets a user function (<parameter>error_handler</parameter>) to handle
- errors in a script. Returns the previously defined error handler (if
- any), or false on error. 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 user function needs to accept 2 parameters: the error code, and a
- string describing the error. The example below shows the handling of
- internal execptions 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">
-<?php
-
-// redefine the user error constants - PHP4 only
-define(FATAL,E_USER_ERROR);
-define(ERROR,E_USER_WARNING);
-define(WARNING,E_USER_NOTICE);
-
-// set the error reporting level for this script
-error_reporting(FATAL + ERROR + WARNING);
-
-// error handler function
-function myErrorHandler ($errno, $errstr) {
- switch ($errno) {
- case FATAL:
- echo "<b>FATAL</b> [$errno] $errstr<br>\n";
- echo " Fatal error in line ".__LINE__." of file ".__FILE__;
- echo ", PHP ".PHP_VERSION." (".PHP_OS.")<br>\n";
- echo "Aborting...<br>\n";
- exit -1;
- break;
- case ERROR:
- echo "<b>ERROR</b> [$errno] $errstr<br>\n";
- break;
- case WARNING:
- echo "<b>WARNING</b> [$errno] $errstr<br>\n";
- break;
- default:
- echo "Unkown error type: [$errno] $errstr<br>\n";
- break;
- }
-}
-
-// 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",
- FATAL);
- if (!is_array($vect)) {
- trigger_error("Incorrect input vector, array of values expected", ERROR);
- return null;
- }
- 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)",
- WARNING);
- $temp[$i] = log($scale) * $vect[$i];
- }
- return $temp;
-}
-
-// set to the use 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, generating a warning
-echo "----\nvector b - a warning (b = log(PI) * a)\n";
-$b = scale_by_log($a, M_PI);
-print_r($b);
-
-// this is trouble, we pass a string instead of an array
-echo "----\nvector c - an error\n";
-$c = scale_by_log("not array",2.3);
-var_dump($c);
-
-// this is a critical error, log of zero or negative number is undefined
-echo "----\nvector d - fatal error\n";
-$d = scale_by_log($a, -2.5);
-
-?>
- </programlisting>
- </example>
- And when you run this sample script, the output will be
- <informalexample>
- <programlisting>
-vector a
-Array
-(
- [0] => 2
- [1] => 3
- [2] => foo
- [3] => 5.5
- [4] => 43.3
- [5] => 21.11
-)
-----
-vector b - a warning (b = log(PI) * a)
-<b>WARNING</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 - an error
-<b>ERROR</b> [512] Incorrect input vector, array of values expected<br>
-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 16 of file trigger_error.php, PHP 4.0.1pl2 (Linux)<br>
-Aborting...<br>
- </programlisting>
- </informalexample>
- </para>
- <para>
- See also <function>error_reporting</function>,
- <function>restore_error_handler</function>,
- <function>trigger_error</function>, <function>user_error</function>
- </para>
- </refsect1>
- </refentry>
-
<refentry id="function.show-source">
<refnamediv>
<refname>show_source</refname>
@@ -1056,52 +873,6 @@
</refsect1>
</refentry>
- <refentry id="function.trigger-error">
- <refnamediv>
- <refname>trigger_error</refname>
- <refpurpose>
- Generates a user-level error/warning/notice message
- </refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
- <funcsynopsis>
- <funcprototype>
- <funcdef>void <function>trigger_error</function></funcdef>
- <paramdef>string <parameter>error_msg</parameter></paramdef>
- <paramdef>int
- <parameter><optional>error_type</optional></parameter>
- </paramdef>
- </funcprototype>
- </funcsynopsis>
- <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>). This function is useful when
- you need to generate a particular response to an exception at runtime.
- For example:
- <informalexample>
- <programlisting>
-if (assert($divisor == 0))
- 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>
- </para>
- <para>
- See also <function>error_reporting</function>,
- <function>set_error_handler</function>,
- <function>restore_error_handler</function>,
- <function>user_error</function>
- </para>
- </refsect1>
- </refentry>
-
<refentry id="function.uniqid">
<refnamediv>
<refname>uniqid</refname>
@@ -1257,36 +1028,6 @@
}
</programlisting>
</example>
- </para>
- </refsect1>
- </refentry>
-
- <refentry id="function.user-error">
- <refnamediv>
- <refname>user_error</refname>
- <refpurpose>
- Generates a user-level error/warning/notice message
- </refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
- <funcsynopsis>
- <funcprototype>
- <funcdef>void <function>user_error</function></funcdef>
- <paramdef>string <parameter>error_msg</parameter></paramdef>
- <paramdef>int
- <parameter><optional>error_type</optional></parameter>
- </paramdef>
- </funcprototype>
- </funcsynopsis>
- <para>
- This is an alias for the function <function>trigger_error</function>.
- </para>
- <para>
- See also <function>error_reporting</function>,
- <function>set_error_handler</function>,
- <function>restore_error_handler</function>,
- <function>trigger_error</function>
</para>
</refsect1>
</refentry>
Index: phpdoc/en/functions/errorfunc.xml
+++ phpdoc/en/functions/errorfunc.xml
<reference id="ref.errorfunc">
<title>Error Handling and Logging Functions</title>
<titleabbrev>Error Handling and Logging</titleabbrev>
<partintro>
<para>
These are functions dealing with error handling and logging. They
are very useful when you want to define a way of handling
errors that can occur in your scripts.
</para>
</partintro>
<refentry id="function.error-log">
<refnamediv>
<refname>error_log</refname>
<refpurpose>send an error message somewhere</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>error_log</function></funcdef>
<paramdef>string <parameter>message</parameter></paramdef>
<paramdef>int <parameter>message_type</parameter></paramdef>
<paramdef>string
<parameter><optional>destination</optional></parameter>
</paramdef>
<paramdef>string
<parameter><optional>extra_headers</optional></parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<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.
</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="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>
<para>
<example role="php">
<title><function>error_log</function> examples</title>
<programlisting role="php">
// Send notification through the server log if we can not
// connect to the database.
if (!Ora_Logon($username, $password)) {
error_log("Oracle database not available!", 0);
}
// Notify administrator by email if we run out of FOO
if (!($foo = allocate_new_foo()) {
error_log ("Big trouble, we're all out of FOOs!", 1,
"operator <email protected>");
}
// other ways of calling error_log():
error_log ("You messed up!", 2, "127.0.0.1:7000");
error_log ("You messed up!", 2, "loghost");
error_log ("You messed up!", 3, "/var/tmp/my-errors.log");
</programlisting>
</example>
</para>
</refsect1>
</refentry>
<refentry id="function.error-reporting">
<refnamediv>
<refname>error_reporting</refname>
<refpurpose>set which PHP errors are reported</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>error_reporting</function></funcdef>
<paramdef>int
<parameter><optional>level</optional></parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<para>
Sets PHP's error reporting level and returns the old level. The
error reporting level is either a bitmask, or named constant. 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.
<example role="php">
<title>Error Integer changes</title>
<programlisting role="php">
error_reporting(55); // PHP 3 equivalent to E_ALL ^ E_NOTICE
/* ...in PHP 4, '55' would mean (E_ERROR | E_WARNING | E_PARSE |
E_CORE_ERROR | E_CORE_WARNING) */
error_reporting(2039); // PHP 4 equivalent to E_ALL ^ E_NOTICE
error_reporting(E_ALL ^ E_NOTICE); // The same in both PHP 3 and 4
</programlisting>
</example>
Follow the links for the internal values to get their meanings:
<table>
<title><function>error_reporting</function> bit values</title>
<tgroup cols="2">
<thead>
<row>
<entry>constant</entry>
<entry>value</entry>
</row>
</thead>
<tbody>
<row>
<entry>1</entry>
<entry>
<link linkend="internal.e-error">E_ERROR</link>
</entry>
</row>
<row>
<entry>2</entry>
<entry>
<link linkend="internal.e-warning">E_WARNING</link>
</entry>
</row>
<row>
<entry>4</entry>
<entry>
<link linkend="internal.e-parse">E_PARSE</link>
</entry>
</row>
<row>
<entry>8</entry>
<entry>
<link linkend="internal.e-notice">E_NOTICE</link>
</entry>
</row>
<row>
<entry>16</entry>
<entry>
<link linkend="internal.e-core-error">E_CORE_ERROR</link>
</entry>
</row>
<row>
<entry>32</entry>
<entry>
<link linkend="internal.e-core-warning">E_CORE_WARNING</link>
</entry>
</row>
<row>
<entry>64</entry>
<entry>
<link linkend="internal.e-compile-error">E_COMPILE_ERROR</link>
</entry>
</row>
<row>
<entry>128</entry>
<entry>
<link linkend="internal.e-compile-warning">E_COMPILE_WARNING</link>
</entry>
</row>
<row>
<entry>256</entry>
<entry>
<link linkend="internal.e-user-error">E_USER_ERROR</link>
</entry>
</row>
<row>
<entry>512</entry>
<entry>
<link linkend="internal.e-user-warning">E_USER_WARNING</link>
</entry>
</row>
<row>
<entry>1024</entry>
<entry>
<link linkend="internal.e-user-error">E_USER_NOTICE</link>
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<para>
<example role="php">
<title><function>error_reporting</function> examples</title>
<programlisting role="php">
error_reporting(0);
/* Turn off all reporting */
error_reporting(7); // Old syntax, PHP 2/3
error_reporting(E_ERROR | E_WARNING | E_PARSE); // New syntax for PHP 3/4
/* Good to use for simple running errors */
error_reporting(15); // Old syntax, PHP 2/3
error_reporting(E_ERROR | E_WARNING | E_PARSE | E_NOTICE); // New syntax for PHP 3/4
/* good for code authoring to report uninitialized or (possibly mis-spelled) variables */
error_reporting(63); // Old syntax, PHP 2/3
error_reporting(E_ALL); // New syntax for PHP3/4
/* report all PHP errors */
</programlisting>
</example>
</para>
</refsect1>
</refentry>
<refentry id="function.restore-error-handler">
<refnamediv>
<refname>restore_error_handler</refname>
<refpurpose>
Restores the previous error handler function
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>restore_error_handler</function></funcdef>
<paramdef>void</paramdef>
</funcprototype>
</funcsynopsis>
<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)
</para>
<para>
See also <function>error_reporting</function>,
<function>set_error_handler</function>,
<function>trigger_error</function>, <function>user_error</function>
</para>
</refsect1>
</refentry>
<refentry id="function.set-error-handler">
<refnamediv>
<refname>set_error_handler</refname>
<refpurpose>
Sets a user-defined error handler function.
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>string <function>set_error_handler</function></funcdef>
<paramdef>string <parameter>error_handler</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Sets a user function (<parameter>error_handler</parameter>) to handle
errors in a script. Returns the previously defined error handler (if
any), or false on error. 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 user function needs to accept 2 parameters: the error code, and a
string describing the error. The example below shows the handling of
internal execptions 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">
<?php
// redefine the user error constants - PHP4 only
define(FATAL,E_USER_ERROR);
define(ERROR,E_USER_WARNING);
define(WARNING,E_USER_NOTICE);
// set the error reporting level for this script
error_reporting(FATAL + ERROR + WARNING);
// error handler function
function myErrorHandler ($errno, $errstr) {
switch ($errno) {
case FATAL:
echo "<b>FATAL</b> [$errno] $errstr<br>\n";
echo " Fatal error in line ".__LINE__." of file ".__FILE__;
echo ", PHP ".PHP_VERSION." (".PHP_OS.")<br>\n";
echo "Aborting...<br>\n";
exit -1;
break;
case ERROR:
echo "<b>ERROR</b> [$errno] $errstr<br>\n";
break;
case WARNING:
echo "<b>WARNING</b> [$errno] $errstr<br>\n";
break;
default:
echo "Unkown error type: [$errno] $errstr<br>\n";
break;
}
}
// 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",
FATAL);
if (!is_array($vect)) {
trigger_error("Incorrect input vector, array of values expected", ERROR);
return null;
}
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)",
WARNING);
$temp[$i] = log($scale) * $vect[$i];
}
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, generating a warning
echo "----\nvector b - a warning (b = log(PI) * a)\n";
$b = scale_by_log($a, M_PI);
print_r($b);
// this is trouble, we pass a string instead of an array
echo "----\nvector c - an error\n";
$c = scale_by_log("not array",2.3);
var_dump($c);
// this is a critical error, log of zero or negative number is undefined
echo "----\nvector d - fatal error\n";
$d = scale_by_log($a, -2.5);
?>
</programlisting>
</example>
And when you run this sample script, the output will be
<informalexample>
<programlisting>
vector a
Array
(
[0] => 2
[1] => 3
[2] => foo
[3] => 5.5
[4] => 43.3
[5] => 21.11
)
----
vector b - a warning (b = log(PI) * a)
<b>WARNING</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 - an error
<b>ERROR</b> [512] Incorrect input vector, array of values expected<br>
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 16 of file trigger_error.php, PHP 4.0.1pl2 (Linux)<br>
Aborting...<br>
</programlisting>
</informalexample>
</para>
<para>
See also <function>error_reporting</function>,
<function>restore_error_handler</function>,
<function>trigger_error</function>, <function>user_error</function>
</para>
</refsect1>
</refentry>
<refentry id="function.trigger-error">
<refnamediv>
<refname>trigger_error</refname>
<refpurpose>
Generates a user-level error/warning/notice message
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>trigger_error</function></funcdef>
<paramdef>string <parameter>error_msg</parameter></paramdef>
<paramdef>int
<parameter><optional>error_type</optional></parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<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>). This function is useful when
you need to generate a particular response to an exception at runtime.
For example:
<informalexample>
<programlisting>
if (assert($divisor == 0))
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>
</para>
<para>
See also <function>error_reporting</function>,
<function>set_error_handler</function>,
<function>restore_error_handler</function>,
<function>user_error</function>
</para>
</refsect1>
</refentry>
<refentry id="function.user-error">
<refnamediv>
<refname>user_error</refname>
<refpurpose>
Generates a user-level error/warning/notice message
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>user_error</function></funcdef>
<paramdef>string <parameter>error_msg</parameter></paramdef>
<paramdef>int
<parameter><optional>error_type</optional></parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<para>
This is an alias for the function <function>trigger_error</function>.
</para>
<para>
See also <function>error_reporting</function>,
<function>set_error_handler</function>,
<function>restore_error_handler</function>,
<function>trigger_error</function>
</para>
</refsect1>
</refentry>
</reference>
<!-- 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
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->
- Next message: Jesus M. Castagnetto: "[PHP-DOC] cvs: phpdoc / manual.xml.in /en chapters.ent /en/features error-handling.xml"
- Previous message: Hartmut Holzgraefe: "[PHP-DOC] cvs: phpdoc / version.dsl"
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]