ssb Wed Mar 7 18:45:54 2001 EDT
Added files:
/phpdoc/en/pear about.xml standards.xml
Modified files:
/phpdoc global.ent html-common.dsl manual.xml.in
/phpdoc/en language-defs.ent
/phpdoc/en/pear pear.xml
Log:
* more PEAR docs
Index: phpdoc/global.ent
diff -u phpdoc/global.ent:1.80 phpdoc/global.ent:1.81
--- phpdoc/global.ent:1.80 Wed Mar 7 00:36:01 2001
+++ phpdoc/global.ent Wed Mar 7 18:45:53 2001
@@ -1,6 +1,6 @@
<!-- -*- SGML -*-
- $Id: global.ent,v 1.80 2001/03/07 08:36:01 jmcastagnetto Exp $
+ $Id: global.ent,v 1.81 2001/03/08 02:45:53 ssb Exp $
Contains global "macros" for all the SGML documents.
@@ -64,6 +64,7 @@
<!ENTITY url.ldap.openldap-c-api
"http://www.openldap.org/devel/cvsweb.cgi/~checkout~/doc/drafts/draft-ietf-ldapext-ldap-c-api-xx.txt">
<!ENTITY url.levenshtein.demo "http://odur.let.rug.nl/~kleiweg/lev/">
<!ENTITY url.lightyear "http://homepage.mac.com/LightyearDesign/MacOSX/Packages/">
+<!ENTITY url.malinimg "http://www.pvv.org/~ssb/malin/bilder/mi/twain001.jpg">
<!ENTITY url.mcal "http://mcal.chek.com/">
<!ENTITY url.mcrypt "ftp://mcrypt.hellug.gr/pub/mcrypt/libmcrypt">
<!ENTITY url.mersenne "http://www.math.keio.ac.jp/~matumoto/emt.html">
@@ -97,6 +98,7 @@
<!ENTITY url.php.docs "http://www.php.net/docs.php">
<!ENTITY url.php.stats "../images/phpstats-200002.gif">
<!ENTITY url.php.snaps.manual "http://snaps.php.net/manual/">
+<!ENTITY url.phpdoc 'http://www.phpdoc.de/'>
<!ENTITY url.pgsql "http://www.postgresql.org/">
<!ENTITY url.pspell "http://pspell.sourceforge.net/">
<!ENTITY url.qmail "http://www.qmail.org/">
Index: phpdoc/html-common.dsl
diff -u phpdoc/html-common.dsl:1.7 phpdoc/html-common.dsl:1.8
--- phpdoc/html-common.dsl:1.7 Sun May 14 08:30:26 2000
+++ phpdoc/html-common.dsl Wed Mar 7 18:45:53 2001
@@ -1,6 +1,6 @@
;; -*- Scheme -*-
;;
-;; $Id: html-common.dsl,v 1.7 2000/05/14 15:30:26 hholzgra Exp $
+;; $Id: html-common.dsl,v 1.8 2001/03/08 02:45:53 ssb Exp $
;;
;; Returns the depth of the auto-generated TOC (table of contents) that
@@ -17,50 +17,47 @@
(element (funcdef function)
- ($bold-seq$
- (make sequence
- (process-children)
- )
- )
- )
-
-
+ ($bold-seq$
+ (make sequence
+ (process-children)
+ )
+ )
+ )
-
-
(define (is-true-optional nl)
- (and (equal? (gi (parent nl)) (normalize "parameter"))
- (equal? 0 (string-length (strip (data (preced nl)))))
- (equal? 0 (string-length (strip (data (follow nl)))))
- )
- )
+ (and (equal? (gi (parent nl)) (normalize "parameter"))
+ (equal? 0 (string-length (strip (data (preced nl)))))
+ (equal? 0 (string-length (strip (data (follow nl)))))
+ )
+ )
+
(define (has-true-optional nl)
- (is-true-optional
- (node-list-first-element
- (select-elements
- (descendants nl)
- (normalize "optional"))
- )
- )
- )
+ (is-true-optional
+ (node-list-first-element
+ (select-elements
+ (descendants nl)
+ (normalize "optional"))
+ )
+ )
+ )
(define (count-true-optionals nl)
- (let loop
- ((result 0)
- (nl (select-elements (descendants nl) (normalize "optional")))
- )
- (if(node-list-empty? nl)
- result
- (if(is-true-optional(node-list-first nl))
- (loop (+ result 1) (node-list-rest nl))
- (loop result (node-list-rest nl))
- )
- )
- )
- )
+ (let loop
+ ((result 0)
+ (nl (select-elements (descendants nl) (normalize "optional")))
+ )
+ (if(node-list-empty? nl)
+ result
+ (if(is-true-optional(node-list-first nl))
+ (loop (+ result 1) (node-list-rest nl))
+ (loop result (node-list-rest nl))
+ )
+ )
+ )
+ )
;; there are two different kinds of optionals
@@ -69,90 +66,91 @@
;; with a parameter tag as its parent
;; and only whitespace between them
(element optional
- ;;check for true optional parameter
- (if (is-true-optional (current-node))
- ;; yes - handle '[...]' in paramdef
- (process-children-trim)
- ;; no - do '[...]' output
- (make sequence
- (literal %arg-choice-opt-open-str%)
- (process-children-trim)
- (literal %arg-choice-opt-close-str%)
- )
- )
- )
+ ;;check for true optional parameter
+ (if (is-true-optional (current-node))
+ ;; yes - handle '[...]' in paramdef
+ (process-children-trim)
+ ;; no - do '[...]' output
+ (make sequence
+ (literal %arg-choice-opt-open-str%)
+ (process-children-trim)
+ (literal %arg-choice-opt-close-str%)
+ )
+ )
+ )
(element (paramdef parameter)
- (make sequence
+ (make sequence
font-posture: 'italic
- (process-children-trim)
- )
- )
+ (process-children-trim)
+ )
+ )
;; now this is going to be tricky
(element paramdef
(make sequence
- ;; special treatment for first parameter in funcsynopsis
+ ;; special treatment for first parameter in funcsynopsis
(if (equal? (child-number (current-node)) 1)
- ;; is first ?
- (make sequence
- ;; start parameter list
- (literal " (")
- ;; is optional ?
- ( if (has-true-optional (current-node))
- (literal
%arg-choice-opt-open-str%)
- (empty-sosofo)
- )
- )
- ;; not first
- (empty-sosofo)
- )
-
- ;;
+ ;; is first ?
+ (make sequence
+ ;; start parameter list
+ (literal " (")
+ ;; is optional ?
+ ( if (has-true-optional (current-node))
+ (literal %arg-choice-opt-open-str%)
+ (empty-sosofo)
+ )
+ )
+ ;; not first
+ (empty-sosofo)
+ )
+
+ ;;
(process-children-trim)
-
- ;; special treatment for last parameter
+
+ ;; special treatment for last parameter
(if (equal? (gi (ifollow (current-node))) (normalize "paramdef"))
- ;; more parameters will follow
- (make sequence
- ;; next is optional ?
- ( if (has-true-optional (ifollow
(current-node)))
- ;; optional
- (make sequence
- (literal " ")
- (literal
%arg-choice-opt-open-str%)
- )
- ;; not optional
- (empty-sosofo)
- )
- (literal ", " )
- )
- ;; last parameter
- (make sequence
- (literal
- (let loop ((result "")(count
(count-true-optionals (parent (current-node)))))
- (if (<= count 0)
- result
- (loop (string-append
result %arg-choice-opt-close-str%)(- count 1))
- )
- )
- )
- ( literal ")" )
- )
- )
- )
- )
-
-
+ ;; more parameters will follow
+ (make sequence
+ ;; next is optional ?
+ ( if (has-true-optional (ifollow (current-node)))
+ ;; optional
+ (make sequence
+ (literal " ")
+ (literal %arg-choice-opt-open-str%)
+ )
+ ;; not optional
+ (empty-sosofo)
+ )
+ (literal ", " )
+
+ )
+ ;; last parameter
+ (make sequence
+ (literal
+ (let loop ((result "")(count (count-true-optionals (parent
+(current-node)))))
+ (if (<= count 0)
+ result
+ (loop (string-append result %arg-choice-opt-close-str%)(- count 1))
+ )
+ )
+ )
+ ( literal ")" )
+ )
+ )
+ )
+ )
(element function
(let* ((function-name (data (current-node)))
- (linkend
- (string-append "function."
-
(string-replace function-name "_" "-")))
- (target (element-with-id linkend))
- (parent-gi (gi (parent))))
+ (linkend
+ (string-append
+ "function."
+ (string-replace
+ (string-replace function-name "_" "-")
+ "::" ".")))
+ (target (element-with-id linkend))
+ (parent-gi (gi (parent))))
(cond
;; function names should be plain in FUNCDEF
((equal? parent-gi "funcdef")
@@ -162,56 +160,130 @@
;; FUNCTION tag is within the definition of the same function,
;; make it bold, add (), but don't make a link
((or (node-list-empty? target)
- (equal? (case-fold-down
- (data
(node-list-first
-
(select-elements
-
(node-list-first
-
(children
-
(select-elements
-
(children
-
(ancestor-member (parent) (list "refentry")))
-
"refnamediv")))
-
"refname"))))
- function-name))
+ (equal? (case-fold-down
+ (data (node-list-first
+ (select-elements
+ (node-list-first
+ (children
+ (select-elements
+ (children
+ (ancestor-member (parent) (list "refentry")))
+ "refnamediv")))
+ "refname"))))
+ function-name))
($bold-seq$
(make sequence
- (process-children)
- (literal "()"))))
+ (process-children)
+ (literal "()"))))
;; else make a link to the function and add ()
(else
(make element gi: "A"
- attributes: (list
-
(list "HREF" (href-to target)))
- ($bold-seq$
- (make sequence
- (process-children)
- (literal
- )
- (literal "()"))))))))
+ attributes: (list
+ (list "HREF" (href-to target)))
+ ($bold-seq$
+ (make sequence
+ (process-children)
+ (literal
+ )
+ (literal "()"))))))))
+(element classname
+ (let* ((class-name (data (current-node)))
+ (linkend
+ (string-append
+ "class."
+ (string-replace
+ (case-fold-down class-name) "_" "-")))
+ (target (element-with-id linkend))
+ (parent-gi (gi (parent))))
+ (cond
+ ;; function names should be plain in SYNOPSIS
+ ((equal? parent-gi "synopsis")
+ (process-children))
+
+ ;; if a valid ID for the target class is not found, or if the
+ ;; CLASSNAME tag is within the definition of the same class,
+ ;; make it bold, but don't make a link
+ ((or (node-list-empty? target)
+ (equal? (case-fold-down
+ (data (node-list-first
+ (select-elements
+ (node-list-first
+ (children
+ (select-elements
+ (children
+ (ancestor-member (parent) (list "refentry")))
+ "refnamediv")))
+ "refname"))))
+ class-name))
+ ($bold-seq$
+ (process-children)))
+
+ ;; else make a link to the function and add ()
+ (else
+ (make element gi: "A"
+ attributes: (list
+ (list "HREF" (href-to target)))
+ ($bold-seq$
+ (process-children)))))))
+(element constant
+ (let* ((constant-name (data (current-node)))
+ (linkend
+ (string-append "constant."
+ (case-fold-down
+ (string-replace constant-name "_" "-"))))
+ (target (element-with-id linkend))
+ (parent-gi (gi (parent))))
+ (cond
+; ;; constant names should be plain in FUNCDEF
+; ((equal? parent-gi "funcdef")
+; (process-children))
+
+ ;; if a valid ID for the target constant is not found, or if the
+ ;; CONSTANT tag is within the definition of the same constant,
+ ;; make it bold, add (), but don't make a link
+ ((or (node-list-empty? target)
+ (equal? (case-fold-down
+ (data (node-list-first
+ (select-elements
+ (node-list-first
+ (children
+ (select-elements
+ (children
+ (ancestor-member (parent) (list "refentry")))
+ "refnamediv")))
+ "refname"))))
+ constant-name))
+ ($bold-mono-seq$
+ (process-children)))
+
+ ;; else make a link to the function and add ()
+ (else
+ (make element gi: "A"
+ attributes: (list
+ (list "HREF" (href-to target)))
+ ($bold-mono-seq$
+ (process-children)))))))
(element example
(make sequence
(make element gi: "TABLE"
- attributes: (list
-
(list "WIDTH" "100%")
-
(list "BORDER" "0")
-
(list "CELLPADDING" "0")
-
(list "CELLSPACING" "0")
-
(list "CLASS" "EXAMPLE"))
- (make element gi: "TR"
- (make element gi: "TD"
-
($formal-object$))))))
-
-
+ attributes: (list
+ (list "WIDTH" "100%")
+ (list "BORDER" "0")
+ (list "CELLPADDING" "0")
+ (list "CELLSPACING" "0")
+ (list "CLASS" "EXAMPLE"))
+ (make element gi: "TR"
+ (make element gi: "TD"
+ ($formal-object$))))))
-
(mode book-titlepage-recto-mode
(element authorgroup
(process-children))
@@ -228,16 +300,15 @@
)
-
(element (refnamediv refname)
- (make sequence
- (make element gi: "P"
- (literal " (")
- (version-info (current-node))
- (literal ")")
- )
- (process-children)
- )
- )
+ (make sequence
+ (make element gi: "P"
+ (literal " (")
+ (version-info (current-node))
+ (literal ")")
+ )
+ (process-children)
+ )
+ )
Index: phpdoc/manual.xml.in
diff -u phpdoc/manual.xml.in:1.55 phpdoc/manual.xml.in:1.56
--- phpdoc/manual.xml.in:1.55 Wed Feb 28 14:04:54 2001
+++ phpdoc/manual.xml.in Wed Mar 7 18:45:53 2001
@@ -146,6 +146,13 @@
&functions.zlib;
</part>
+ <part id="pear">
+ <title>&PEAR;</title>
+ &pear.about;
+ &pear.standards;
+ &pear.pear;
+ </part>
+
<part id="appendixes">
<title>&Appendixes;</title>
&appendices.migration;
Index: phpdoc/en/language-defs.ent
diff -u phpdoc/en/language-defs.ent:1.1 phpdoc/en/language-defs.ent:1.2
--- phpdoc/en/language-defs.ent:1.1 Fri Dec 15 00:58:53 2000
+++ phpdoc/en/language-defs.ent Wed Mar 7 18:45:53 2001
@@ -5,6 +5,6 @@
<!ENTITY Features "Features">
<!ENTITY FunctionReference "Function Reference">
<!ENTITY Appendixes "Appendixes">
-
+<!ENTITY PEAR "PEAR: the PHP Extension and Application Repository">
<!ENTITY available "available in">
Index: phpdoc/en/pear/pear.xml
diff -u phpdoc/en/pear/pear.xml:1.1 phpdoc/en/pear/pear.xml:1.2
--- phpdoc/en/pear/pear.xml:1.1 Wed Mar 7 12:35:26 2001
+++ phpdoc/en/pear/pear.xml Wed Mar 7 18:45:53 2001
@@ -1,11 +1,22 @@
<reference id="ref.pear">
- <title>PEAR: the PHP Extension and Application Repository</title>
+ <title>PEAR Reference Manual</title>
<titleabbrev>PEAR</titleabbrev>
- <refentry id="pear.class.pear">
+ <partintro>
+ <simpara>
+ This chapter contains reference documentation for PEAR components
+ that are distributed with PHP. It is assumed that you are
+ already familiar with <link linkend="language.oop">objects and
+ classes</link>.
+ </simpara>
+ </partintro>
+ <refentry id="class.pear">
<refnamediv>
<refname>PEAR</refname>
<refpurpose>PEAR base class</refpurpose>
</refnamediv>
+ <refsynopsisdiv>
+ <synopsis>class <replaceable>classname</replaceable> extends
+<classname>PEAR</classname> { ... }</synopsis>
+ </refsynopsisdiv>
<refsect1>
<title>Description</title>
<simpara>
@@ -24,6 +35,52 @@
</listitem>
</itemizedlist>
</para>
+ <refsect2>
+ <title>PEAR "destructors"</title>
+ <simpara>
+ If you inherit <classname>PEAR</classname> in a class called
+ <replaceable>ClassName</replaceable>, you can define a method in
+ it called called _<replaceable>ClassName</replaceable> (the
+ class name with an underscore prepended) that will be invoked
+ when the request is over. This is not a destructor in the sense
+ that you can "delete" an object and have the destructor called,
+ but in the sense that PHP gives you a callback in the object
+ when it is done executing. See <link
+ linkend="example.pear.destructors">the example</link> below.
+ </simpara>
+ </refsect2>
+ <refsect2>
+ <title>PEAR Error Handling</title>
+ <simpara>
+ PEAR's base class also provides a way of passing around more
+ complex errors than a true/false value or a numeric code. A
+ PEAR error is an object that is either an instance of the class
+ <classname>PEAR_Error</classname>, or some class inheriting
+ <classname>PEAR_Error</classname>.
+ </simpara>
+ <simpara>
+ One of the design criteria of PEAR's errors is that it should
+ not force a particular type of output on the user, it should be
+ possible to handle errors without any output at all if that is
+ desireable. This makes it possible to handle errors gracefully,
+ also when your output format is different from HTML (for example
+ WML or some other XML format).
+ </simpara>
+ <simpara>
+ The error object can be configured to do a number of things when
+ it is created, such as printing an error message, printing the
+ message and exiting, raising an error with PHP's
+ <function>trigger_error</function> function, invoke a callback,
+ or none of the above. This is typically specified in
+ <classname>PEAR_Error</classname>'s constructor, but all of the
+ parameters are optional, and you can set up defaults for errors
+ generated from each object based on the
+ <classname>PEAR</classname> class. See the <link
+ linkend="example.pear.error1">PEAR error examples</link> for how
+ to use it and the <classname>PEAR_Error</classname> reference
+ for the full details.
+ </simpara>
+ </refsect2>
</refsect1>
<refsect1>
<title>Examples</title>
@@ -32,7 +89,7 @@
emulated destructors" to implement a simple class that holds the
contents of a file, lets you append data to the object and
flushes the data back to the file at the end of the request:
- <example>
+ <example id="example.pear.destructors">
<title>PEAR: emulated destructors</title>
<programlisting role="php">
require_once "PEAR.php";
@@ -95,16 +152,215 @@
</simpara>
</note>
</para>
+ <simpara>
+ The next examples illustrate different ways of using PEAR's error
+ handling mechanism.
+ </simpara>
+ <para>
+ <example id="example.pear.error1">
+ <title>PEAR error example (1)</title>
+ <programlisting role="php">
+function mysockopen($host = "localhost", $port = 8090)
+{
+ $fp = fsockopen($host, $port, $errno, $errstr);
+ if (!is_resource($fp)) {
+ return new PEAR_Error($errstr, $errno);
+ }
+ return $fp;
+}
+
+$sock = mysockopen();
+if (PEAR::isError($sock)) {
+ print "mysockopen error: ".$sock->getMessage()."<BR>\n"
+}
+</programlisting>
+ </example>
+ </para>
+ <simpara>
+ This example shows a wrapper to <function>fsockopen</function>
+ that delivers the error code and message (if any) returned by
+ fsockopen in a PEAR error object. Notice that
+ <function>PEAR::isError</function> is used to detect whether a
+ value is a PEAR error.
+ </simpara>
+ <simpara>
+ PEAR_Error's mode of operation in this example is simply
+ returning the error object and leaving the rest to the user
+ (programmer). This is the default error mode.
+ </simpara>
+ <simpara>
+ In the next example we're showing how to use default error modes:
+ </simpara>
+ <para>
+ <example id="example.pear.error2">
+ <title>PEAR error example (2)</title>
+ <programlisting role="php">
+class TCP_Socket extends PEAR
+{
+ var $sock;
+
+ function TCP_Socket()
+ {
+ $this->PEAR();
+ }
+
+ function connect($host, $port)
+ {
+ $sock = fsockopen($host, $port, $errno, $errstr);
+ if (!is_resource($sock)) {
+ return $this->raiseError($errstr, $errno);
+ }
+ }
+}
+
+$sock = new TCP_Socket;
+$sock->setErrorHandling(PEAR_ERROR_DIE);
+$sock->connect("localhost", 8090);
+print "still alive<BR>\n";
+</programlisting>
+ </example>
+ </para>
+ <simpara>
+ Here, we set the default error mode to
+ <constant>PEAR_ERROR_DIE</constant>, and since we don't specify
+ any error mode in the raiseError call (that'd be the third
+ parameter), raiseError uses the default error mode and exits if
+ fsockopen fails.
+ </simpara>
</refsect1>
</refentry>
- <refentry id="pear.class.pear-error">
+ <refentry id="class.pear-error">
<refnamediv>
<refname>PEAR_Error</refname>
<refpurpose>PEAR error mechanism base class</refpurpose>
</refnamediv>
+ <refsynopsisdiv>
+ <synopsis>$err = new <classname>PEAR_Error</classname>($msg);</synopsis>
+ </refsynopsisdiv>
<refsect1>
- <title>Description</title>
+ <title>Error Modes</title>
+ <para>
+ An error object has a mode of operation that can be set with one
+ of the following constants:
+ <variablelist id="pear.error-modes">
+ <varlistentry id="constant.pear-error-return">
+ <term>PEAR_ERROR_RETURN</term>
+ <listitem>
+ <simpara>
+ Just return the object, don't do anything special in
+ PEAR_Error's constructor.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="constant.pear-error-print">
+ <term>PEAR_ERROR_PRINT</term>
+ <listitem>
+ <simpara>
+ Print the error message in the constructor. The execution is
+ not interrupted.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="constant.pear-error-trigger">
+ <term>PEAR_ERROR_TRIGGER</term>
+ <listitem>
+ <simpara>
+ Use PHP's <function>trigger_error</function> function to
+ raise an internal error in PHP. The execution is aborted if
+ you have defined your own PHP error handler or if you set the
+ error severity to E_USER_ERROR.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="constant.pear-error-die">
+ <term>PEAR_ERROR_DIE</term>
+ <listitem>
+ <simpara>
+ Print the error message and exit. Execution is of course
+ aborted.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="constant.pear-error-callback">
+ <term>PEAR_ERROR_CALLBACK</term>
+ <listitem>
+ <simpara>
+ Use a callback function or method to handle errors.
+ Execution is aborted.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </refsect1>
+ <refsect1>
+ <title>Properties</title>
<simpara></simpara>
+ </refsect1>
+ <refsect1>
+ <title>Methods</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><function>PEAR_Error::PEAR_Error</function></funcdef>
+ <paramdef>
+ <parameter><optional>message</optional></parameter>
+ <parameter><optional>code</optional></parameter>
+ <parameter><optional>mode</optional></parameter>
+ <parameter><optional>options</optional></parameter>
+ <parameter><optional>userinfo</optional></parameter>
+ </paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <refsect2>
+ <title>Description</title>
+ <para>
+ PEAR_Error constructor. Parameters:
+ <variablelist>
+ <varlistentry>
+ <term>message</term>
+ <listitem>
+ <simpara>
+ error message, defaults to "unknown error"
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>code</term>
+ <listitem>
+ <simpara>
+ error code (optional)
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>mode</term>
+ <listitem>
+ <simpara>
+ Mode of operation. See the <link
+ linkend="pear.error-modes">error modes</link> section for
+ details.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>options</term>
+ <listitem>
+ <simpara>
+ If the mode of can have any options specified, use this
+ parameter. Currently the "trigger" and "callback" modes are
+ the only using the options parameter. For trigger mode,
+ this parameter is one of <constant>E_USER_NOTICE</constant>,
+ <constant>E_USER_WARNING</constant> or
+ <constant>E_USER_ERROR</constant>. For callback mode, this
+ parameter should contain either the callback function name
+ (string), or a two-element (object, string) array
+ representing an object and a method name.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </refsect2>
</refsect1>
</refentry>
</reference>
Index: phpdoc/en/pear/about.xml
+++ phpdoc/en/pear/about.xml
<chapter id="pear.about">
<title>About PEAR</title>
<simpara>
PEAR is dedicated to <ulink url="&url.malinimg;">Malin Bakken</ulink>,
born 1999-11-21 (the first PEAR code was written just two hours
before she was born).
</simpara>
<sect1 id="pear-whatis">
<title>What is PEAR?</title>
<simpara>
PEAR is a code repository for PHP extensions and PHP library code
inspired by TeX's CTAN and Perl's CPAN.
</simpara>
<para>
The purpose of PEAR is:
<itemizedlist>
<listitem>
<simpara>
to provide a consistent means for library code authors to share
their code with other developers
</simpara>
</listitem>
<listitem>
<simpara>
to give the PHP community an infrastructure for sharing code
</simpara>
</listitem>
<listitem>
<simpara>
to define standards that help developers write portable and
reusable code
</simpara>
</listitem>
<listitem>
<simpara>
to provide tools for code maintenance and distribution
</simpara>
</listitem>
</itemizedlist>
</para>
</sect1>
</chapter>
<!-- 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:
-->
Index: phpdoc/en/pear/standards.xml
+++ phpdoc/en/pear/standards.xml
<chapter id="pear.standards">
<title>PEAR Coding Standards</title>
<sect1 id="pear.standards.indenting">
<title>Indenting</title>
<para>
Use an indent of 4 spaces, with no tabs. If you use Emacs to edit PEAR
code, you should set indent-tabs-mode to nil. Here is an example mode
hook that will set up Emacs according to these guidelines (you will
need to ensure that it is called when you are editing php files):
<programlisting role="elisp">
(defun php-mode-hook ()
(setq tab-width 4
c-basic-offset 4
c-hanging-comment-ender-p nil
indent-tabs-mode nil))
</programlisting>
</para>
<para>Here are vim rules for the same thing:
<programlisting role="vim">
set expandtab
set shiftwidth=4
set tabstop=4
</programlisting>
</para>
</sect1>
<sect1 id="pear.standards.control">
<title>Control Structures</title>
<para>
These include if, for, while, switch, etc. Here is an example if
statement, since it is the most complicated of them:
<programlisting role="php">
if ((condition1) || (condition2)) {
action1;
} elseif ((condition3) && (condition4)) {
action2;
} else {
defaultaction;
}
</programlisting>
</para>
<simpara>
Control statements should have one space between the control keyword
and opening parenthesis, to distinguish them from function calls.
</simpara>
<simpara>
You are strongly encouraged to always use curly braces even in
situations where they are technically optional. Having them
increases readability and decreases the likelihood of logic errors
being introduced when new lines are added.
</simpara>
<para>
For switch statements:
<programlisting role="php">
switch (condition) {
case 1:
action1;
break;
case 2:
action2;
break;
default:
defaultaction;
break;
}
</programlisting>
</para>
</sect1>
<sect1 id="pear.standards.funcalls">
<title>Function Calls</title>
<para>
Functions should be called with no spaces between the function
name, the opening parenthesis, and the first parameter; spaces
between commas and each parameter, and no space between the last
parameter, the closing parenthesis, and the semicolon. Here's an
example:
<programlisting role="php">
$var = foo($bar, $baz, $quux);
</programlisting>
</para>
<para>
As displayed above, there should be one space on either side of an
equals sign used to assign the return value of a function to a
variable. In the case of a block of related assignments, more space
may be inserted to promote readability:
<programlisting role="php">
$short = foo($bar);
$long_variable = foo($baz);
</programlisting>
</para>
</sect1>
<sect1 id="pear.standards.funcdef">
<title>Function Definitions</title>
<para>
Function declaractions follow the "one true brace" convention:
<programlisting role="php">
function fooFunction($arg1, $arg2 = '')
{
if (condition) {
statement;
}
return $val;
}
</programlisting>
</para>
<para>
Arguments with default values go at the end of the argument list.
Always attempt to return a meaningful value from a function if one
is appropriate. Here is a slightly longer example:
<programlisting role="php">
function connect(&$dsn, $persistent = false)
{
if (is_array($dsn)) {
$dsninfo = &$dsn;
} else {
$dsninfo = DB::parseDSN($dsn);
}
if (!$dsninfo || !$dsninfo['phptype']) {
return $this->raiseError();
}
return true;
}
</programlisting>
</para>
</sect1>
<sect1 id="pear.standards.comments">
<title>Comments</title>
<para>
Inline documentation for classes should follow the PHPDoc
convention, similar to Javadoc. More information about PHPDoc can
be found here: <ulink url="&url.phpdoc;">&url.phpdoc;</ulink>
</para>
<para>
Non-documentation comments are strongly encouraged. A general rule of
thumb is that if you look at a section of code and think "Wow, I don't
want to try and describe that", you need to comment it before you
forget how it works.
</para>
<para>
C++ style comments (/* */) and standard C comments (// ) are both
fine. Use of perl/shell style comments (# ) is discouraged.
</para>
</sect1>
<sect1 id="pear.standards.including">
<title>Including Code</title>
<para>
Anywhere you are unconditionally including a class file, use
<function>require_once</function>. Anywhere you are conditionally
including a class file (for example, factory methods), use
<function>include_once</function>. Either of these will ensure
that class files are included only once. They share the same file
list, so you don't need to worry about mixing them - a file
included with <function>require_once</function> will not be
included again by <function>include_once</function>.
<note>
<simpara>
<function>include_once</function> and
<function>require_once</function> are statements, not
functions. You don't <emphasis>need</emphasis> parentheses
around the filename to be included.
</simpara>
</note>
</para>
</sect1>
<sect1 id="pear.standards.tags">
<title>PHP Code Tags</title>
<para>
<emphasis>Always</emphasis> use <literal><?php ?></literal> to
delimit PHP code, not the <literal><? ?></literal> shorthand.
This is required for PEAR compliance and is also the most portable
way to include PHP code on differing operating systems and setups.
</para>
</sect1>
<sect1 id="pear.standards.header">
<title>Header Comment Blocks</title>
<para>
All source code files in the core PEAR distribution should contain
the following comment block as the header:
<programlisting role="php">
/* vim: set expandtab tabstop=4 shiftwidth=4: */
// +----------------------------------------------------------------------+
// | PHP version 4.0 |
// +----------------------------------------------------------------------+
// | Copyright (c) 1997, 1998, 1999, 2000, 2001 The PHP Group |
// +----------------------------------------------------------------------+
// | This source file is subject to version 2.0 of the PHP license, |
// | that is bundled with this package in the file LICENSE, and is |
// | available at through the world-wide-web at |
// | http://www.php.net/license/2_02.txt. |
// | If you did not receive a copy of the PHP license and are unable to |
// | obtain it through the world-wide-web, please send a note to |
// | [EMAIL PROTECTED] so we can mail you a copy immediately. |
// +----------------------------------------------------------------------+
// | Authors: Original Author <[EMAIL PROTECTED]> |
// | Your Name <[EMAIL PROTECTED]> |
// +----------------------------------------------------------------------+
//
// $Id$
</programlisting>
</para>
<para>
There's no hard rule to determine when a new code contributer
should be added to the list of authors for a given source file.
In general, their changes should fall into the "substantial"
category (meaning somewhere around 10% to 20% of code changes).
Exceptions could be made for rewriting functions or contributing
new logic.
</para>
<para>
Simple code reorganization or bug fixes would not justify the
addition of a new individual to the list of authors.
</para>
<para>
Files not in the core PEAR repository should have a similar block
stating the copyright, the license, and the authors. All files
should include the modeline comments to encourage consistency.
</para>
</sect1>
<sect1 id="pear.standards.cvstags">
<title>CVS Tags</title>
<para>
Include the $Id$ CVS vendor tag in each file. As each file
is edited, add this tag if it's not yet present (or replace
existing forms such as "Last Modified:", etc.).
<note>
<simpara>
We have a custom $Horde tag in Horde cvs to track our versions
seperately; we could do the same and make a $PEAR tag, that
would remain even if PEAR files were put into another source
control system, etc...]
</simpara>
</note>
</para>
</sect1>
<sect1 id="pear.standards.exampleurls">
<title>Example URLs</title>
<para>
Use "example.com" for all example URLs, per RFC 2606.
</para>
</sect1>
<sect1 id="pear.standards.constants">
<title>Naming Constants</title>
<para>
Constants should always be uppercase, with underscores to seperate
words. Prefix constant names with the name of the class/package
they are used in. For example, the constants used by the
<literal>DB::</literal> package all begin with
"<literal>DB_</literal>".
</para>
</sect1>
</chapter>
<!-- 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:
-->
