mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-16 00:48:54 +00:00
* 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
parent
554d45cae2
commit
e0d08012e5
2 changed files with 306 additions and 55 deletions
263
pear/pear.xml
263
pear/pear.xml
|
|
@ -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 @@ class FileContainer extends PEAR
|
|||
}
|
||||
}
|
||||
|
||||
$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 @@ $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<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>
|
||||
|
|
|
|||
|
|
@ -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(&$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 $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 @@ function connect(&$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(&$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:
|
||||
|
|
|
|||
Loading…
Reference in a new issue