cvs: peardoc /en/core pear.xml /en/core/pear pear-error.xml pear-errorstack.xml pear-exception.xml /en/core/pear/pear-exception intro.xml
| From: | Greg Beaver | Date: | Thu, 12 Oct 2006 21:15:50 +0000 |
| Subject: | cvs: peardoc /en/core pear.xml /en/core/pear pear-error.xml pear-errorstack.xml pear-exception.xml /en/core/pear/pear-exception intro.xml | ||
| Groups: | php.pear.doc | ||
| Request: | Send a blank email to pear-doc+get-8601@lists.php.net to get a copy of this message | ||
cellog Thu Oct 12 21:15:50 2006 UTC
Added files:
/peardoc/en/core/pear pear-exception.xml
/peardoc/en/core/pear/pear-exception intro.xml
Modified files:
/peardoc/en/core pear.xml
/peardoc/en/core/pear pear-error.xml pear-errorstack.xml
Log:
add rudimentary docs for PEAR_Exception, re-organize docs on error handling
http://cvs.php.net/viewvc.cgi/peardoc/en/core/pear.xml?r1=1.5&r2=1.6&diff_format=u Index: peardoc/en/core/pear.xml diff -u peardoc/en/core/pear.xml:1.5 peardoc/en/core/pear.xml:1.6 --- peardoc/en/core/pear.xml:1.5 Sat Mar 20 07:40:34 2004 +++ peardoc/en/core/pear.xml Thu Oct 12 21:15:49 2006 @@ -1,4 +1,4 @@ -<!-- $Revision: 1.5 $ --> +<!-- $Revision: 1.6 $ --> <chapter id="core.pear"> <title>PEAR base classes</title> @@ -8,8 +8,9 @@ </para> &core.pear.pear; - &core.pear.pear-error; + &core.pear.pear-exception; &core.pear.pear-errorstack; + &core.pear.pear-error; &core.pear.system; </chapter> <!-- Keep this comment at the end of the file http://cvs.php.net/viewvc.cgi/peardoc/en/core/pear/pear-error.xml?r1=1.4&r2=1.5&diff_format=u Index: peardoc/en/core/pear/pear-error.xml diff -u peardoc/en/core/pear/pear-error.xml:1.4 peardoc/en/core/pear/pear-error.xml:1.5 --- peardoc/en/core/pear/pear-error.xml:1.4 Tue Oct 14 22:53:59 2003 +++ peardoc/en/core/pear/pear-error.xml Thu Oct 12 21:15:49 2006 @@ -1,7 +1,7 @@ -<!-- $Revision: 1.4 $ --> -<!-- $Id: pear-error.xml,v 1.4 2003/10/14 22:53:59 thierry_bo Exp $ --> +<!-- $Revision: 1.5 $ --> +<!-- $Id: pear-error.xml,v 1.5 2006/10/12 21:15:49 cellog Exp $ --> <sect1 id="core.pear.pear-error"> - <title>PEAR_Error</title> + <title>PEAR_Error [deprecated]</title> <titleabbrev>PEAR Error object</titleabbrev> <para> http://cvs.php.net/viewvc.cgi/peardoc/en/core/pear/pear-errorstack.xml?r1=1.4&r2=1.5&diff_format=u Index: peardoc/en/core/pear/pear-errorstack.xml diff -u peardoc/en/core/pear/pear-errorstack.xml:1.4 peardoc/en/core/pear/pear-errorstack.xml:1.5 --- peardoc/en/core/pear/pear-errorstack.xml:1.4 Thu Oct 12 20:39:28 2006 +++ peardoc/en/core/pear/pear-errorstack.xml Thu Oct 12 21:15:49 2006 @@ -1,11 +1,11 @@ -<!-- $Revision: 1.4 $ --> +<!-- $Revision: 1.5 $ --> <sect1 id="core.pear.pear-errorstack"> - <title>Intelligent Error Handling with PEAR_ErrorStack</title> + <title>PEAR_ErrorStack</title> <titleabbrev>PEAR_ErrorStack</titleabbrev> <para> PEAR_ErrorStack is an experimental error raising and handling implementation for PEAR that is designed to replace PEAR_Error when it has stabilized. PEAR_ErrorStack is both backwards compatible with PEAR_Error - and forward compatible with PHP 5's Exception class. There are many other features, all described + and forward compatible with PHP 5's PEAR_Exception class. There are many other features, all described in the Introduction. </para> <para>Usage: http://cvs.php.net/viewvc.cgi/peardoc/en/core/pear/pear-exception.xml?view=markup&rev=1.1 Index: peardoc/en/core/pear/pear-exception.xml +++ peardoc/en/core/pear/pear-exception.xml <!-- $Revision: 1.1 $ --> <sect1 id="core.pear.pear-exception"> <title>PEAR_Exception - PHP 5+</title> <titleabbrev>PEAR_Exception</titleabbrev> <para> PEAR_Exception is the recommended error handling solution for PHP 5-based packages in PEAR. PEAR_Exception is a lightweight wrapper above the built-in <classname>Exception</classname> class in PHP 5 that provides the ability to specify causes for errors, register observers, and many more features. </para> <para>Example usage (demonstration only, not recommended practice): <programlisting role="php"> <![CDATA[ <?php require_once 'PEAR/Exception.php'; class MyPackage_Exception extends PEAR_Exception {} try { throw new PEAR_Exception('exception 1'); } catch (MyPackage_Exception $e) { echo 'this is not executed'; } catch (PEAR_Exception $e) { echo 'this is executed'; } try { throw new MyPackage_Exception('exception 2'); } catch (MyPackage_Exception $e) { echo 'this is executed'; } catch (PEAR_Exception $e) { echo 'this is not executed'; } ?> ]]> </programlisting> </para> <para> Exceptions in general should be used only for exceptional circumstances - for error conditions that require termination of execution. PEAR_Exception should mainly be used for transmitting error information outside the existing package, and not for normal flow control. Use <ulink url="&url.php.manual;en/language.control-structures.php"> Control Structures</ulink> in favor of exceptions wherever possible. </para> &core.pear.pear-exception.intro; </sect1> <!-- 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: vim600: syn=xml fen fdm=syntax fdl=2 si vim: et tw=78 syn=sgml vi: ts=1 sw=1 --> http://cvs.php.net/viewvc.cgi/peardoc/en/core/pear/pear-exception/intro.xml?view=markup&rev=1.1 Index: peardoc/en/core/pear/pear-exception/intro.xml +++ peardoc/en/core/pear/pear-exception/intro.xml <!-- $Revision: 1.1 $ --> <refentry id="core.pear.pear-exception.intro"> <refnamediv> <refname> Using PEAR_Exception for advanced error handlingin PHP 5+ </refname> <refpurpose> Using PEAR_Exception </refpurpose> </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> <author> <firstname>Gregory</firstname> <surname>Beaver</surname> <authorblurb><para>cellog@php.net</para></authorblurb> </author> <copyright> <year>2006</year> <holder>Gregory Beaver</holder> </copyright> <releaseinfo>PEAR_Exception PEAR 1.5.0a1</releaseinfo> </refsynopsisdivinfo> <simpara>Introduction to the usage of PEAR_Exception</simpara> </refsynopsisdiv> <refsect1 id="core.pear.pear-exception.intro.intro"> <title>Introduction</title> <para> This class is available as part of the <ulink url="&url.pear.package;pear">PEAR package</ulink>. Features include: <itemizedlist> <listitem> <para> Nestable exceptions (<programlisting role="php"><![CDATA[ <?php throw new PEAR_Exception($msg, $prev_exception); ?>]]></programlisting>) </para> </listitem> <listitem> <para> Subject/Observer pattern, triggered when an exception is instantiated </para> </listitem> <listitem> <para> Clear, detailed and attractively formatted error messages </para> </listitem> <listitem> <para> Extra context information available compared to built-in Exception. For instance, a cause of the exception (PEAR_Error/PEAR_ErrorStack/another Exception). </para> </listitem> <listitem> <para> Exception cause can be a PEAR_Error object, PEAR_Exception object or an array of mixed PEAR_Exceptions/PEAR_ErrorStack warnings </para> </listitem> <listitem> <para> callbacks for specific exception classes and their children </para> </listitem> </itemizedlist> </para> <para> Usage example: <programlisting role="php"> <![CDATA[ <?php require_once 'PEAR/Exception.php'; class Test { function foo() { throw new PEAR_Exception('Error Message', ERROR_CODE); } } function myLogger($pear_exception) { echo $pear_exception->getMessage(); } // each time a exception is thrown the 'myLogger' will be called // (its use is completely optional) PEAR_Exception::addObserver('myLogger'); $test = new Test; try { $test->foo(); } catch (PEAR_Exception $e) { print $e; } ?> ]]> </programlisting> </para> <para> API documentation is documented in the documentation for the PEAR package generated by phpDocumentor. The class is very simple, examine the source in the PEAR package to get a better idea of how it works. </para> </refsect1> </refentry> <!-- Keep this comment at the end of the file Local variables: mode: sgml sgml-omittag:t sgml-shorttag:t sgml-minimize-attributes:nil sgml-always-quote-attributes:t sgml-indent-step:1 sgml-indent-data:t sgml-parent-document:nil sgml-default-dtd-file:"../../../../manual.ced" sgml-exposed-tags:nil sgml-local-catalogs:nil sgml-local-ecat-files:nil End: vim600: syn=xml fen fdm=syntax fdl=2 si vim: et tw=78 syn=sgml vi: ts=1 sw=1 -->
http://cvs.php.net/viewvc.cgi/peardoc/en/core/pear.xml?r1=1.5&r2=1.6&diff_format=u Index: peardoc/en/core/pear.xml diff -u peardoc/en/core/pear.xml:1.5 peardoc/en/core/pear.xml:1.6 --- peardoc/en/core/pear.xml:1.5 Sat Mar 20 07:40:34 2004 +++ peardoc/en/core/pear.xml Thu Oct 12 21:15:49 2006 @@ -1,4 +1,4 @@ -<!-- $Revision: 1.5 $ --> +<!-- $Revision: 1.6 $ --> <chapter id="core.pear"> <title>PEAR base classes</title> @@ -8,8 +8,9 @@ </para> &core.pear.pear; - &core.pear.pear-error; + &core.pear.pear-exception; &core.pear.pear-errorstack; + &core.pear.pear-error; &core.pear.system; </chapter> <!-- Keep this comment at the end of the file http://cvs.php.net/viewvc.cgi/peardoc/en/core/pear/pear-error.xml?r1=1.4&r2=1.5&diff_format=u Index: peardoc/en/core/pear/pear-error.xml diff -u peardoc/en/core/pear/pear-error.xml:1.4 peardoc/en/core/pear/pear-error.xml:1.5 --- peardoc/en/core/pear/pear-error.xml:1.4 Tue Oct 14 22:53:59 2003 +++ peardoc/en/core/pear/pear-error.xml Thu Oct 12 21:15:49 2006 @@ -1,7 +1,7 @@ -<!-- $Revision: 1.4 $ --> -<!-- $Id: pear-error.xml,v 1.4 2003/10/14 22:53:59 thierry_bo Exp $ --> +<!-- $Revision: 1.5 $ --> +<!-- $Id: pear-error.xml,v 1.5 2006/10/12 21:15:49 cellog Exp $ --> <sect1 id="core.pear.pear-error"> - <title>PEAR_Error</title> + <title>PEAR_Error [deprecated]</title> <titleabbrev>PEAR Error object</titleabbrev> <para> http://cvs.php.net/viewvc.cgi/peardoc/en/core/pear/pear-errorstack.xml?r1=1.4&r2=1.5&diff_format=u Index: peardoc/en/core/pear/pear-errorstack.xml diff -u peardoc/en/core/pear/pear-errorstack.xml:1.4 peardoc/en/core/pear/pear-errorstack.xml:1.5 --- peardoc/en/core/pear/pear-errorstack.xml:1.4 Thu Oct 12 20:39:28 2006 +++ peardoc/en/core/pear/pear-errorstack.xml Thu Oct 12 21:15:49 2006 @@ -1,11 +1,11 @@ -<!-- $Revision: 1.4 $ --> +<!-- $Revision: 1.5 $ --> <sect1 id="core.pear.pear-errorstack"> - <title>Intelligent Error Handling with PEAR_ErrorStack</title> + <title>PEAR_ErrorStack</title> <titleabbrev>PEAR_ErrorStack</titleabbrev> <para> PEAR_ErrorStack is an experimental error raising and handling implementation for PEAR that is designed to replace PEAR_Error when it has stabilized. PEAR_ErrorStack is both backwards compatible with PEAR_Error - and forward compatible with PHP 5's Exception class. There are many other features, all described + and forward compatible with PHP 5's PEAR_Exception class. There are many other features, all described in the Introduction. </para> <para>Usage: http://cvs.php.net/viewvc.cgi/peardoc/en/core/pear/pear-exception.xml?view=markup&rev=1.1 Index: peardoc/en/core/pear/pear-exception.xml +++ peardoc/en/core/pear/pear-exception.xml <!-- $Revision: 1.1 $ --> <sect1 id="core.pear.pear-exception"> <title>PEAR_Exception - PHP 5+</title> <titleabbrev>PEAR_Exception</titleabbrev> <para> PEAR_Exception is the recommended error handling solution for PHP 5-based packages in PEAR. PEAR_Exception is a lightweight wrapper above the built-in <classname>Exception</classname> class in PHP 5 that provides the ability to specify causes for errors, register observers, and many more features. </para> <para>Example usage (demonstration only, not recommended practice): <programlisting role="php"> <![CDATA[ <?php require_once 'PEAR/Exception.php'; class MyPackage_Exception extends PEAR_Exception {} try { throw new PEAR_Exception('exception 1'); } catch (MyPackage_Exception $e) { echo 'this is not executed'; } catch (PEAR_Exception $e) { echo 'this is executed'; } try { throw new MyPackage_Exception('exception 2'); } catch (MyPackage_Exception $e) { echo 'this is executed'; } catch (PEAR_Exception $e) { echo 'this is not executed'; } ?> ]]> </programlisting> </para> <para> Exceptions in general should be used only for exceptional circumstances - for error conditions that require termination of execution. PEAR_Exception should mainly be used for transmitting error information outside the existing package, and not for normal flow control. Use <ulink url="&url.php.manual;en/language.control-structures.php"> Control Structures</ulink> in favor of exceptions wherever possible. </para> &core.pear.pear-exception.intro; </sect1> <!-- 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: vim600: syn=xml fen fdm=syntax fdl=2 si vim: et tw=78 syn=sgml vi: ts=1 sw=1 --> http://cvs.php.net/viewvc.cgi/peardoc/en/core/pear/pear-exception/intro.xml?view=markup&rev=1.1 Index: peardoc/en/core/pear/pear-exception/intro.xml +++ peardoc/en/core/pear/pear-exception/intro.xml <!-- $Revision: 1.1 $ --> <refentry id="core.pear.pear-exception.intro"> <refnamediv> <refname> Using PEAR_Exception for advanced error handlingin PHP 5+ </refname> <refpurpose> Using PEAR_Exception </refpurpose> </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> <author> <firstname>Gregory</firstname> <surname>Beaver</surname> <authorblurb><para>cellog@php.net</para></authorblurb> </author> <copyright> <year>2006</year> <holder>Gregory Beaver</holder> </copyright> <releaseinfo>PEAR_Exception PEAR 1.5.0a1</releaseinfo> </refsynopsisdivinfo> <simpara>Introduction to the usage of PEAR_Exception</simpara> </refsynopsisdiv> <refsect1 id="core.pear.pear-exception.intro.intro"> <title>Introduction</title> <para> This class is available as part of the <ulink url="&url.pear.package;pear">PEAR package</ulink>. Features include: <itemizedlist> <listitem> <para> Nestable exceptions (<programlisting role="php"><![CDATA[ <?php throw new PEAR_Exception($msg, $prev_exception); ?>]]></programlisting>) </para> </listitem> <listitem> <para> Subject/Observer pattern, triggered when an exception is instantiated </para> </listitem> <listitem> <para> Clear, detailed and attractively formatted error messages </para> </listitem> <listitem> <para> Extra context information available compared to built-in Exception. For instance, a cause of the exception (PEAR_Error/PEAR_ErrorStack/another Exception). </para> </listitem> <listitem> <para> Exception cause can be a PEAR_Error object, PEAR_Exception object or an array of mixed PEAR_Exceptions/PEAR_ErrorStack warnings </para> </listitem> <listitem> <para> callbacks for specific exception classes and their children </para> </listitem> </itemizedlist> </para> <para> Usage example: <programlisting role="php"> <![CDATA[ <?php require_once 'PEAR/Exception.php'; class Test { function foo() { throw new PEAR_Exception('Error Message', ERROR_CODE); } } function myLogger($pear_exception) { echo $pear_exception->getMessage(); } // each time a exception is thrown the 'myLogger' will be called // (its use is completely optional) PEAR_Exception::addObserver('myLogger'); $test = new Test; try { $test->foo(); } catch (PEAR_Exception $e) { print $e; } ?> ]]> </programlisting> </para> <para> API documentation is documented in the documentation for the PEAR package generated by phpDocumentor. The class is very simple, examine the source in the PEAR package to get a better idea of how it works. </para> </refsect1> </refentry> <!-- Keep this comment at the end of the file Local variables: mode: sgml sgml-omittag:t sgml-shorttag:t sgml-minimize-attributes:nil sgml-always-quote-attributes:t sgml-indent-step:1 sgml-indent-data:t sgml-parent-document:nil sgml-default-dtd-file:"../../../../manual.ced" sgml-exposed-tags:nil sgml-local-catalogs:nil sgml-local-ecat-files:nil End: vim600: syn=xml fen fdm=syntax fdl=2 si vim: et tw=78 syn=sgml vi: ts=1 sw=1 -->