ssb Sat Aug 4 18:20:47 2001 EDT
Modified files:
/phpdoc/en/pear pear.xml standards.xml
Log:
* some more pear docs
* added cvs tags to pear coding guidelines
Index: phpdoc/en/pear/pear.xml
diff -u phpdoc/en/pear/pear.xml:1.7 phpdoc/en/pear/pear.xml:1.8
--- phpdoc/en/pear/pear.xml:1.7 Sat Aug 4 14:07:05 2001
+++ phpdoc/en/pear/pear.xml Sat Aug 4 18:20:47 2001
@@ -1,5 +1,5 @@
<reference id="pear.reference">
-<!-- $Revision: 1.7 $ -->
+<!-- $Revision: 1.8 $ -->
<title>PEAR Reference Manual</title>
<titleabbrev>PEAR</titleabbrev>
@@ -38,52 +38,71 @@
</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 id="pear.destructors">
+ <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 PHP is done executing. See <link
+ linkend="example.pear.destructors">the example</link> below.
+ </simpara>
+ <para>
+ <warning id="pear.destructors.warning">
+ <title>Important!</title>
+ <para>
+ In order for destructors to work properly, you must
+ instantiate your class with the "=& new" operator like
+ this:
+ <programlisting role="php">
+$obj =& new MyClass();
+</programlisting>
+ </para>
+ <simpara>
+ If you only use "= new", the object registered in PEAR's
+ shutdown list will be a copy of the object at the time the
+ constructor is called, and it will this copy's "destructor"
+ that will be called upon request shutdown.
+ </simpara>
+ </warning>
+ </para>
+ </refsect1>
+ <refsect1 id="pear.error-handling">
+ <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
+ desirable. 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>
</refsect1>
<refsect1>
<title>Examples</title>
@@ -137,7 +156,7 @@
}
}
-$fileobj = new FileContainer("testfile");
+$fileobj =& new FileContainer("testfile");
$fileobj->append("this ends up at the end of the file\n");
// When the request is done and PHP shuts down, $fileobj's
@@ -153,6 +172,11 @@
server. So anything printed in a "destructor" gets lost except
when PHP is used in command-line mode. Bummer.
</simpara>
+ <simpara>
+ Also, see the <link
+ linkend="pear.destructors.warning">warning</link> about how to
+ instantiate objects if you want to use the destructor.
+ </simpara>
</note>
</para>
<simpara>
@@ -230,6 +254,149 @@
parameter), raiseError uses the default error mode and exits if
fsockopen fails.
</simpara>
+ </refsect1>
+ <refsect1>
+ <title>Global Variables Used</title>
+ <para>
+ The PEAR class uses some global variables to register global
+ defaults, and an object list used by the "destructors". All of
+ the global variables associated with the PEAR class have a
+ <literal>_PEAR_</literal> name prefix.
+ </para>
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term>$_PEAR_default_error_mode</term>
+ <listitem>
+ <simpara>
+ If no default error mode is set in an object, this mode will
+ be used. Must be one of
+ <constant>PEAR_ERROR_RETURN</constant>,
+ <constant>PEAR_ERROR_PRINT</constant>,
+ <constant>PEAR_ERROR_TRIGGER</constant>,
+ <constant>PEAR_ERROR_DIE</constant> or
+ <constant>PEAR_ERROR_CALLBACK</constant>.
+ </simpara>
+ <para>
+ Don't set this variable directly, call
+ <function>PEAR::setErrorHandling</function> as a static
+ method like this:
+ <informalexample>
+ <programlisting role="php">
+PEAR::setErrorHandling(PEAR_ERROR_DIE);
+</programlisting>
+ </informalexample>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>$_PEAR_default_error_options</term>
+ <listitem>
+ <simpara>
+ If the error mode is <constant>PEAR_ERROR_TRIGGER</constant>,
+ this is the error level (one of
+ <constant>E_USER_NOTICE</constant>,
+ <constant>E_USER_WARNING</constant> or
+ <constant>E_USER_ERROR</constant>).
+ </simpara>
+ <para>
+ Don't set this variable directly, call
+ <function>PEAR::setErrorHandling</function> as a static
+ method like this:
+ <informalexample>
+ <programlisting role="php">
+PEAR::setErrorHandling(PEAR_ERROR_TRIGGER, E_USER_ERROR);
+</programlisting>
+ </informalexample>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>$_PEAR_default_error_callback</term>
+ <listitem>
+ <simpara>
+ If no <replaceable>options</replaceable> parameter is used
+ when an error is raised and the error mode is
+ <constant>PEAR_ERROR_CALLBACK</constant>, the value of this
+ variable is used as the callback. This means that you can
+ switch the error mode temporarily and return to callback mode
+ without specifying the callback function again. A string
+ value represents a function, a two-element array with an
+ object at index 0 and a string at index 1 represents a
+ method.
+ </simpara>
+ <para>
+ Again, don't set this variable directly, call
+ <function>PEAR::setErrorHandling</function> as a static
+ method like this:
+ <informalexample>
+ <programlisting role="php">
+PEAR::setErrorHandling(PEAR_ERROR_CALLBACK, "my_error_handler");
+</programlisting>
+ </informalexample>
+ </para>
+ <para>
+ Here is an example of how you can switch back and forth
+ without specifying the callback function again:
+ <informalexample>
+ <programlisting role="php">
+PEAR::setErrorMode(PEAR_ERROR_CALLBACK, "my_function_handler");
+do_some_stuff();
+PEAR::setErrorMode(PEAR_ERROR_DIE);
+do_some_critical_stuff();
+PEAR::setErrorMode(PEAR_ERROR_CALLBACK);
+// now we're back to using my_function_handler again
+</programlisting>
+ </informalexample>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </refsect1>
+ <refsect1>
+ <title>Methods</title>
+ <refsect2 id="function.pear.pear">
+ <title>PEAR::PEAR</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>PEAR()</funcdef>
+ <void/>
+ </funcprototype>
+ </funcsynopsis>
+ <para>
+ This is the PEAR class constructor. Call it from the
+ constructor of every class inheriting the PEAR class.
+ <example>
+ <title>PEAR Class Constructor Example</title>
+ <programlisting role="php">
+class MyClass extends PEAR
+{
+ var $foo, $bar;
+ function MyClass($foo, $bar)
+ {
+ $this->PEAR();
+ $this->foo = $foo;
+ $this->bar = $bar;
+ }
+}
+</programlisting>
+ </example>
+ </para>
+ </refsect2>
+ <refsect2 id="function.pear.-pear">
+ <title>PEAR::_PEAR</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>_PEAR()</funcdef>
+ <void/>
+ </funcprototype>
+ </funcsynopsis>
+ <para>
+ This is the PEAR class destructor. It is called during request
+ shutdown.
+ </para>
+ </refsect2>
</refsect1>
</refentry>
<refentry id="class.pear-error">
Index: phpdoc/en/pear/standards.xml
diff -u phpdoc/en/pear/standards.xml:1.7 phpdoc/en/pear/standards.xml:1.8
--- phpdoc/en/pear/standards.xml:1.7 Thu Aug 2 13:37:51 2001
+++ phpdoc/en/pear/standards.xml Sat Aug 4 18:20:47 2001
@@ -1,4 +1,4 @@
-<!-- $Revision: 1.7 $ -->
+<!-- $Revision: 1.8 $ -->
<chapter id="pear.standards">
<title>PEAR Coding Standards</title>
<note>
@@ -108,7 +108,7 @@
<sect1 id="pear.standards.funcdef">
<title>Function Definitions</title>
<para>
- Function declaractions follow the "one &true; brace" convention:
+ Function declaractions follow the "one true brace" convention:
<programlisting role="php">
function fooFunction($arg1, $arg2 = '')
{
@@ -239,12 +239,16 @@
</para>
</sect1>
- <sect1 id="pear.standards.cvstags">
- <title>CVS Tags</title>
+ <sect1 id="pear.standards.cvs">
+ <title>Using CVS</title>
+ <simpara>
+ This section applies only to packages using CVS at cvs.php.net.
+ </simpara>
<para>
- Include the $Id$ CVS vendor tag in each file. As each file
+ Include the $Id$ CVS keyword 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
@@ -253,6 +257,86 @@
control system, etc...]
</simpara>
</note>
+-->
+ </para>
+ <para>
+ The rest of this section assumes that you have basic knowledge
+ about CVS tags and branches.
+ </para>
+ <para>
+ CVS tags are used to label which revisions of the files in your
+ package belong to a given release. Below is a list of the
+ required and suggested CVS tags:
+
+ <variablelist>
+ <varlistentry>
+ <term>RELEASE_<replaceable>n_n</replaceable></term>
+ <listitem>
+ <simpara>
+ (required) Used for tagging a release. If you don't use it,
+ there's no way to go back and retrieve your package from the
+ CVS server in the state it was in at the time of the release.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>QA_<replaceable>n_n</replaceable></term>
+ <listitem>
+ <simpara>
+ (branch, optional) If you feel you need to roll out a
+ release candidate before releasing, it's a good idea to make a
+ branch for it so you can isolate the release and apply only
+ those critical fixes before the actual release. Meanwhile,
+ normal development may continue on the main trunk.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>MAINT_<replaceable>n_n</replaceable></term>
+ <listitem>
+ <simpara>
+ (branch, optional) If you need to make "micro-releases" (for
+ example 1.2.1 and so on after 1.2, you can use a branch for
+ that too, if your main trunk is very active and you want only
+ minor changes between your micro-releases.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ Only the RELEASE tag is required, the rest are recommended for
+ your convenience.
+ </para>
+ <para>
+ Below is an example of how to tag the 1.2 release of the
+ "Money_Fast" package:
+ <informalexample>
+ <screen><prompt>$ </prompt><command>cd pear/Money_Fast</command>
+<prompt>$ </prompt><command>cvs tag RELEASE_1_2</command>
+<computeroutput>T Fast.php
+T README
+T package.xml
+</computeroutput>
+</screen>
+ </informalexample>
+ By doing this you make it possible for the PEAR web site to take
+ you through the rest of your release process.
+ </para>
+ <para>
+ Here's an example of how to create a QA branch:
+ <informalexample>
+ <screen><prompt>$ </prompt><command>cvs tag QA_2_0_BP</command>
+...
+<prompt>$ </prompt><command>cvs rtag -b -r QA_2_0_BP QA_2_0</command>
+<prompt>$ </prompt><command>cvs update -r QA_2_0</command>
+<prompt>$ </prompt><command>cvs tag RELEASE_2_0RC1</command>
+...and then the actual release, from the same branch:
+<prompt>$ </prompt><command>cvs tag RELEASE_2_0</command>
+</screen>
+ </informalexample>
+ The "QA_2_0_BP" tag is a "branch point" tag, which is the start
+ point of the tag. It's always a good idea to start a CVS branch
+ from such branch points. MAINT branches may use the RELEASE tag
+ as their branch point.
</para>
</sect1>
@@ -266,14 +350,14 @@
<sect1 id="pear.standards.constants">
<title>Naming Constants</title>
<para>
- Constants should always be uppercase, with underscores to seperate
+ Constants should always be all-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:
