* some more pear docs

* added cvs tags to pear coding guidelines


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@53349 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Stig Bakken 2001-08-04 22:20:47 +00:00
parent 554d45cae2
commit e0d08012e5
2 changed files with 306 additions and 55 deletions

View file

@ -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 "=&amp; new" operator like
this:
<programlisting role="php">
$obj =&amp; 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 @@ class FileContainer extends PEAR
}
}
$fileobj = new FileContainer("testfile");
$fileobj =&amp; 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 @@ $fileobj->append("this ends up at the end of the file\n");
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>
@ -231,6 +255,149 @@ print "still alive&lt;BR>\n";
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">
<refnamediv>

View file

@ -1,4 +1,4 @@
<!-- $Revision: 1.7 $ -->
<!-- $Revision: 1.8 $ -->
<chapter id="pear.standards">
<title>PEAR Coding Standards</title>
<note>
@ -108,7 +108,7 @@ $long_variable = foo($baz);
<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 @@ function connect(&amp;$dsn, $persistent = false)
</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 &dollar;Id&dollar; CVS vendor tag in each file. As each file
Include the &dollar;Id&dollar; 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 @@ function connect(&amp;$dsn, $persistent = false)
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 @@ function connect(&amp;$dsn, $persistent = false)
<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: