sigmasternchen/php-doc-en
1
0
Fork 0
mirror of https://github.com/sigmasternchen/php-doc-en synced 2025-03-16 08:58:56 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

No more PEAR documentation in phpdoc, it is available

Browse source 
and updated at http://pear.php.net/


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@65947 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Gabor Hojtsy 2001-12-22 14:19:06 +00:00
parent 574e538f17
commit 64ff290284
4 changed files with 0 additions and 1171 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

72
pear/about.xml
View file

@ -1,72 +0,0 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.9 $ -->
<chapter id="pear.about">
<title>About PEAR</title>
<simpara>
PEAR is dedicated to Malin Bakken,
born 1999-11-21 (the first PEAR code was written just two hours
before she was born).
</simpara>
<note>
<para>
A separate manual for PEAR is just forming at
<ulink url="&url.php.pear.manual;">&url.php.pear.manual;</ulink>.
See that page for most actual information about PEAR.
</para>
</note>
<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
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

73
pear/benchmark_timer.xml
View file

@ -1,73 +0,0 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.10 $ -->
<refentry id="class.benchmark-timer">
<refnamediv>
<refname>Benchmark_Timer</refname>
<refpurpose>Timing script execution</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>...</synopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<simpara>
...
</simpara>
</refsect1>
<refsect1>
<example id="example.pear.benchmark.timer">
<programlisting role="php">
<![CDATA[
require_once 'Benchmark/Timer.php';
$timer = new Benchmark_Timer;
$timer->setMarker('start of for() loop');
for ($i = 0; $i < 1000; $i++) { /* ... */ }
$timer->setMarker('end of for() loop');
echo 'The for() loop took ' .
$timer->timeElapsed('start of for() loop', 'end of for() loop');
]]>
</programlisting>
</example>
</refsect1>
</refentry>
<refentry id="function.benchmark-timer.start">
<refnamediv>
<refname>start</refname>
<refpurpose>Set a default marker, called 'start'.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>...</synopsis>
</refsynopsisdiv>
</refentry>
<refentry id="function.benchmark-timer.stop">
<refnamediv>
<refname>stop</refname>
<refpurpose>Set a default marker, called 'stop'.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>...</synopsis>
</refsynopsisdiv>
</refentry>
<!-- 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
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

574
pear/pear.xml
View file

@ -1,574 +0,0 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.13 $ -->
<reference id="pear.reference">
<title>PEAR Reference Manual</title>
<titleabbrev>PEAR</titleabbrev>
<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>require_once "PEAR.php";</synopsis>
<synopsis>class <replaceable>classname</replaceable> extends <classname>PEAR</classname> { ... }</synopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<simpara>
The PEAR base class provides standard functionality that is used
by most PEAR classes. Normally you never make an instance of the
PEAR class directly, you use it by subclassing it.
</simpara>
<para>
Its key features are:
<itemizedlist>
<listitem>
<simpara>request-shutdown object "destructors"</simpara>
</listitem>
<listitem>
<simpara>error handling</simpara>
</listitem>
</itemizedlist>
</para>
</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">
<![CDATA[
$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>
<para>
The example below shows how to use the PEAR's "poor man's kinda
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 id="example.pear.destructors">
<title>PEAR: emulated destructors</title>
<programlisting role="php">
<![CDATA[
require_once "PEAR.php";
class FileContainer extends PEAR
{
var $file = '';
var $contents = '';
var $modified = 0;
function FileContainer($file)
{
$this->PEAR(); // this calls the parent class constructor
$fp = fopen($file, "r");
if (!is_resource($fp)) {
return;
}
while (!empty($data = fread($fp, 2048))) {
$this->contents .= $data;
}
fclose($fp);
}
function append($str)
{
$this->contents .= $str;
$this->modified++;
}
// The "destructor" is named like the constructor
// but with an underscore in front.
function _FileContainer()
{
if ($this->modified) {
$fp = fopen($this->file, "w");
if (!is_resource($fp)) {
return;
}
fwrite($fp, $this->contents);
fclose($fp);
}
}
}
$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
// "destructor" is called and updates the file on disk.
]]>
</programlisting>
</example>
<note>
<simpara>
PEAR "destructors" use PHP's shutdown callbacks
(<function>register_shutdown_function</function>), and you
can't output anything from these when PHP is running in a web
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>
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">
<![CDATA[
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">
<![CDATA[
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>
<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">
<![CDATA[
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">
<![CDATA[
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">
<![CDATA[
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">
<![CDATA[
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">
<![CDATA[
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>
<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>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>
<!-- 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
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

452
pear/standards.xml
View file

@ -1,452 +0,0 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.16 $ -->
<chapter id="pear.standards">
<title>PEAR Coding Standards</title>
<note>
<simpara>
The PEAR Coding Standards applies to code that is to become a part
of PEAR, either distributed with PHP or available for download via
PEAR's install tool.
</simpara>
</note>
<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">
<![CDATA[
(defun php-mode-hook ()
(setq tab-width 4
c-basic-offset 4
c-hanging-comment-ender-p nil
indent-tabs-mode
(not
(and (string-match "/\\(PEAR\\|pear\\)/" (buffer-file-name))
(string-match "\.php$" (buffer-file-name))))))
]]>
</programlisting>
</para>
<para>Here are vim rules for the same thing:
<programlisting role="vim">
<![CDATA[
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">
<![CDATA[
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">
<![CDATA[
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">
<![CDATA[
$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">
<![CDATA[
$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">
<![CDATA[
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">
<![CDATA[
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>&lt;?php ?></literal> to
delimit PHP code, not the <literal>&lt;? ?></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">
<![CDATA[
/* 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 |
// | license@php.net so we can mail you a copy immediately. |
// +----------------------------------------------------------------------+
// | Authors: Original Author <author@example.com> |
// | Your Name <you@example.com> |
// +----------------------------------------------------------------------+
//
// $Id: standards.xml,v 1.16 2001-12-12 20:47:43 hholzgra Exp $
]]>
</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.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 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
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>
<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>
<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.naming">
<title>Naming Conventions</title>
<sect2>
<title>Functions and Methods</title>
<para>
Functions and methods should be named using the "studly caps"
style (also referred to as "bumpy case" or "camel caps").
Functions should in addition have the package name as a prefix,
to avoid name collisions between packages. The initial letter of
the name (after the prefix) is lowercase, and each letter that
starts a new "word" is capitalized. Some examples:
<informaltable>
<tgroup cols="3">
<tbody>
<row>
<entry><simpara>connect()</simpara></entry>
<entry><simpara>getData()</simpara></entry>
<entry><simpara>buildSomeWidget()</simpara></entry>
<entry><simpara>XML_RPC_serializeData()</simpara></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<para>
Private class members (meaning class members that are intented
to be used only from within the same class in which they are
declared; PHP does not yet support truly-enforceable private
namespaces) are preceeded by a single underscore. For example:
<informaltable>
<tgroup cols="3">
<tbody>
<row>
<entry><simpara>_sort()</simpara></entry>
<entry><simpara>_initTree()</simpara></entry>
<entry><simpara>$this->_status</simpara></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</sect2>
<sect2>
<title>Constants</title>
<para>
Constants should always be all-uppercase, with underscores to
seperate words. Prefix constant names with the uppercased 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>
</sect2>
<sect2>
<title>Global Variables</title>
<para>
If your package needs to define global variables, their name
should start with a single underscore followed by the package
name and another underscore. For example, the PEAR package uses
a global variable called $_PEAR_destructor_object_list.
</para>
</sect2>
</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
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->