cvs: peardoc /en/core/pear/pear-errorstack intro.xml
| From: | Christophe Gesch� | Date: | Sat, 05 Nov 2005 08:56:10 +0000 |
| Subject: | cvs: peardoc /en/core/pear/pear-errorstack intro.xml | ||
| Groups: | php.pear.doc | ||
| Request: | Send a blank email to pear-doc+get-7142@lists.php.net to get a copy of this message | ||
moosh Sat Nov 5 03:56:10 2005 EDT
Modified files:
/peardoc/en/core/pear/pear-errorstack intro.xml
Log:
- indent (include new line for easiest translation)
- change tag classname
http://cvs.php.net/diff.php/peardoc/en/core/pear/pear-errorstack/intro.xml?r1=1.12&r2=1.13&ty=u Index: peardoc/en/core/pear/pear-errorstack/intro.xml diff -u peardoc/en/core/pear/pear-errorstack/intro.xml:1.12 peardoc/en/core/pear/pear-errorstack/intro.xml:1.13 --- peardoc/en/core/pear/pear-errorstack/intro.xml:1.12 Thu Sep 22 03:31:56 2005 +++ peardoc/en/core/pear/pear-errorstack/intro.xml Sat Nov 5 03:56:08 2005 @@ -1,8 +1,12 @@ -<!-- $Revision: 1.12 $ --> +<!-- $Revision: 1.13 $ --> <refentry id="core.pear.pear-errorstack.intro"> <refnamediv> - <refname>Introduction to using PEAR_ErrorStack for advanced error handling</refname> - <refpurpose>Using PEAR_ErrorStack to do both simple and advanced error handling</refpurpose> + <refname> + Introduction to using PEAR_ErrorStack for advanced error handling + </refname> + <refpurpose> + Using PEAR_ErrorStack to do both simple and advanced error handling + </refpurpose> </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> @@ -23,32 +27,66 @@ <refsect1 id="core.pear.pear-errorstack.intro.intro"> <title>Introduction</title> <para> - This class is available as part of the <ulink url="&url.pear.package;pear">PEAR package</ulink>. + This class is available as part of the + <ulink url="&url.pear.package;pear">PEAR package</ulink>. Features include: <itemizedlist> <listitem><para>Fully unit-tested and documented</para></listitem> - <listitem><para>blazingly fast - blows PEAR_Error out of the water</para></listitem> + <listitem> + <para> + blazingly fast - blows PEAR_Error out of the water + </para> + </listitem> <listitem><para>Package-specific errors</para></listitem> - <listitem><para>Error levels (notice/warning/error/exception)</para></listitem> - <listitem><para>Error context data is saved separate from error message</para></listitem> - <listitem><para>Error cascading - parent errors can be specified</para></listitem> - <listitem><para>Dynamic error message generation allows generation of multiple - and distinct error messages from the same error object</para></listitem> - <listitem><para>Sophisticated callbacks are available for error message generation, - error context generation, and error handling functionality, - see <link linkend="core.pear.pear-errorstack.intro.advanced.context">Error Context Display</link>, - <link linkend="core.pear.pear-errorstack.intro.advanced.message">Custom Error Message Generation</link>, - and <link linkend="core.pear.pear-errorstack.intro.advanced.callback">controlling error generation</link></para> + <listitem> + <para> + Error levels (notice/warning/error/exception) + </para> + </listitem> + <listitem> + <para> + Error context data is saved separate from error message + </para> + </listitem> + <listitem> + <para> + Error cascading - parent errors can be specified + </para> + </listitem> + <listitem> + <para> + Dynamic error message generation allows generation of multiple + and distinct error messages from the same error object + </para> + </listitem> + <listitem> + <para> + Sophisticated callbacks are available for error message generation, + error context generation, and error handling functionality, + see + <link linkend="core.pear.pear-errorstack.intro.advanced.context">Error Context Display</link>, + <link linkend="core.pear.pear-errorstack.intro.advanced.message">Custom Error Message Generation</link>, + and + <link linkend="core.pear.pear-errorstack.intro.advanced.callback">controlling error generation</link> + </para> </listitem> </itemizedlist> </para> <para> - PEAR_ErrorStack implements error raising and handling using a stack pattern. This has tremendous advantages - over the PEAR_Error Implementation. PEAR_Error centralizes all error creation and handling in the - constructor of the PEAR_Error object. Once an object has been created, all handling must have been - completed, either through checking the return value of a method, or through a single global callback. In addition, - it is nearly impossible to determine the source of an error, and the baggage of all of the PEAR base class's - bulky, slow methods accompanies every error creation. + PEAR_ErrorStack implements error raising and handling using a stack pattern. + + This has tremendous advantages over the PEAR_Error Implementation. + + PEAR_Error centralizes all error creation and handling in the + constructor of the PEAR_Error object. + + Once an object has been created, all handling must have been completed, + either through checking the return value of a method, + or through a single global callback. + + In addition, it is nearly impossible to determine the source of an error, + and the baggage of all of the PEAR base class's bulky, + slow methods accompanies every error creation. </para> <para> <programlisting role = "php"> @@ -64,7 +102,7 @@ $this->display($err->getMessage()); $this->log($err->getMessage()); } - + function log($msg) { error_log($msg, 3, 'somefile.log') @@ -96,8 +134,10 @@ </programlisting> </para> <para> - The PEAR_ErrorStack class has built in knowledge of the <ulink url="&url.pear.package;Log">Log</ulink> package, - can easily differentiate and even automatically re-package errors with little to no difficulty. + The PEAR_ErrorStack class has built in knowledge of the + <ulink url="&url.pear.package;Log">Log</ulink> package, + can easily differentiate and even automatically re-package errors + with little to no difficulty. </para> <para> <programlisting role = "php"><![CDATA[ @@ -117,12 +157,12 @@ function errorCallback($err) { switch($err['package']){ - case 'MyPackage': + case 'MyPackage': // tell the error stack to log the error only // it will not be pushed onto the stack return PEAR_ERRORSTACK_LOG; break; - case 'InternalDbPackage': + case 'InternalDbPackage': // re-package these errors as a mypackage error fit // for enduser consumption $this->_stack->push(MYPACKAGE_ERROR_DBERROR, 'error', @@ -169,31 +209,52 @@ </programlisting> </para> <para> - Why write a new error-handling routine when <link linkend="core.pear.pear-error"><classname>PEAR_Error</classname></link> - already exists? There are several problems with <classname>PEAR_Error</classname>. - Although an error message is present in an error class, processing this error - message automatically is excessively difficult for computers. In addition, - the error message cannot easily be translated once it has been placed into - the <classname>PEAR_Error</classname>. There is also no standard facility for - storing error-related data in the error class. On top of error - message-related issues, there is no way to automatically determine which - package a <classname>PEAR_Error object</classname> - comes from, or the severity of an error. Fatal + Why write a new error-handling routine when + <link linkend="core.pear.pear-error"><classname>PEAR_Error</classname></link> + already exists? + + There are several problems with <classname>PEAR_Error</classname>. + + Although an error message is present in an error class, + processing this error message automatically is excessively + difficult for computers. + + In addition, the error message cannot easily be translated once it has been placed into + the <classname>PEAR_Error</classname>. + + There is also no standard facility for + storing error-related data in the error class. + + On top of error message-related issues, + there is no way to automatically determine which package a + <classname>PEAR_Error</classname> object comes from, + or the severity of an error. + + Fatal errors look exactly the same as non-fatal errors. </para> <para> - The largest flaw with <classname>PEAR_Error object</classname> - is the single-error type design. Every <classname>PEAR_Error object</classname> - is just a <classname>PEAR_Error object</classname>. There is no differentiating - between the severity of an error, or its origin. The - only way to determine the severity is to use PEAR_ERROR_TRIGGER and E_USER_NOTICE/E_USER_WARNING/E_USER_ERROR - constants from php's <ulink url="&url.php.lookup;trigger_error">trigger_error</ulink>. + The largest flaw with <classname>PEAR_Error</classname> object is the + single-error type design. + + Every <classname>PEAR_Error</classname> object is just a + <classname>PEAR_Error</classname> object. + + There is no differentiating between the severity of an error, or its origin. + + The only way to determine the severity is to use + PEAR_ERROR_TRIGGER and E_USER_NOTICE/E_USER_WARNING/E_USER_ERROR + constants from php's + <ulink url="&url.php.lookup;trigger_error">trigger_error</ulink>. + But using this functionality does not justify 900 lines of code, simply because trigger_error() is built into PHP itself! </para> <para> - Now, to start using your newly created error objects, change - all of your <function>PEAR::raiseError</function> or <function>PEAR::throwError</function> + Now, to start using your newly created error objects, + change all of your + <function>PEAR::raiseError</function> + or <function>PEAR::throwError</function> calls from this... </para> <para> @@ -228,8 +289,9 @@ ?>]]> </programlisting> </para> - <para>For basic use, this is all that is needed to use the PEAR_ErrorStack package - in place of PEAR_Error. + <para> + For basic use, this is all that is needed to use the + PEAR_ErrorStack package in place of PEAR_Error. </para> </refsect1> <refsect1 id = "core.pear.pear-errorstack.intro.advanced"> @@ -237,17 +299,28 @@ <refsect2 id = "core.pear.pear-errorstack.intro.advanced.context"> <title>Error Context Display</title> <para> - In some cases, you may want to customize error generation. For instance, for - many exceptions, it is useful to include file, line number, and class/function - context information in order to trace an error. A default option is - available which will be sufficient for most cases, and that - is <link linkend="core.pear.pear-errorstack.getfileline"><function>PEAR_ErrorStack::getFileLine</function></link>. + In some cases, you may want to customize error generation. + For instance, for many exceptions, it is useful to include file, + line number, + and class/function context information in order to trace an error. + + A default option is available which will be sufficient for most cases, + and that is + <link linkend="core.pear.pear-errorstack.getfileline"><function>PEAR_ErrorStack::getFileLine</function></link>. </para> <para> - Not all package errors occur in the PHP source file. For instance, compiling template - engines errors can occur in the template source files. Database errors can occur in the text of a query, - or internal to the database server. Internet package errors can occur on another server. All of this - information can be included in an error message using a context grabbing callback. + Not all package errors occur in the PHP source file. + + For instance, compiling template + engines errors can occur in the template source files. + + Database errors can occur in the text of a query, + or internal to the database server. + + Internet package errors can occur on another server. + + All of this information can be included in an error + message using a context grabbing callback. </para> <para> <programlisting role = "php"><![CDATA[ @@ -282,22 +355,28 @@ </programlisting> </para> <para> - The context information is formatted to be easily processed by an external application. - If you wish context information to be in the error message, the error message callback - should be used to add the information in a human-readable format to the error message, as described + The context information is formatted to be easily + processed by an external application. + + If you wish context information to be in the error message, + the error message callback should be used to add the information + in a human-readable format to the error message, as described in the next section. </para> </refsect2> <refsect2 id = "core.pear.pear-errorstack.intro.advanced.message"> <title>Custom Error Message Generation</title> <para> - There are three methods of PEAR_ErrorStack designed for use with generating - error messages efficiently. To use them, you must do one of two things: + There are three methods of PEAR_ErrorStack designed for + use with generating error messages efficiently. + + To use them, you must do one of two things: <itemizedlist> <listitem> <para> - Call <link linkend="core.pear.pear-errorstack.seterrormessagetemplate"><function>PEAR_ErrorStack::setErrorMessageTemplate</function></link>, and set an array mapping - error codes to error message templates, like so: + Call + <link linkend="core.pear.pear-errorstack.seterrormessagetemplate"><function>PEAR_ErrorStack::setErrorMessageTemplate</function></link>, + and set an array mapping error codes to error message templates, like so: </para> <para> <programlisting role = "php"><![CDATA[ @@ -319,18 +398,24 @@ </programlisting> </para> <para> - Substitution is done using <ulink url="&url.php.lookup;str_replace">str_replace</ulink>, and is very simple. + Substitution is done using + <ulink url="&url.php.lookup;str_replace">str_replace</ulink>, + and is very simple. + Basically, if a variable name is enclosed in percent signs (%), it will - be replaced with the value passed in the associative array. If an array - <programlisting role = "php">array('varname' => 'value');</programlisting> + be replaced with the value passed in the associative array. + + If an array + <programlisting role = "php">array('varname' => 'value');</programlisting> is passed to either method, all occurrences of %varname% will be replaced by value. </para> <para> In addition, if values are objects, the methods will search for a method - named "<function>__toString</function>" and if found, will use that - to convert the object to a string. If an array of strings is passed in, - they will be joined by commas. + named "<function>__toString</function>" and if found, + will use that to convert the object to a string. + + If an array of strings is passed in, they will be joined by commas. <programlisting role = "php"><![CDATA[ <?php array('varname' => array('first', 'second', 'third')); @@ -341,10 +426,15 @@ </listitem> <listitem> <para> - Call <link linkend="core.pear.pear-errorstack.setmessagecallback"><function>PEAR_ErrorStack::setMessageCallback</function></link>, and set a custom error - message generating function or method. This is probably the best option for - the majority of complex situations, as it allows users to override or even - extend the existing error message callback using <link linkend="core.pear.pear-errorstack.getmessagecallback"><function>PEAR_ErrorStack::getMessageCallback</function></link>. + Call + <link linkend="core.pear.pear-errorstack.setmessagecallback"><function>PEAR_ErrorStack::setMessageCallback</function></link>, + and set a custom error message generating function or method. + + This is probably the best option for the majority of complex situations, + as it allows users to override or even extend the existing error + message callback using + <link linkend="core.pear.pear-errorstack.getmessagecallback"><function>PEAR_ErrorStack::getMessageCallback</function></link>. + For example: <programlisting role = "php"><![CDATA[ <?php @@ -369,9 +459,13 @@ </listitem> <listitem> <para> - Extend PEAR_ErrorStack with your own class, and override <link linkend="core.pear.pear-errorstack.geterrormessagetemplate"><function>PEAR_ErrorStack::getErrorMessageTemplate</function></link> or - <link linkend="core.pear.pear-errorstack.geterrormessage"><function>PEAR_ErrorStack::getErrorMessage</function></link>. To guarantee that this class will be used by other - packages/applications, use this code right after the class declaration: + Extend PEAR_ErrorStack with your own class, and override + <link linkend="core.pear.pear-errorstack.geterrormessagetemplate"><function>PEAR_ErrorStack::getErrorMessageTemplate</function></link> + or + <link linkend="core.pear.pear-errorstack.geterrormessage"><function>PEAR_ErrorStack::getErrorMessage</function></link>. + + To guarantee that this class will be used by other packages/applications, + use this code right after the class declaration: </para> <para> <programlisting role = "php"><![CDATA[ @@ -387,16 +481,28 @@ <refsect2 id = "core.pear.pear-errorstack.intro.advanced.callback"> <title>Controlling error generation</title> <para> - There are many scenarios in which fine-grained control over error raising is absolutely necessary. A - generic error handling callback means that every single error raised will be handled in the same error - callback. Although PEAR_ErrorStack is designed to operate with independent callbacks for each package, generic - error handling is possible through the <link linkend="core.pear.pear-errorstack.staticpushcallback"><function>PEAR_ErrorStack::staticPushCallback</function></link> method. This is no different - from PEAR_Error's PEAR_ERROR_CALLBACK error handling mode. + There are many scenarios in which fine-grained control over error raising + is absolutely necessary. + + A generic error handling callback means that every single error + raised will be handled in the same error callback. + + Although PEAR_ErrorStack is designed to operate with independent + callbacks for each package, generic error handling is possible through the + <link linkend="core.pear.pear-errorstack.staticpushcallback"><function>PEAR_ErrorStack::staticPushCallback</function></link> + method. + + This is no different from PEAR_Error's + PEAR_ERROR_CALLBACK error handling mode. </para> <para> - PEAR_ErrorStack's real strength comes from the callback itself. PEAR_Error's callback has no actual - effect on the error message - all error handling must happen in the callback method or function itself. - PEAR_ErrorStack's callback can influence the error through the use of three constants: + PEAR_ErrorStack's real strength comes from the callback itself. + + PEAR_Error's callback has no actual effect on the error message - + all error handling must happen in the callback method or function itself. + + PEAR_ErrorStack's callback can influence the error + through the use of three constants: <itemizedlist> <listitem> <para> @@ -417,7 +523,7 @@ </para> <para> PEAR_ERRORSTACK_IGNORE informs the stack to ignore the error, as if it never occurred. The error will be - neither logged, nor pushed on the stack. It will, however, be returned from <link linkend="core.pear.pear-errorstack.push"><function>PEAR_ErrorStack::push</function></link> + neither logged, nor pushed on the stack. It will, however, be returned from <link linkend="core.pear.pear-errorstack.push"><function>PEAR_ErrorStack::push</function></link> </para> <para> PEAR_ERRORSTACK_PUSH informs the stack to push the error onto the error stack, but not to log the error. @@ -436,13 +542,13 @@ function somecallback($err) { switch($err['code']){ - case ERROR_CODE_ONE: + case ERROR_CODE_ONE: return PEAR_ERRORSTACK_IGNORE; break; - case ERROR_CODE_TWO: + case ERROR_CODE_TWO: return PEAR_ERRORSTACK_PUSH; break; - case ERROR_CODE_THREE: + case ERROR_CODE_THREE: return PEAR_ERRORSTACK_LOG; break; } // switch @@ -474,10 +580,14 @@ <refsect3 id = "core.pear.pear-errorstack.intro.advanced.callback.repackage"> <title>Repackaging errors from one package to another</title> <para> - The most obvious usage for an error callback involves a common scenario in many user-level applications - that use system-level packages. If you write a Content Management System (CMS) with the PEAR DB package, - it is usually a bad idea to display database-level errors when a user clicks on a link to add a message to - a forum. PEAR_ErrorStack can be used to repackage this error as a MyPackage error. + The most obvious usage for an error callback involves a common scenario + in many user-level applications that use system-level packages. + + If you write a Content Management System (CMS) with the PEAR DB package, + it is usually a bad idea to display database-level errors when a user + clicks on a link to add a message to a forum. + + PEAR_ErrorStack can be used to repackage this error as a MyPackage error. </para> <para> <programlisting role = "php"><![CDATA[ @@ -500,8 +610,12 @@ <refsect3 id = "core.pear.pear-errorstack.intro.advanced.callback.silence"> <title>Emulating the @ operator</title> <para> - One of the difficult-to-use strengths of PEAR_Error involves the <link linkend="core.pear.pear.expecterror"><function>PEAR::expectError</function></link> - method. With regular PHP errors, it is possible to silence them using the @ operator like so: + One of the difficult-to-use strengths of PEAR_Error involves the + <link linkend="core.pear.pear.expecterror"><function>PEAR::expectError</function></link> + method. + + With regular PHP errors, it is possible to silence them using + the @ operator like so: </para> <para> <programlisting role = "php"><![CDATA[ @@ -530,8 +644,11 @@ </programlisting> </para> <para> - PEAR_ErrorStack can take this one step further, and only log errors or only put errors on the error stack, - using the other two constants. Finally, particular errors can be singled out, and all others ignored. + PEAR_ErrorStack can take this one step further, + and only log errors or only put errors on the error stack, + using the other two constants. + + Finally, particular errors can be singled out, and all others ignored. </para> <para> <programlisting role = "php"><![CDATA[ @@ -559,10 +676,15 @@ </refsect2> </refsect1> <refsect1 id = "core.pear.pear-errorstack.intro.merging"> - <title>Backwards compatibility with PEAR_Error, Forward compatibility with PHP 5 Exception</title> - <para> - <classname>PEAR_ErrorStack</classname> can also be programmed to automatically raise a PEAR_Error - using <link linkend="core.pear.pear.raiseerror"><function>PEAR::raiseError</function></link>, simply pass in true to the PEAR_Error compatibility like so: + <title> + Backwards compatibility with PEAR_Error, + Forward compatibility with PHP 5 Exception + </title> + <para> + <classname>PEAR_ErrorStack</classname> + can also be programmed to automatically raise a PEAR_Error using + <link linkend="core.pear.pear.raiseerror"><function>PEAR::raiseError</function></link>, + simply pass in true to the PEAR_Error compatibility like so: </para> <para> <programlisting role = "php"><![CDATA[ @@ -575,12 +697,17 @@ <warning> <title>Backward Compatibility break</title> <para> - As of PEAR 1.3.2, PEAR_ErrorStack->push() no longer returns an exception class. Code that relies on this behavior will not work + As of PEAR 1.3.2, PEAR_ErrorStack->push() + no longer returns an exception class. + + Code that relies on this behavior will not work </para> </warning> <para> - PEAR_ErrorStack will return an exception automatically in PHP 5. You can set the exception class name that will - be returned using the following code: + PEAR_ErrorStack will return an exception automatically in PHP 5. + + You can set the exception class name that will be returned + using the following code: </para> <para> <programlisting role = "php"><![CDATA[
http://cvs.php.net/diff.php/peardoc/en/core/pear/pear-errorstack/intro.xml?r1=1.12&r2=1.13&ty=u Index: peardoc/en/core/pear/pear-errorstack/intro.xml diff -u peardoc/en/core/pear/pear-errorstack/intro.xml:1.12 peardoc/en/core/pear/pear-errorstack/intro.xml:1.13 --- peardoc/en/core/pear/pear-errorstack/intro.xml:1.12 Thu Sep 22 03:31:56 2005 +++ peardoc/en/core/pear/pear-errorstack/intro.xml Sat Nov 5 03:56:08 2005 @@ -1,8 +1,12 @@ -<!-- $Revision: 1.12 $ --> +<!-- $Revision: 1.13 $ --> <refentry id="core.pear.pear-errorstack.intro"> <refnamediv> - <refname>Introduction to using PEAR_ErrorStack for advanced error handling</refname> - <refpurpose>Using PEAR_ErrorStack to do both simple and advanced error handling</refpurpose> + <refname> + Introduction to using PEAR_ErrorStack for advanced error handling + </refname> + <refpurpose> + Using PEAR_ErrorStack to do both simple and advanced error handling + </refpurpose> </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> @@ -23,32 +27,66 @@ <refsect1 id="core.pear.pear-errorstack.intro.intro"> <title>Introduction</title> <para> - This class is available as part of the <ulink url="&url.pear.package;pear">PEAR package</ulink>. + This class is available as part of the + <ulink url="&url.pear.package;pear">PEAR package</ulink>. Features include: <itemizedlist> <listitem><para>Fully unit-tested and documented</para></listitem> - <listitem><para>blazingly fast - blows PEAR_Error out of the water</para></listitem> + <listitem> + <para> + blazingly fast - blows PEAR_Error out of the water + </para> + </listitem> <listitem><para>Package-specific errors</para></listitem> - <listitem><para>Error levels (notice/warning/error/exception)</para></listitem> - <listitem><para>Error context data is saved separate from error message</para></listitem> - <listitem><para>Error cascading - parent errors can be specified</para></listitem> - <listitem><para>Dynamic error message generation allows generation of multiple - and distinct error messages from the same error object</para></listitem> - <listitem><para>Sophisticated callbacks are available for error message generation, - error context generation, and error handling functionality, - see <link linkend="core.pear.pear-errorstack.intro.advanced.context">Error Context Display</link>, - <link linkend="core.pear.pear-errorstack.intro.advanced.message">Custom Error Message Generation</link>, - and <link linkend="core.pear.pear-errorstack.intro.advanced.callback">controlling error generation</link></para> + <listitem> + <para> + Error levels (notice/warning/error/exception) + </para> + </listitem> + <listitem> + <para> + Error context data is saved separate from error message + </para> + </listitem> + <listitem> + <para> + Error cascading - parent errors can be specified + </para> + </listitem> + <listitem> + <para> + Dynamic error message generation allows generation of multiple + and distinct error messages from the same error object + </para> + </listitem> + <listitem> + <para> + Sophisticated callbacks are available for error message generation, + error context generation, and error handling functionality, + see + <link linkend="core.pear.pear-errorstack.intro.advanced.context">Error Context Display</link>, + <link linkend="core.pear.pear-errorstack.intro.advanced.message">Custom Error Message Generation</link>, + and + <link linkend="core.pear.pear-errorstack.intro.advanced.callback">controlling error generation</link> + </para> </listitem> </itemizedlist> </para> <para> - PEAR_ErrorStack implements error raising and handling using a stack pattern. This has tremendous advantages - over the PEAR_Error Implementation. PEAR_Error centralizes all error creation and handling in the - constructor of the PEAR_Error object. Once an object has been created, all handling must have been - completed, either through checking the return value of a method, or through a single global callback. In addition, - it is nearly impossible to determine the source of an error, and the baggage of all of the PEAR base class's - bulky, slow methods accompanies every error creation. + PEAR_ErrorStack implements error raising and handling using a stack pattern. + + This has tremendous advantages over the PEAR_Error Implementation. + + PEAR_Error centralizes all error creation and handling in the + constructor of the PEAR_Error object. + + Once an object has been created, all handling must have been completed, + either through checking the return value of a method, + or through a single global callback. + + In addition, it is nearly impossible to determine the source of an error, + and the baggage of all of the PEAR base class's bulky, + slow methods accompanies every error creation. </para> <para> <programlisting role = "php"> @@ -64,7 +102,7 @@ $this->display($err->getMessage()); $this->log($err->getMessage()); } - + function log($msg) { error_log($msg, 3, 'somefile.log') @@ -96,8 +134,10 @@ </programlisting> </para> <para> - The PEAR_ErrorStack class has built in knowledge of the <ulink url="&url.pear.package;Log">Log</ulink> package, - can easily differentiate and even automatically re-package errors with little to no difficulty. + The PEAR_ErrorStack class has built in knowledge of the + <ulink url="&url.pear.package;Log">Log</ulink> package, + can easily differentiate and even automatically re-package errors + with little to no difficulty. </para> <para> <programlisting role = "php"><![CDATA[ @@ -117,12 +157,12 @@ function errorCallback($err) { switch($err['package']){ - case 'MyPackage': + case 'MyPackage': // tell the error stack to log the error only // it will not be pushed onto the stack return PEAR_ERRORSTACK_LOG; break; - case 'InternalDbPackage': + case 'InternalDbPackage': // re-package these errors as a mypackage error fit // for enduser consumption $this->_stack->push(MYPACKAGE_ERROR_DBERROR, 'error', @@ -169,31 +209,52 @@ </programlisting> </para> <para> - Why write a new error-handling routine when <link linkend="core.pear.pear-error"><classname>PEAR_Error</classname></link> - already exists? There are several problems with <classname>PEAR_Error</classname>. - Although an error message is present in an error class, processing this error - message automatically is excessively difficult for computers. In addition, - the error message cannot easily be translated once it has been placed into - the <classname>PEAR_Error</classname>. There is also no standard facility for - storing error-related data in the error class. On top of error - message-related issues, there is no way to automatically determine which - package a <classname>PEAR_Error object</classname> - comes from, or the severity of an error. Fatal + Why write a new error-handling routine when + <link linkend="core.pear.pear-error"><classname>PEAR_Error</classname></link> + already exists? + + There are several problems with <classname>PEAR_Error</classname>. + + Although an error message is present in an error class, + processing this error message automatically is excessively + difficult for computers. + + In addition, the error message cannot easily be translated once it has been placed into + the <classname>PEAR_Error</classname>. + + There is also no standard facility for + storing error-related data in the error class. + + On top of error message-related issues, + there is no way to automatically determine which package a + <classname>PEAR_Error</classname> object comes from, + or the severity of an error. + + Fatal errors look exactly the same as non-fatal errors. </para> <para> - The largest flaw with <classname>PEAR_Error object</classname> - is the single-error type design. Every <classname>PEAR_Error object</classname> - is just a <classname>PEAR_Error object</classname>. There is no differentiating - between the severity of an error, or its origin. The - only way to determine the severity is to use PEAR_ERROR_TRIGGER and E_USER_NOTICE/E_USER_WARNING/E_USER_ERROR - constants from php's <ulink url="&url.php.lookup;trigger_error">trigger_error</ulink>. + The largest flaw with <classname>PEAR_Error</classname> object is the + single-error type design. + + Every <classname>PEAR_Error</classname> object is just a + <classname>PEAR_Error</classname> object. + + There is no differentiating between the severity of an error, or its origin. + + The only way to determine the severity is to use + PEAR_ERROR_TRIGGER and E_USER_NOTICE/E_USER_WARNING/E_USER_ERROR + constants from php's + <ulink url="&url.php.lookup;trigger_error">trigger_error</ulink>. + But using this functionality does not justify 900 lines of code, simply because trigger_error() is built into PHP itself! </para> <para> - Now, to start using your newly created error objects, change - all of your <function>PEAR::raiseError</function> or <function>PEAR::throwError</function> + Now, to start using your newly created error objects, + change all of your + <function>PEAR::raiseError</function> + or <function>PEAR::throwError</function> calls from this... </para> <para> @@ -228,8 +289,9 @@ ?>]]> </programlisting> </para> - <para>For basic use, this is all that is needed to use the PEAR_ErrorStack package - in place of PEAR_Error. + <para> + For basic use, this is all that is needed to use the + PEAR_ErrorStack package in place of PEAR_Error. </para> </refsect1> <refsect1 id = "core.pear.pear-errorstack.intro.advanced"> @@ -237,17 +299,28 @@ <refsect2 id = "core.pear.pear-errorstack.intro.advanced.context"> <title>Error Context Display</title> <para> - In some cases, you may want to customize error generation. For instance, for - many exceptions, it is useful to include file, line number, and class/function - context information in order to trace an error. A default option is - available which will be sufficient for most cases, and that - is <link linkend="core.pear.pear-errorstack.getfileline"><function>PEAR_ErrorStack::getFileLine</function></link>. + In some cases, you may want to customize error generation. + For instance, for many exceptions, it is useful to include file, + line number, + and class/function context information in order to trace an error. + + A default option is available which will be sufficient for most cases, + and that is + <link linkend="core.pear.pear-errorstack.getfileline"><function>PEAR_ErrorStack::getFileLine</function></link>. </para> <para> - Not all package errors occur in the PHP source file. For instance, compiling template - engines errors can occur in the template source files. Database errors can occur in the text of a query, - or internal to the database server. Internet package errors can occur on another server. All of this - information can be included in an error message using a context grabbing callback. + Not all package errors occur in the PHP source file. + + For instance, compiling template + engines errors can occur in the template source files. + + Database errors can occur in the text of a query, + or internal to the database server. + + Internet package errors can occur on another server. + + All of this information can be included in an error + message using a context grabbing callback. </para> <para> <programlisting role = "php"><![CDATA[ @@ -282,22 +355,28 @@ </programlisting> </para> <para> - The context information is formatted to be easily processed by an external application. - If you wish context information to be in the error message, the error message callback - should be used to add the information in a human-readable format to the error message, as described + The context information is formatted to be easily + processed by an external application. + + If you wish context information to be in the error message, + the error message callback should be used to add the information + in a human-readable format to the error message, as described in the next section. </para> </refsect2> <refsect2 id = "core.pear.pear-errorstack.intro.advanced.message"> <title>Custom Error Message Generation</title> <para> - There are three methods of PEAR_ErrorStack designed for use with generating - error messages efficiently. To use them, you must do one of two things: + There are three methods of PEAR_ErrorStack designed for + use with generating error messages efficiently. + + To use them, you must do one of two things: <itemizedlist> <listitem> <para> - Call <link linkend="core.pear.pear-errorstack.seterrormessagetemplate"><function>PEAR_ErrorStack::setErrorMessageTemplate</function></link>, and set an array mapping - error codes to error message templates, like so: + Call + <link linkend="core.pear.pear-errorstack.seterrormessagetemplate"><function>PEAR_ErrorStack::setErrorMessageTemplate</function></link>, + and set an array mapping error codes to error message templates, like so: </para> <para> <programlisting role = "php"><![CDATA[ @@ -319,18 +398,24 @@ </programlisting> </para> <para> - Substitution is done using <ulink url="&url.php.lookup;str_replace">str_replace</ulink>, and is very simple. + Substitution is done using + <ulink url="&url.php.lookup;str_replace">str_replace</ulink>, + and is very simple. + Basically, if a variable name is enclosed in percent signs (%), it will - be replaced with the value passed in the associative array. If an array - <programlisting role = "php">array('varname' => 'value');</programlisting> + be replaced with the value passed in the associative array. + + If an array + <programlisting role = "php">array('varname' => 'value');</programlisting> is passed to either method, all occurrences of %varname% will be replaced by value. </para> <para> In addition, if values are objects, the methods will search for a method - named "<function>__toString</function>" and if found, will use that - to convert the object to a string. If an array of strings is passed in, - they will be joined by commas. + named "<function>__toString</function>" and if found, + will use that to convert the object to a string. + + If an array of strings is passed in, they will be joined by commas. <programlisting role = "php"><![CDATA[ <?php array('varname' => array('first', 'second', 'third')); @@ -341,10 +426,15 @@ </listitem> <listitem> <para> - Call <link linkend="core.pear.pear-errorstack.setmessagecallback"><function>PEAR_ErrorStack::setMessageCallback</function></link>, and set a custom error - message generating function or method. This is probably the best option for - the majority of complex situations, as it allows users to override or even - extend the existing error message callback using <link linkend="core.pear.pear-errorstack.getmessagecallback"><function>PEAR_ErrorStack::getMessageCallback</function></link>. + Call + <link linkend="core.pear.pear-errorstack.setmessagecallback"><function>PEAR_ErrorStack::setMessageCallback</function></link>, + and set a custom error message generating function or method. + + This is probably the best option for the majority of complex situations, + as it allows users to override or even extend the existing error + message callback using + <link linkend="core.pear.pear-errorstack.getmessagecallback"><function>PEAR_ErrorStack::getMessageCallback</function></link>. + For example: <programlisting role = "php"><![CDATA[ <?php @@ -369,9 +459,13 @@ </listitem> <listitem> <para> - Extend PEAR_ErrorStack with your own class, and override <link linkend="core.pear.pear-errorstack.geterrormessagetemplate"><function>PEAR_ErrorStack::getErrorMessageTemplate</function></link> or - <link linkend="core.pear.pear-errorstack.geterrormessage"><function>PEAR_ErrorStack::getErrorMessage</function></link>. To guarantee that this class will be used by other - packages/applications, use this code right after the class declaration: + Extend PEAR_ErrorStack with your own class, and override + <link linkend="core.pear.pear-errorstack.geterrormessagetemplate"><function>PEAR_ErrorStack::getErrorMessageTemplate</function></link> + or + <link linkend="core.pear.pear-errorstack.geterrormessage"><function>PEAR_ErrorStack::getErrorMessage</function></link>. + + To guarantee that this class will be used by other packages/applications, + use this code right after the class declaration: </para> <para> <programlisting role = "php"><![CDATA[ @@ -387,16 +481,28 @@ <refsect2 id = "core.pear.pear-errorstack.intro.advanced.callback"> <title>Controlling error generation</title> <para> - There are many scenarios in which fine-grained control over error raising is absolutely necessary. A - generic error handling callback means that every single error raised will be handled in the same error - callback. Although PEAR_ErrorStack is designed to operate with independent callbacks for each package, generic - error handling is possible through the <link linkend="core.pear.pear-errorstack.staticpushcallback"><function>PEAR_ErrorStack::staticPushCallback</function></link> method. This is no different - from PEAR_Error's PEAR_ERROR_CALLBACK error handling mode. + There are many scenarios in which fine-grained control over error raising + is absolutely necessary. + + A generic error handling callback means that every single error + raised will be handled in the same error callback. + + Although PEAR_ErrorStack is designed to operate with independent + callbacks for each package, generic error handling is possible through the + <link linkend="core.pear.pear-errorstack.staticpushcallback"><function>PEAR_ErrorStack::staticPushCallback</function></link> + method. + + This is no different from PEAR_Error's + PEAR_ERROR_CALLBACK error handling mode. </para> <para> - PEAR_ErrorStack's real strength comes from the callback itself. PEAR_Error's callback has no actual - effect on the error message - all error handling must happen in the callback method or function itself. - PEAR_ErrorStack's callback can influence the error through the use of three constants: + PEAR_ErrorStack's real strength comes from the callback itself. + + PEAR_Error's callback has no actual effect on the error message - + all error handling must happen in the callback method or function itself. + + PEAR_ErrorStack's callback can influence the error + through the use of three constants: <itemizedlist> <listitem> <para> @@ -417,7 +523,7 @@ </para> <para> PEAR_ERRORSTACK_IGNORE informs the stack to ignore the error, as if it never occurred. The error will be - neither logged, nor pushed on the stack. It will, however, be returned from <link linkend="core.pear.pear-errorstack.push"><function>PEAR_ErrorStack::push</function></link> + neither logged, nor pushed on the stack. It will, however, be returned from <link linkend="core.pear.pear-errorstack.push"><function>PEAR_ErrorStack::push</function></link> </para> <para> PEAR_ERRORSTACK_PUSH informs the stack to push the error onto the error stack, but not to log the error. @@ -436,13 +542,13 @@ function somecallback($err) { switch($err['code']){ - case ERROR_CODE_ONE: + case ERROR_CODE_ONE: return PEAR_ERRORSTACK_IGNORE; break; - case ERROR_CODE_TWO: + case ERROR_CODE_TWO: return PEAR_ERRORSTACK_PUSH; break; - case ERROR_CODE_THREE: + case ERROR_CODE_THREE: return PEAR_ERRORSTACK_LOG; break; } // switch @@ -474,10 +580,14 @@ <refsect3 id = "core.pear.pear-errorstack.intro.advanced.callback.repackage"> <title>Repackaging errors from one package to another</title> <para> - The most obvious usage for an error callback involves a common scenario in many user-level applications - that use system-level packages. If you write a Content Management System (CMS) with the PEAR DB package, - it is usually a bad idea to display database-level errors when a user clicks on a link to add a message to - a forum. PEAR_ErrorStack can be used to repackage this error as a MyPackage error. + The most obvious usage for an error callback involves a common scenario + in many user-level applications that use system-level packages. + + If you write a Content Management System (CMS) with the PEAR DB package, + it is usually a bad idea to display database-level errors when a user + clicks on a link to add a message to a forum. + + PEAR_ErrorStack can be used to repackage this error as a MyPackage error. </para> <para> <programlisting role = "php"><![CDATA[ @@ -500,8 +610,12 @@ <refsect3 id = "core.pear.pear-errorstack.intro.advanced.callback.silence"> <title>Emulating the @ operator</title> <para> - One of the difficult-to-use strengths of PEAR_Error involves the <link linkend="core.pear.pear.expecterror"><function>PEAR::expectError</function></link> - method. With regular PHP errors, it is possible to silence them using the @ operator like so: + One of the difficult-to-use strengths of PEAR_Error involves the + <link linkend="core.pear.pear.expecterror"><function>PEAR::expectError</function></link> + method. + + With regular PHP errors, it is possible to silence them using + the @ operator like so: </para> <para> <programlisting role = "php"><![CDATA[ @@ -530,8 +644,11 @@ </programlisting> </para> <para> - PEAR_ErrorStack can take this one step further, and only log errors or only put errors on the error stack, - using the other two constants. Finally, particular errors can be singled out, and all others ignored. + PEAR_ErrorStack can take this one step further, + and only log errors or only put errors on the error stack, + using the other two constants. + + Finally, particular errors can be singled out, and all others ignored. </para> <para> <programlisting role = "php"><![CDATA[ @@ -559,10 +676,15 @@ </refsect2> </refsect1> <refsect1 id = "core.pear.pear-errorstack.intro.merging"> - <title>Backwards compatibility with PEAR_Error, Forward compatibility with PHP 5 Exception</title> - <para> - <classname>PEAR_ErrorStack</classname> can also be programmed to automatically raise a PEAR_Error - using <link linkend="core.pear.pear.raiseerror"><function>PEAR::raiseError</function></link>, simply pass in true to the PEAR_Error compatibility like so: + <title> + Backwards compatibility with PEAR_Error, + Forward compatibility with PHP 5 Exception + </title> + <para> + <classname>PEAR_ErrorStack</classname> + can also be programmed to automatically raise a PEAR_Error using + <link linkend="core.pear.pear.raiseerror"><function>PEAR::raiseError</function></link>, + simply pass in true to the PEAR_Error compatibility like so: </para> <para> <programlisting role = "php"><![CDATA[ @@ -575,12 +697,17 @@ <warning> <title>Backward Compatibility break</title> <para> - As of PEAR 1.3.2, PEAR_ErrorStack->push() no longer returns an exception class. Code that relies on this behavior will not work + As of PEAR 1.3.2, PEAR_ErrorStack->push() + no longer returns an exception class. + + Code that relies on this behavior will not work </para> </warning> <para> - PEAR_ErrorStack will return an exception automatically in PHP 5. You can set the exception class name that will - be returned using the following code: + PEAR_ErrorStack will return an exception automatically in PHP 5. + + You can set the exception class name that will be returned + using the following code: </para> <para> <programlisting role = "php"><![CDATA[