cvs: pearweb /public_html/doc pear.html pear.xml

From:	Stig Bakken	Date:	Mon, 04 Dec 2000 17:49:34 +0000
Subject:	cvs: pearweb /public_html/doc pear.html pear.xml
Groups:	php.pear
Request:	Send a blank email to php-pear+get-486@lists.php.net to get a copy of this message

ssb Mon Dec 4 09:49:34 2000 EDT Modified files: /pearweb/public_html/doc pear.html pear.xml Log: * added a section about errors

Index: pearweb/public_html/doc/pear.html diff -u pearweb/public_html/doc/pear.html:1.4 pearweb/public_html/doc/pear.html:1.5 --- pearweb/public_html/doc/pear.html:1.4 Mon Jul 17 15:54:39 2000 +++ pearweb/public_html/doc/pear.html Mon Dec 4 09:49:34 2000 @@ -1,11 +1,14 @@ <HTML ><HEAD ><TITLE ->PEAR: PHP Extension and Add-on Repository</TITLE +>PEAR: PHP Extension and Application Repository</TITLE ><META NAME="GENERATOR" -CONTENT="Modular DocBook HTML Stylesheet Version 1.44"></HEAD +CONTENT="Modular DocBook HTML Stylesheet Version 1.52"><META +NAME="HTTP_EQUIV" +CONTENT="text/html; charset=ISO-8859-1"></HEAD ><BODY +CLASS="article" BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" @@ -19,11 +22,20 @@ CLASS="title" ><A NAME="AEN2" ->PEAR: PHP Extension and Add-on Repository</A +>PEAR: PHP Extension and Application Repository</A ></H1 +><DIV +CLASS="authorgroup" +><A +NAME="AEN4" +></A ><H3 CLASS="author" ->Stig Bakken</H3 +><A +NAME="AEN5" +>Stig Bakken</A +></H3 +></DIV ><SPAN CLASS="releaseinfo" > @@ -45,10 +57,10 @@ ><TR ><TD ALIGN="LEFT" ->Revision $Revision: 1.4 $</TD +>Revision $Revision: 1.5 $</TD ><TD ALIGN="LEFT" ->$Date: 2000/07/17 22:54:39 $</TD +>$Date: 2000/12/04 17:49:34 $</TD ><TD ALIGN="LEFT" >Revised by: $Author: ssb $</TD @@ -63,7 +75,12 @@ ></DIV ><HR></DIV ><P ->PEAR is dedicated to Malin Bakken, born 1999-11-21.</P +>PEAR is dedicated to <A +HREF="http://www.pvv.org/~ssb/malin/bilder/mi/twain001.jpg" +TARGET="_top" +>Malin Bakken</A +>, born + 1999-11-21.</P ><DIV CLASS="section" ><HR><H1 @@ -122,8 +139,7 @@ >Note: </B > It is important that your files do not output anything, so watch - those extra linefeeds at the end of the files (no more than - one!) + those linefeeds at the end of files (no more than one!) </P ></BLOCKQUOTE ></DIV @@ -279,9 +295,8 @@ ><TD ><PRE CLASS="programlisting" -> 1  - 2 Header("Last-Modified: " . HTTP::Date(getlastmod())); - 3 </PRE +>Header("Last-Modified: " . HTTP::Date(getlastmod())); +</PRE ></TD ></TR ></TABLE @@ -313,7 +328,7 @@ ><HR><H2 CLASS="section" ><A -NAME="AEN63" +NAME="pear-variables" >Variable Names</A ></H2 ><P @@ -337,15 +352,14 @@ ><TD ><PRE CLASS="programlisting" -> 1  - 2 <?php - 3  - 4 $Gah_Zonk_errorcodes = array( -1 => "This error", - 5  -2 => "That error" ); - 6 $_Gah_Zonk_cache = array(); - 7  - 8 ?> - 9 </PRE +><?php + +$Gah_Zonk_errorcodes = array( -1 => "This error", + -2 => "That error" ); +$_Gah_Zonk_cache = array(); + +?> +</PRE ></TD ></TR ></TABLE @@ -377,8 +391,138 @@ and what, be it as simple as returning an error code, or something more fancy. </P +><P +> Fortunately, PEAR a general mechanism for reporting errors. An + error is "raised" by creating an error object that may be used as + the return value of a function/method. I say "may be used" + because PEAR errors have several modes of operation: simply + returning an object with more information, printing the error (and + optionally exit), call PHP's internal error handling functions, or + invoke a callback function. + </P +><P +> Use the PEAR::isError() function to determine whether a returned + value is a PEAR error. + </P +><P +> The following example makes an error wrapper around PHP's built-in + <B +CLASS="function" +>fsockopen()</B +> function following PEAR + conventions. + <TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +CLASS="EXAMPLE" +><TR +><TD +><DIV +CLASS="example" +><P +><B +>Example 1. PEAR error example 1</B +></P +><TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +WIDTH="100%" +><TR +><TD +><PRE +CLASS="programlisting" +><?php + +// PEAR_Error is defined in PEAR.php +require_once 'PEAR.php'; + +function myfsockopen($host, $port) { + $fp = @fsockopen($host, $port, &$errno, &$errstr, 10); + if (!$fp) { + return new PEAR_Error($errstr, $errno, PEAR_ERROR_RETURN, null, + "$host:$port"); + } + return $fp; +} + +$sock = myfsockopen("www.php.net", 80); +if (PEAR::isError($sock)) { + print "<B>Error: ".$sock->getMessage()."</B>\n"; +} + +?> +</PRE +></TD +></TR +></TABLE ></DIV +></TD +></TR +></TABLE +> + </P +><P +> You can customize the error handling by subclassing + <TT +CLASS="classname" +>PEAR_Error</TT +> and adding your own stuff on top + of that, <B +CLASS="function" +>PEAR::isError()</B +> will return true for + any object that is an instance of + <TT +CLASS="classname" +>PEAR_Error</TT +> or a class inheriting it. + </P +><P +> Some PEAR classes already do this, such as the DB error class, + <TT +CLASS="classname" +>DB_Error</TT +>: + <TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +CLASS="EXAMPLE" +><TR +><TD ><DIV +CLASS="example" +><P +><B +>Example 2. DB_Error example</B +></P +><TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +WIDTH="100%" +><TR +><TD +><PRE +CLASS="programlisting" +><?php + + +?> +</PRE +></TD +></TR +></TABLE +></DIV +></TD +></TR +></TABLE +> + </P +></DIV +><DIV CLASS="section" ><HR><H2 CLASS="section" @@ -414,12 +558,11 @@ ><TD ><PRE CLASS="programlisting" -> 1  - 2 // If magic_quotes_gpc is enabled, remove those slashes. - 3 if (ini_get("magic_quotes_gpc")) { - 4  $arg = stripslashes($arg); - 5 } - 6 </PRE +>// If magic_quotes_gpc is enabled, remove those slashes. +if (ini_get("magic_quotes_gpc")) { + $arg = stripslashes($arg); +} +</PRE ></TD ></TR ></TABLE @@ -524,7 +667,7 @@ CLASS="example" ><P ><B ->Example 1. file1.php</B +>Example 3. file1.php</B ></P ><TABLE BORDER="0" @@ -534,9 +677,8 @@ ><TD ><PRE CLASS="programlisting" -> 1  - 2 <?php $myglobal = 42; ?> - 3 </PRE +><?php $myglobal = 42; ?> +</PRE ></TD ></TR ></TABLE @@ -558,7 +700,7 @@ CLASS="example" ><P ><B ->Example 2. file2.php</B +>Example 4. file2.php</B ></P ><TABLE BORDER="0" @@ -568,19 +710,18 @@ ><TD ><PRE CLASS="programlisting" -> 1  - 2 <?php - 3  - 4 class Foo { - 5  function Foo($arg) { - 6  if ($arg == 42) { - 7  include("file1.php"); - 8  } - 9  } - 10 } - 11  - 12 ?> - 13 </PRE +><?php + +class Foo { + function Foo($arg) { + if ($arg == 42) { + include("file1.php"); + } + } +} + +?> +</PRE ></TD ></TR ></TABLE @@ -600,6 +741,45 @@ >Foo</TT > class's constructor function, not as a global variable. + </P +><P +> The correct/portable way to do this in + <TT +CLASS="filename" +>file1.php</TT +> is: + <TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +CLASS="EXAMPLE" +><TR +><TD +><DIV +CLASS="example" +><P +><B +>Example 5. Correct file1.php</B +></P +><TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +WIDTH="100%" +><TR +><TD +><PRE +CLASS="programlisting" +><?php $GLOBALS['myglobal'] = 42; ?> +</PRE +></TD +></TR +></TABLE +></DIV +></TD +></TR +></TABLE +> </P ></DIV ></DIV Index: pearweb/public_html/doc/pear.xml diff -u pearweb/public_html/doc/pear.xml:1.7 pearweb/public_html/doc/pear.xml:1.8 --- pearweb/public_html/doc/pear.xml:1.7 Tue Aug 1 04:00:35 2000 +++ pearweb/public_html/doc/pear.xml Mon Dec 4 09:49:34 2000 @@ -20,15 +20,15 @@ </releaseinfo> <revhistory> <revision> - <revnumber>$Revision: 1.7 $</revnumber> - <date>$Date: 2000/08/01 11:00:35 $</date> + <revnumber>$Revision: 1.8 $</revnumber> + <date>$Date: 2000/12/04 17:49:34 $</date> <authorinitials>$Author: ssb $</authorinitials> </revision> </revhistory> </artheader> <simpara>PEAR is dedicated to <ulink - url="http://www.pvv.org/~ssb/malin/">Malin Bakken</ulink>, born + url="http://www.pvv.org/~ssb/malin/bilder/mi/twain001.jpg">Malin Bakken</ulink>, born 1999-11-21.</simpara> <section id="pear-whatis"> @@ -177,7 +177,7 @@ </section> </section> - <section> + <section id="pear-variables"> <title>Variable Names</title> <simpara> Global variables visible to the user should be prefixed with the @@ -212,6 +212,69 @@ and what, be it as simple as returning an error code, or something more fancy. </simpara> + <simpara> + Fortunately, PEAR a general mechanism for reporting errors. An + error is "raised" by creating an error object that may be used as + the return value of a function/method. I say "may be used" + because PEAR errors have several modes of operation: simply + returning an object with more information, printing the error (and + optionally exit), call PHP's internal error handling functions, or + invoke a callback function. + </simpara> + <simpara> + Use the PEAR::isError() function to determine whether a returned + value is a PEAR error. + </simpara> + <para> + The following example makes an error wrapper around PHP's built-in + <function>fsockopen</function> function following PEAR + conventions. + <example> + <title>PEAR error example 1</title> + <programlisting role="html"> +<?php + +// PEAR_Error is defined in PEAR.php +require_once 'PEAR.php'; + +function myfsockopen($host, $port) { + $fp = @fsockopen($host, $port, &$errno, &$errstr, 10); + if (!$fp) { + return new PEAR_Error($errstr, $errno, PEAR_ERROR_RETURN, null, + "$host:$port"); + } + return $fp; +} + +$sock = myfsockopen("www.php.net", 80); +if (PEAR::isError($sock)) { + print "<B>Error: ".$sock->getMessage()."</B>\n"; +} + +?> +</programlisting> + </example> + </para> + <para> + You can customize the error handling by subclassing + <classname>PEAR_Error</classname> and adding your own stuff on top + of that, <function>PEAR::isError</function> will return true for + any object that is an instance of + <classname>PEAR_Error</classname> or a class inheriting it. + </para> + <para> + Some PEAR classes already do this, such as the DB error class, + <classname>DB_Error</classname>: + <example> + <title>DB_Error example</title> + <programlisting role="html"> +<?php + + +?> +</programlisting> + </example> + </para> </section> <section id="pear-options"> @@ -307,6 +370,16 @@ function, not as a global variable. </simpara> + <para> + The correct/portable way to do this in + <filename>file1.php</filename> is: + <example> + <title>Correct file1.php</title> + <programlisting role="html"> +<?php $GLOBALS['myglobal'] = 42; ?> +</programlisting> + </example> + </para> </section> </section>