What is PEAR?

PEAR is short for "PHP Extension and Application Repository" and is pronounced just like the fruit. The purpose of PEAR is to provide:

• A structured library of open-source code for PHP users

• A system for code distribution and package maintenance

• A standard style for code written in PHP, specified here

• The PHP Extension Community Library (PECL), see more below

• A web site, mailing lists and download mirrors to support the PHP/PEAR community

PEAR is a community-driven project governed by its developers. PEAR's governing bodies are subdivided into the PEAR Group, Collectives, and a President. PEAR's constitution (adopted in March 2007) defining these groups is documented here. The PEAR project was founded in 1999 by Stig S. Bakken and quite a lot of people have joined the project.

Introduction

This chapter requires that you are already familiar with the general structure of PEAR.

The base installation that comes with the PHP distribution, contains all the stuff that is needed to run the PEAR installation tools etc. If you have a recent installation of PHP, you can relax: The PEAR base installation is already there, unless you have compiled your PHP with the ./configure flag --without-pear.

The packages that do not come with PHP can be installed with the PEAR package manager. The manager handles installation similar to Debian's "apt-get" package management utility, as well as others such as "yum". Again: If you are running a recent version of PHP (> 4.3.0) you can skip the next section. But if you are running PHP 4.2.* or earlier, you need to manually install the manager.

Apart from installing packages, the PEAR package manager also handles some other tasks: It can create new packages on your machine, manage a registry of installed packages, check dependencies and it can interact with an XML-RPC service on pear.php.net to serve some other tasks.

Getting the manager

Command line installer

The command line installer is the easiest way to install PEAR packages on your system: It connects to the PEAR package server via a simple HTTP connection, loads the package on your system and installs it to the desired location.

Installation of a local PEAR copy on a shared host

Many users have a shared provider that grants access to a system-wide PEAR installation. However, in many cases, it is advantageous to have a local copy of PEAR that can be used for packages that are not installed by the host provider. There are ways of installing PEAR both for users with a telnet/ssh shell access and users who only have ftp access.

Manual installation

CVS installer

This passage will describe how to install the latest development version of a PEAR package from CVS.

It is NOT recommended to run a package from CVS in working environments! Because CVS versions are not regular releases, this means:

• You could get no kind of help from the maintainer or anybody other.

• Versions in CVS may break the upgrade mechanism of the PEAR Installer.

If you still want to install a package from CVS, you have to do the same steps like a package maintainer creating a new release of a package. If you have problems following the next steps, take a look into the Developers Section of the manual.

1. Get the package files from CVS like described in http://www.php.net/anoncvs.php

   The name of the module to checkout is pear/<packagename>, i.e. cvs -d :pserver:cvsread@cvs.php.net:/repository checkout pear/HTTP_Client.

2. Check the package.xml file, especially the dir and file entries. They must match the existing files and directory structure. If they differ, contact the package maintainer and ask for an update of the package.xml.

3. Create a valid package using the PEAR Installer pear package <path to package.xml>

4. If you have already installed the package: remove it to avoid version conflicts: pear uninstall <package>

5. Install your package archive: pear install <package-file>

   Now, you have a CVS version installed!

You should upgrade to an official release of the package as early as possible. Before you install the official release, uninstall the CVS version to avoid version conflicts.

Installing PECL packages

The procedure of installing PECL packages is described in the manual on the PHP website.

The mailing lists

Web resources

There are a number of web sites that deal with PEAR. We have compiled a list of them here. If a site is missing, you can email the webmaster.

#PEAR on IRC

The PEAR project has its own IRC channel #PEAR, which is available on EFnet. Come along and meet the gurus, which don't have to pay for their internet connection and can hang around in IRC the whole day.

Indenting and Line Length

Use an indent of 4 spaces, with no tabs. This helps to avoid problems with diffs, patches, CVS history and annotations.

For Emacs you should set indent-tabs-mode to nil. Here is an example mode hook that will set up Emacs (ensure that it is called when you are editing PHP files):

(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))))))

Here are Vim rules for the same thing:

set expandtab set shiftwidth=4 set softtabstop=4 set tabstop=4

It is recommended to keep lines at approximately 75-85 characters long for better code readability.

Control Structures

These include if, for, while, switch, etc. Here is an example if statement, since it is the most complicated of them:

if ((condition1) || (condition2)) { action1; } elseif ((condition3) && (condition4)) { action2; } else { defaultaction; }

Control statements should have one space between the control keyword and opening parenthesis, to distinguish them from function calls.

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.

For switch statements:

switch (condition) { case 1: action1; break; case 2: action2; break; default: defaultaction; break; }

Function Calls

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:

$var = foo($bar, $baz, $quux);

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:

$short = foo($bar); $long_variable = foo($baz);

Class Definitions

Class declarations have their opening brace on a new line:

class Foo_Bar { //... code goes here }

Function Definitions

Function declarations follow the "K&R style":

function fooFunction($arg1, $arg2 = '') { if (condition) { statement; } return $val; }

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:

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; }

Comments

Complete inline documentation comment blocks (docblocks) must be provided. Please read the Sample File and Header Comment Blocks sections of the Coding Standards to learn the specifics of writing docblocks for PEAR packages. Further information can be found on the phpDocumentor website.

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.

C style comments (/* */) and standard C++ comments (//) are both fine. Use of Perl/shell style comments (#) is discouraged.

Including Code

Anywhere you are unconditionally including a class file, use require_once. Anywhere you are conditionally including a class file (for example, factory methods), use include_once. 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 require_once will not be included again by include_once.

PHP Code Tags

Always use <?php ?> to delimit PHP code, not the <? ?> shorthand. This is required for PEAR compliance and is also the most portable way to include PHP code on differing operating systems and setups.

Header Comment Blocks

All source code files in the PEAR repository shall contain a "page-level" docblock at the top of each file and a "class-level" docblock immediately above each class. Below are examples of such docblocks.

<?php /* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */ /** * Short description for file * * Long description for file (if any)... * * PHP versions 4 and 5 * * LICENSE: This source file is subject to version 3.0 of the PHP license * that is available through the world-wide-web at the following URI: * http://www.php.net/license/3_0.txt. If you did not receive a copy of * the PHP License and are unable to obtain it through the web, please * send a note to license@php.net so we can mail you a copy immediately. * * @category CategoryName * @package PackageName * @author Original Author <author@example.com> * @author Another Author <another@example.com> * @copyright 1997-2005 The PHP Group * @license http://www.php.net/license/3_0.txt PHP License 3.0 * @version CVS: $Id:$ * @link http://pear.php.net/package/PackageName * @see NetOther, Net_Sample::Net_Sample() * @since File available since Release 1.2.0 * @deprecated File deprecated in Release 2.0.0 */ /* * Place includes, constant defines and $_GLOBAL settings here. * Make sure they have appropriate docblocks to avoid phpDocumentor * construing they are documented by the page-level docblock. */ /** * Short description for class * * Long description for class (if any)... * * @category CategoryName * @package PackageName * @author Original Author <author@example.com> * @author Another Author <another@example.com> * @copyright 1997-2005 The PHP Group * @license http://www.php.net/license/3_0.txt PHP License 3.0 * @version Release: @package_version@ * @link http://pear.php.net/package/PackageName * @see NetOther, Net_Sample::Net_Sample() * @since Class available since Release 1.2.0 * @deprecated Class deprecated in Release 2.0.0 */ class Foo_Bar { } ?>

<file name="Class.php">
  <replace from="@package_version@" to="version" type="package-info" />
</file>

$pkg->addReplacement('filename.php', 'package-info',
                     '@package_version@', 'version');

Using CVS

This section applies only to packages using CVS at cvs.php.net.

Include the $Id$ CVS keyword in each file.

The rest of this section assumes that you have basic knowledge about CVS tags and branches.

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:

$ cd pear/Money_Fast
$ cvs tag RELEASE_1_2_0
T Fast.php
T README
T package.xml

$ cvs tag QA_2_0_0_BP
...
$ cvs rtag -b -r QA_2_0_0_BP QA_2_0_0
$ cvs update -r QA_2_0_0
$ cvs tag RELEASE_2_0_0RC1
...and then the actual release, from the same branch:
$ cvs tag RELEASE_2_0_0

Example URLs

Use example.com, example.org and example.net for all example URLs and email addresses, per RFC 2606.

Naming Conventions

File Formats

All scripts contributed to PEAR must:

• Be stored as ASCII text

• Use ISO-8859-1 character encoding

• Be Unix formatted

  "Unix formatted" means two things:

  1) Lines must end only with a line feed (LF). Line feeds are represented as ordinal 10, octal 012 and hex 0A. Do not use carriage returns (CR) like Macintosh computers do or the carriage return/line feed combination (CRLF) like Windows computers do.

  2) There should be one line feed after the closing PHP tag (?>). This means that when the cursor is at the very end of the file, it should be one line below the closing PHP tag.

E_STRICT-compatible code

Starting on 01 January 2007, all new code that is suggested for inclusion into PEAR must be E_STRICT-compatible. This means that it must not produce any warnings or errors when PHP's error reporting level is set to E_ALL | E_STRICT.

The development of existing packages that are not E_STRICT-compatible can continue as usual. If however a new major version of the package is released, this major version must then be E_STRICT-compatible.

More details on this part of the Coding Standards can be found in the corresponding PEPr proposal.

Error Handling Guidelines

This part of the Coding Standards describes how errors are handled in PEAR packages that are developed for PHP 5 and 6. It uses Exceptions, introduced in PHP 5.0 with Zend Engine 2, as the error handling mechanism.

/*
 * Connect to Specified Database
 *
 * @throws Example_Datasource_Exception when it can't connect
 * to specified DSN.
 */
function connectDB($dsn)
{
    $this->db =& DB::connect($dsn);
    if (DB::isError($this->db)) {
        throw new Example_Datasource_Exception(
                "Unable to connect to $dsn:" . $this->db->getMessage()
        );
    }
}

/*
 * Connect to one of the possible databases
 *
 * @throws Example_Datasource_Exception when it can't connect to
 * any of the configured databases.
 *
 * @throws Example_Config_Exception when it can't find databases
 * in the configuration.
 */

function connect(Config $conf)
{
    $dsns =& $conf->searchPath(array('config', 'db'));
    if ($dsns === FALSE) throw new Example_Config_Exception(
        'Unable to find config/db section in configuration.'
    );

    $dsns =& $dsns->toArray();

    foreach($dsns as $dsn) {
        try {
            $this->connectDB($dsn);
            return;
        } catch (Example_Datasource_Exception e) {
            // Some warning/logging code recording the failure
            // to connect to one of the databases
        }
    }
    throw new Example_Datasource_Exception(
        'Unable to connect to any of the configured databases'
    );
}

/*
 * loadConfig parses the provided configuration. If the configuration
 * is invalid, it will set the configuration to the default config.
 *
 */
function loadConfig(Config $conf)
{
    try {
        $this->config = $conf->parse();
    } catch (Config_Parse_Exception e) {
        // Warn/Log code goes here
        // Perform incomplete recovery
        $this->config = $this->defaultConfig;
    }
}

function divide($x, $y)
{
    if ($y == 0) {
        throw new Example_Aritmetic_Exception('Division by zero');
    }
}

/*
 * Connect to Specified Database
 *
 * @throws Example_Datasource_Exception when it can't connect to specified DSN.
 */
function connectDB($dsn)
{
    $this->db =& DB::connect($dsn);
    if (DB::isError($this->db)) {
        throw new Example_Datasource_Exception(
                "Unable to connect to $dsn:" . $this->db->getMessage()
        );
    }
}

function preTaxPrice($retailPrice, $taxRate)
{
    try {
        return $this->divide($retailPrice, 1 + $taxRate);
    } catch (Example_Aritmetic_Exception e) {
        throw new Example_Tax_Exception('Invalid tax rate.', e);
    }
}

function preTaxPrice($retailPrice, $taxRate)
{
    return $this->divide($retailPrice, 1 + $taxRate);
}

/**
 * Recursively search a tree for string.
 * @throws ResultException
 */
public function search(TreeNode $node, $data)
{
    if ($node->data === $data) {
        throw new ResultException( $node );
    } else {
        search( $node->leftChild, $data );
        search( $node->rightChild, $data );
    }
}

/**
 * This method searches for aliens.
 *
 * @return array Array of Aliens objects.
 * @throws AntennaBrokenException If the impedence readings indicate
 * that the antenna is broken.
 *
 * @throws AntennaInUseException If another process is using the
 * antenna already.
 */
public function findAliens($color = 'green');

/**
 * Load session objects into shared memory.
 *
 * @throws LoadingException Any lower-level IOException will be wrapped
 * and re-thrown as a LoadingException.
 */
public function loadSessionObjects();

/**
 * Performs a batch of database queries (atomically, not in transaction).
 * @throws SQLException Low-level SQL errors will bubble up through this method.
 */
public function batchExecute();

Best practices

There are other things not covered by PEAR Coding Standards which are mostly subject of personal preference and not directly related to readability of the code. Things like "single quotes vs double quotes" are features of PHP itself to make programming easier and there are no reasons not use one way in preference to another. Such best practices are left solely on developer to decide. The only recommendation could be made to keep consistency within package and respect personal style of other developers.

Sample File (including Docblock Comment standards)

The source code of PEAR packages are read by thousands of people. Also, it is likely other people will become developers on your package at some point in the future. Therefore, it is important to make life easier for everyone by formatting the code and docblocks in standardized ways. People can then quickly find the information they are looking for because it is in the expected location. Your cooperation is appreciated.

Each docblock in the example contains many details about writing Docblock Comments. Following those instructions is important for two reasons. First, when docblocks are easy to read, users and developers can quickly ascertain what your code does. Second, the PEAR website now contains the phpDocumentor generated documentation for each release of each package, so keeping things straight here means the API docs on the website will be useful.

Please take note of the vertical and horizontal spacing. They are part of the standard.

The "fold markers" (// {{{ and // }}}) are optional. If you aren't using fold markers, remove foldmethod=marker from the vim header.

<?php /* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */ /** * Short description for file * * Long description for file (if any)... * * PHP versions 4 and 5 * * LICENSE: This source file is subject to version 3.0 of the PHP license * that is available through the world-wide-web at the following URI: * http://www.php.net/license/3_0.txt. If you did not receive a copy of * the PHP License and are unable to obtain it through the web, please * send a note to license@php.net so we can mail you a copy immediately. * * @category CategoryName * @package PackageName * @author Original Author <author@example.com> * @author Another Author <another@example.com> * @copyright 1997-2005 The PHP Group * @license http://www.php.net/license/3_0.txt PHP License 3.0 * @version CVS: $Id:$ * @link http://pear.php.net/package/PackageName * @see NetOther, Net_Sample::Net_Sample() * @since File available since Release 1.2.0 * @deprecated File deprecated in Release 2.0.0 */ /** * This is a "Docblock Comment," also known as a "docblock." The class' * docblock, below, contains a complete description of how to write these. */ require_once 'PEAR.php'; // {{{ constants /** * Methods return this if they succeed */ define('NET_SAMPLE_OK', 1); // }}} // {{{ GLOBALS /** * The number of objects created * @global int $GLOBALS['_NET_SAMPLE_Count'] */ $GLOBALS['_NET_SAMPLE_Count'] = 0; // }}} // {{{ Net_Sample /** * An example of how to write code to PEAR's standards * * Docblock comments start with "/**" at the top. Notice how the "/" * lines up with the normal indenting and the asterisks on subsequent rows * are in line with the first asterisk. The last line of comment text * should be immediately followed on the next line by the closing asterisk * and slash and then the item you are commenting on should be on the next * line below that. Don't add extra lines. Please put a blank line * between paragraphs as well as between the end of the description and * the start of the @tags. Wrap comments before 80 columns in order to * ease readability for a wide variety of users. * * Docblocks can only be used for programming constructs which allow them * (classes, properties, methods, defines, includes, globals). See the * phpDocumentor documentation for more information. * http://phpdoc.org/docs/HTMLSmartyConverter/default/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html * * The Javadoc Style Guide is an excellent resource for figuring out * how to say what needs to be said in docblock comments. Much of what is * written here is a summary of what is found there, though there are some * cases where what's said here overrides what is said there. * http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#styleguide * * The first line of any docblock is the summary. Make them one short * sentence, without a period at the end. Summaries for classes, properties * and constants should omit the subject and simply state the object, * because they are describing things rather than actions or behaviors. * * Below are the tags commonly used for classes. @category through @version * are required. The remainder should only be used when necessary. * Please use them in the order they appear here. phpDocumentor has * several other tags available, feel free to use them. * * @category CategoryName * @package PackageName * @author Original Author <author@example.com> * @author Another Author <another@example.com> * @copyright 1997-2005 The PHP Group * @license http://www.php.net/license/3_0.txt PHP License 3.0 * @version Release: @package_version@ * @link http://pear.php.net/package/PackageName * @see NetOther, Net_Sample::Net_Sample() * @since Class available since Release 1.2.0 * @deprecated Class deprecated in Release 2.0.0 */ class Net_Sample { // {{{ properties /** * The status of foo's universe * * Potential values are 'good', 'fair', 'poor' and 'unknown'. * * @var string */ var $foo = 'unknown'; /** * The status of life * * Note that names of private properties or methods must be * preceeded by an underscore. * * @var bool * @access private */ var $_good = true; // }}} // {{{ setFoo() /** * Registers the status of foo's universe * * Summaries for methods should use 3rd person declarative rather * than 2nd person imperative, beginning with a verb phrase. * * Summaries should add description beyond the method's name. The * best method names are "self-documenting", meaning they tell you * basically what the method does. If the summary merely repeats * the method name in sentence form, it is not providing more * information. * * Summary Examples: * + Sets the label (preferred) * + Set the label (avoid) * + This method sets the label (avoid) * * Below are the tags commonly used for methods. A @param tag is * required for each parameter the method has. The @return and * @access tags are mandatory. The @throws tag is required if the * method uses exceptions. @static is required if the method can * be called statically. The remainder should only be used when * necessary. Please use them in the order they appear here. * phpDocumentor has several other tags available, feel free to use * them. * * The @param tag contains the data type, then the parameter's * name, followed by a description. By convention, the first noun in * the description is the data type of the parameter. Articles like * "a", "an", and "the" can precede the noun. The descriptions * should start with a phrase. If further description is necessary, * follow with sentences. Having two spaces between the name and the * description aids readability. * * When writing a phrase, do not capitalize and do not end with a * period: * + the string to be tested * * When writing a phrase followed by a sentence, do not capitalize the * phrase, but end it with a period to distinguish it from the start * of the next sentence: * + the string to be tested. Must use UTF-8 encoding. * * Return tags should contain the data type then a description of * the data returned. The data type can be any of PHP's data types * (int, float, bool, string, array, object, resource, mixed) * and should contain the type primarily returned. For example, if * a method returns an object when things work correctly but false * when an error happens, say 'object' rather than 'mixed.' Use * 'void' if nothing is returned. * * Here's an example of how to format examples: * <code> * require_once 'Net/Sample.php'; * * $s = new Net_Sample(); * if (PEAR::isError($s)) { * echo $s->getMessage() . "\n"; * } * </code> * * Here is an example for non-php example or sample: * <samp> * pear install net_sample * </samp> * * @param string $arg1 the string to quote * @param int $arg2 an integer of how many problems happened. * Indent to the description's starting point * for long ones. * * @return int the integer of the set mode used. FALSE if foo * foo could not be set. * @throws exceptionclass [description] * * @access public * @static * @see Net_Sample::$foo, Net_Other::someMethod() * @since Method available since Release 1.2.0 * @deprecated Method deprecated in Release 2.0.0 */ function setFoo($arg1, $arg2 = 0) { /* * This is a "Block Comment." The format is the same as * Docblock Comments except there is only one asterisk at the * top. phpDocumentor doesn't parse these. */ if ($arg1 == 'good' || $arg1 == 'fair') { $this->foo = $arg1; return 1; } elseif ($arg1 == 'poor' && $arg2 > 1) { $this->foo = 'poor'; return 2; } else { return false; } } // }}} } // }}} /* * Local variables: * tab-width: 4 * c-basic-offset: 4 * c-hanging-comment-ender-p: nil * End: */ ?>

The PEAR toolbox

PEAR provides some tools to help developers keep their code clean and free of coding standards related errors.

For one there is PHP_CodeSniffer which can be used to detect coding standard errors in your scripts. Further, whole PEAR CVS repository is checked each night for violations - the results can be found at PEAR QA results overview page as well as on the linked subpages which explain the errors in detail.

Introduction

PEAR 1.x is very successful at managing the universe of PEAR-installable code. The new Pyrus installer is designed to expand that universe to include code that can also be easily embedded in non-PEAR applications and that runs identically when simply unzipped and when installed. The PEAR2 repository must adhere to different coding conventions than the PEAR repository to make this possible. This document itemizes all the changes to existing rules and coding standards found here. Any conflict between these standards and the existing standards resolves in favor of the new standards. These standards do not affect the coding standards for PEAR packages hosted at pear.php.net, only PEAR2 packages hosted at pear2.php.net.

require_once introduces a rigidity to package structure that limits the possible uses of a PEAR package. Some of the problems:

• require_once can introduce up to a 10% performance penalty on high-volume sites using multi-processor web servers due to increased latency. However, most users would experience at most 2% performance penalty on single-processor systems (as measured by Yahoo! engineer Gopal Vijayaraghavan)

• include_path is required in order to use a package. This makes it difficult to bundle a PEAR package within another application with its own include_path, to create a single file containing needed classes, to move a PEAR package to a phar archive without extensive source code modification.

• When top-level require_once is mixed with conditional require_once, this can result in code that is uncacheable by opcode caches such as APC, which will be bundled with PHP 6.

• Relative require_once requires that include_path already be set up to the correct value, making it impossible to use a package without proper include_path.

Some of the benefits of require_once:

• You know right away if a file is missing, with a Fatal Error: missing file X (this is mitigated by using __autoload() with PEAR2_Autoload()).

• End-users don't need to know what files are within a package to use it (also mitigated by using __autoload() with PEAR2_Autoload()).

The removal of require_once necessitates another method for loading internal dependencies, both files within a package and external files. This proposal introduces 2 possible methods for doing this:

• use __autoload() in conjunction with PEAR2's custom autoload solution (found here in svn)

• construct a customized solution for loading needed files

In all cases, the onus of loading needed files is shifted to the end user. However, for beginning users, the only required step is to load PEAR2/Autoload.php, which will be always bundled with new packages, but only extracted if used as unzip-and-go (pyrus would simply install the dependency on PEAR2, which would contain the needed base files PEAR2_Exception and PEAR2_Autoload).

<?php require '/full/path/to/PEAR2/Autoload.php'; // now you can start using all PEAR2 packages ?>

PEAR2/Autoload.php automatically sets up include_path if it does not contain the correct value, and also automatically declares an autoloader either using __autoload() or spl_autoload_register(), preserving existing autoloaders set up by the user.

Rules

We will describe the list of rules that form the standards

<?php
namespace PEAR2;
class MyClass {}
?>

<?php
namespace PEAR2::HTTP;
class Request {}
?>

<?php
require_once 'PEAR2/OtherPackage.php';
$class = new PEAR2::OtherPackage;
?>

<?php
$class = new PEAR2::OtherPackage;
?>

PEAR2/Package_Name/
    src/      <-- all role="php"
    data/     <-- all role="data"
    tests/    <-- all role="tests"
    doc/      <-- all role="doc"
    www/      <-- all role="www"
    examples/ <-- role="doc" example files 
                  (php executable files that exemplify package usage)

<contents>
  <dir name="/">
  <dir name="src" baseinstalldir="/">
  ...
</contents>

<?php
namespace PEAR2::PackageName;
class Exception extends PEAR2::Exception {}
?>

<?php
...
// retrieve data from info.txt
$info = file_get_contents(dirname(__FILE__) .
    '../../../data/pear2.php.net/PEAR2_PackageName/info.txt');
?>

<?php
if (!class_exists("PEAR2_PackageName_Driver_$class", true)) {
    throw new PEAR2::PackageName::Exception('Unknown driver ' .
    $class . ', be sure the driver exists and is loaded
    prior to use');
}
?>

Introduction

PEAR is an open source project, which means that everyone can help improving it. Improving doesn't always mean writing code. It can also mean reporting bugs, giving feedback, submitting feature requests and even financial support.

Writing New Packages

Explanations about submitting new packages can be found in the Developers' Guide.

Submitting Patches

If you have modified a package to expand its functionality or to fix a bug, you should contribute your changes back to the community (some licenses force you to do so, and it is generally considered immoral not to).

Before creating the patch, you must first obtain the latest sources of the package you wish to patch from CVS by running the commands (the package in this example is Foo_Bar):

cvs -d:pserver:cvsread@cvs.php.net:/repository login password is phpfi cvs -d:pserver:cvsread@cvs.php.net:/repository co pear/Foo_Bar

Now that you have the latest sources, you can edit the relevant file(s). Make sure that your patch is fully compatible with the PEAR coding standards.

After you have finished adding/changing the code, TEST it: We will not accept code that hasn't been carefully tested. When you are absolutely sure the new code doesn't introduce bugs, create a unified diff by running:

cd pear/Foo_Bar cvs diff -u >Foo_Bar.diff

The resulting .diff file contains your patch. This diff makes it easy for us to see what has been changed.

The next step is to submit the patch. There are basically two options to do this: The first option is to submit the patch by creating a bug report for the package in question. You can do this by visiting the package homepage on pear.php.net and clicking on the "Bugs" tab at the top of the page. Another option is sending a mail to pear-dev@lists.php.net and Cc'ing the maintainer(s) of the package. The subject of the mail should be prefixed with '[Patch]' to make it clear you are submitting a patch. Also include a verbose explanation of what the patch does. Don't forget to attach the .diff file to the mail. The maintainers of the package are usually listed in the header of each source file. Apart from that their email addresses are available on the package information page on http://pear.php.net/.

Reporting Bugs

If you think that you have found a bug in a PEAR package, please take care that you are using the latest version of the package and that your system does meet the packages' requirements.

If the bug still persists with the latest version of the package, don't hesitate to fill out a bug report. The easiest way is to click the link "Bugs" on the package information page for the package on the PEAR Homepage, which you think contains a bug. This will take you to a list of existing bugs of the package. Please double check if the bug hasn't already been reported! If you are unable to find it in the list, you can click on "Report new bug" to fill out the bug form.

More information and tips on how to report bugs in a proper way can be found at http://bugs.php.net/how-to-report.php.

If you have already fixed a bug that you have found in a package, please read this.

Writing & Translating Documentation

Good documentation is essential for users to fully understand any software. Several PEAR packages lack documentation or have docs which need improvement. Writing documentation provides more information about helping out on this front.

Translating documentation is another important task. Not only does new documentation need to be translated into the existing languages, additional languages are welcome. Also, existing translations need to be brought up to date because the English versions have been changed. Help on how to perform the translation process is in the Revision Tracking section of the manual.

Wishlists

Some of the PEAR developers have wishlists at Amazon or a similar service. If you appreciate the work of a certain developer, feel free to buy something for her from her wishlist. To find out if a developer has one of those wishlists, go to the account browser, look for the details of the developer and there you'll see if she has a wishlist. Buying something from people's wishlists may even speed up the time in which annoying bugs are fixed ;-).

User FAQ

Developer FAQ

Documentation/translation FAQ

checking for docbook.dsl... autodetected: /path/to/dsssl-stylesheets-x.yz
checking for docbook.xsl... autodetected: /path/to/xsl-stylesheets-x.y.z

Summary of Important points

The following summary of the constitution is only intended to clarify the most important features of the constitution. The text starting with Constitution is the official Constitution of PEAR.

• Most importantly, this document's main purpose is to enable developers to innovate in a supportive environment, to foster good will between developers, to encourage best practices and to provide a clear path for resolving disputes. PEAR is about bringing PHP developers together to provide great solutions to the problems we encounter every day through the PHP language, it is ideal if the constitution is ancillary to the main activity at pear.php.net: coding.

• Developers have supreme power over ultimately what bugs/features will be assigned to specific roadmap versions, and to releasing package versions. Developers will have to cede some control over API decisions/QA/docs to the collective that contains their package. Developers may be expected to mentor a new developer and help introduce them to the systems within PEAR (how to package, document, test, etc.)

• In other words, the bulk of the day-to-day power will remain with developers, but some of the QA decisions and individual ownership will be relinquished to the collective that contains the package.

• Collectives have supreme power over packages within the collective in terms of API decisions, QA, documentation, defining the way collaboration works in the collective, choosing a collective leader or leaders, self-promotion of packages within the collective and assigning mentors to new developers of packages within the collective.

• The PEAR Group only has power over issues that affect all of PEAR such as coding standards, CVS karma, and all major decisions made about PEAR as a whole. For example, licenses allowed and what defines a collective are two issues that only the PEAR Group can resolve.

• The PEAR president has no power over any of the things above, except for the ability to veto a PEAR Group decision. The president cannot create policy. The president's main job is public relations, talking to people outside of PEAR like an ambassador, trying to recruit new developers or bring packages into PEAR, and to solve big emergencies in a hurry such as finding a new hosting provider should the donated space for pear.php.net disappear.

What is the purpose of this document?

• Clarify who is responsible for what actions within PEAR's sprawling complex of packages and developers.

• Define a clear chain of command.

• Create a structure for resolving disputes on all levels.

Official Constitution

Package Directory Structure

This document was issued on 4th November 2003 and describes which directory structure must be used in PEAR packages. The goal of this document is to unify the directory naming in CVS and after installations.

Let's assume we have a package The_Package_Name that contains one or more sub-classes (eg. The_Package_Name_Module), with some documentation (perhaps a README, copies of RFCs, etc.), a battery of test scripts (unit tests, regression tests, etc.), and it uses some data files (localization strings, etc.), the dir tree would look like:

The_Package_Name
|-- Name (contains Module.php)
|-- data
|-- docs
|   `-- examples
|-- misc
|-- scripts
`-- tests

Name refers to the last part of the The_Package_Name, all subclasses of the main class, should be put in there or subdirectories of it. You can refer to http://cvs.php.net/cvs.php/pear/Cache_Lite/ - the directory Lite as an example (this basically documents what we currently do anyway).

The data and misc directories are optional, because it will not make sense to have them for every single package in PEAR.

The directories that are required are docs/examples and tests. A package may have no extra documentation, but it should have at least one example. There must also be some basics test to be able to verify that the package is working. The preferred type of testing script system to use is PHPUnit or .phpt. But for now we would be content with any sort of test script.

Files in scripts will be installed into a directory available in $PATH, such as /usr/local/bin.

Anything that does not fit any of the above categories is placed into the misc directory.

Maintainers are expected to modify their existing packages to match this new standard.

License Announcement

This document was issued on 02 April 2004 and was revised on 08 January 2006 when adding the MIT License. It lists the licenses that PEAR packages can be released under.

The PEAR Group would like to announce the following refinement of the current license FAQ entry.

Vote result: 5 (+1), 0 (-1), 3 (+0)

The current list allows a great number of licenses which vary greatly. This means that users may have to learn the in's and out's of a lot of licenses. Also some of the license choices impose comparatively high restrictions to the standard PHP license (GPL, QPL ..). As PEAR aims to extend the functionality provided by PHP users of PHP should fairly safely be able to also use any PEAR package without licensing worries, be it for commercial or non commercial, closed or opensource use.

Therefore with this announcement the license choices are reduced to the following short list:

• PHP License

• Apache License

• LGPL

• BSD style

• MIT License

Other licenses may be accepted on a case by case basis, but will have to fit the above criteria. This decision has been made to simplify the current situation, and as with all decisions is open to be refined in the future using the RFC proposal methodology.

All packages, which are already part of PEAR as of now, which use other licenses, do not need to follow this regulation.

New guidelines for BC breaking releases

This document has been published on 14th November 2003 and describes how releases that break backwards compatibility (BC) have to be handled.

The goal is to make it possible to be able to run multiple major versions in one script.

For this reason new major versions (BC break or when the maintainer feels it makes sense as a result of dramatic feature additions or rewrites) require a new package using the following naming convention in the following order of preference (where 'Foo' is the package name and 'X' the major version number):

1. FooX

2. FoovX

3. Foo_vX

The choice should be made based on preventing current and future misleading or ambiguous names. This means good care should be taken in making the right choice for the package. Obviously the first two allow for some ambiguity (is DB2 a package for IBM's DB2 or just the major version 2 of DB? - is IPv4 a package for IPv4 or is it the 4th major release if IP?). They don't break the idea of "_" mapping to directories (the class DB_NestedSet implies that there is a nestedset.php in the DB dir). The last one prevents any ambiguity but it's the least visually pleasing and also breaks the '_' to directory mapping and is therefore the last choice.

We also came to the conclusion that the pear installer should not be clever about the relationship between two major releases aside from printing out notices about the fact that there is a newer major version when a user installs an earlier one. However all major versions of a package will be listed on one package home. This is especially important in order to not break tutorials that cover older major releases (tutorial xyz for major version 1 simply says 'pear install Foo' - if the system would then install 'Foo2' the user might be in for an unpleasant surprise).

Therefore, new major versions are for all intents and purposes new packages with the above mentioned exceptions. The names of these new packages are derived using one of the above mentioned naming conventions.

Orphaned Packages

Orphaned PEPr Proposals

Cases in which it makes sense to propose a new package

As you may have already noticed while browsing the list of existing packages, the PEAR packages provide a (often abstract) solution for a general problem. Thus your code will most likely fit into PEAR if it solves a problem that will not only occur in one (e.g. your) specific application, but that occurs in a lot of (web) applications. Examples are:

• Support for Network protocols

• Object oriented wrappers that provide easy access to otherwise complicated or less intuitive PHP extensions.

• Parsing different XML dialects.

  The PEAR packages that provide XML parsing functionalities can be found in the category browser.

No matter which area is covered by a package, the API should be as abstract as possible (while not becoming too complex), so that it can be utilized painlessly in as much use cases as possible.

Cases in which it is better to improve existing packages

There are two kinds of packages that are not likely to be accepted as new contributions to PEAR:

1. A package that duplicates an existing package very closely

2. A framework or other full-fledged web application

There are exceptions to the duplication rule, for instance a package that requires a higher PHP version, and takes advantage of newer versions in PHP will definitely be considered seriously. Also, packages that provide a completely new paradigm for accessing the same thing are a good candidate for consideration.

Frameworks or other applications may also be considered if they are developer tools, such as phpDocumentor. However, if you have a great idea that you think would fit into PEAR, don't let this document discourage you. PEAR developers can be surprisingly open to new ideas. Remember, the best ideas are well documented and carefully presented. Be prepared to have patience and thick skin! We are a picky bunch about quality, but in the end we will all learn a lot and develop some stellar code in the process.

As the parameters for proposing a package change, this site will be regularly updated.

Communication with other PEAR developers

Mailing lists are the most important way to communicate in PEAR. We are running a number of public mailing lists, which are listed on the PEAR website. For starters the PEAR developers mailing list pear-dev@lists.php.net is the primary place where discuss various aspects of their packages and of the PEAR repository as a whole. pear-general@lists.php.net is a general support list that should be used for questions on using PEAR packages, installing PEAR, and other issues not directly related to the development of PEAR packages.

If you would like to get started with maintaining packages in PEAR, you are expected to be subscribed to pear-dev@lists.php.net. (Subscription instructions)

Some people enjoy communicating via IRC channels. We are running the #pear channel in the EFnet network. Some of the most active PEAR developers hang out regularly on this channel. However, for serious inquiries or discussions, you should email the developers mailing list pear-dev@lists.php.net, as these discussions are the only official communication method of PEAR, and are archived for future reference.

More written information

• The PEAR Group occasionally publishes Administrative Documents, which describe the Group's decisions. You should read those documents before starting serious contributions to PEAR, because they contain important information about the inner workings of PEAR. The developers mailing list will be informed when new documents are added.

• This manual contains the Developer Guide, which provides valuable information for using the tools of a PEAR developer.

• The Coding Standards describe the standards which PEAR code must adhere to.

Step 1: Requirements for a proposal

The following enumeration lists the most important things that need to be done or be made available before starting a new proposal.

• Finding a name for the package

  It is obvious that each package needs to have a unique name. To get a "feeling" for proper package names, you should browse the list of existing packages.

  Choosing a name for the package is an iterative process and it is likely that you will change the name at a later stage of the proposal process.

• Finding a category for the package

  Similar to each package having a unique name, it has to be placed in one of the categories, which are listed in the package browser as well.

• Writing a package description

  For starting the proposal you will need to write a description of the package. This description does not need to mention every detail of the package, but it should at least outline the basic concept and feature set. When your package has been accepted, you will have to come up with a single-line summary and a fulltext description.

• Choosing a license for the package

  Each package has to be licensed under an accepted OpenSource license. If you are unsure about the license, you should opt for the PHP License. The PEAR Group has issued a License Announcement, which provides further details concerning this topic.

• Writing examples and documentation

  Without proper usage examples and documentation, neither will the PEAR developers be able to evaluate your package nor will users be able to make use of your package.

• Listing dependencies

  Making a list of dependencies basically means that you write down all external entities such as other PEAR packages, certain operating systems or external applications, which are required to use your proposed package.

  Example 13-1. Example for a dependency list If your package does only work on Linux, requires the DB package, version 1.8.4 or higher of the Log package and at least PHP 4.3.0, your dependency list looks like this: Linux DB Log >= 1.8.4 PHP >= 4.3.0

Step 2: Initiating a discussion

For every package you should start a proposal in PEPr as a draft to initiate discussion on the developers mailing list.

By discussing the package with the PEAR developers you will easily be able to find out if:

• there are technical issues with the package/code

• a package with similar functionality already exists

• there are people working on something similar, so you can join forces

• etc.

By reading between the lines, you should also be able to find out if you will be able to gather enough positive votes in the formal proposal process.

Be aware that people will scrutinize your code, so be prepared for criticism (both positive and negative) and save everybody a bunch of time by making sure your scripts adhere to the Coding Standards.

Please note that PEAR is an international project. People come from different cultural backgrounds where English may not be their native tongue. Misunderstandings may happen because of that, so assume the person is trying to do good. Do not worry if your English is not perfect but do try to be as clear as possible and do not hesitate to ask for advice.

Step 3: Using PEPr

To be able to use the proposal tool (PEPr), you have to apply for a PEAR website account. This account will usually be granted within one or two days. After that you can open a new proposal using the "New Package Proposal" interface.

The package proposal process is divided into 4 stages: "Draft", "Proposal", "Call for Votes" and "Finished". Every proposal has to run through all of these stages. During each stage (except for the draft stage) an email is send to you (the proposer) and the PEAR developers mailing list for any action.

Changing a proposal

In general you may not edit or delete your proposal after it has left the Proposal stage. In urgent cases you can contact the PEAR community via the developers mailing list to reach a PEAR website administrator to do a change. This is heavily discouraged however! You should have made everything clear to the community during the Proposal stage to ensure a hassle free voting process. Even if the voting has a negative result, this is no reason to delete it.

Who needs this guide?

The intention of this guide is to provide you, a new developer of PEAR packages, with all necessary information to start working effectively.

The first part of this guide covers the advantages a developer has when using PEAR code in everyday work. After that we will show you how to contribute your own code to PEAR. Finally the guide describes the ways a developer can give back to the PEAR project.

Code of high quality

PEAR is first and foremost a repository of reliable and high quality code. All packages comply with the PEAR Coding Standards. A new PEAR package should provide an API that is consistent, be written for PHP version 5.0.0 or newer, make use of PEAR_Exception for error handling, and adhere to the requirements of the package collective that it is accepted into.

Chance to collaborate with and learn from other developers

PEAR provides a stable, robust community of developers with years of experience and a great place to collaborate. New and exciting ways of using PHP to solve the most pressing problems of web development and beyond happen here in PEAR every day.

Chance to release your own code

PEAR gives you the chance to contribute your code to an enormous number of PHP developers: To get more information about how to contribute your code in PEAR, read here.

Requirements for contributing code

We are making certain demands on both the code and the maintainers of packages:

1. Code must conform to the Coding Standards.

   If you want to contribute your code to PEAR in form of a new package or as an addition to an existing package, it has to be compliant to a set of Coding Standards. There have been numerous discussions about whether those standards are good or not, and we have arbitrarily decided that they are good and that the discussion is over. Please respect this decision and don't bring up changes to the basic coding standards, or you risk being ignored mercilessly.

2. Code must be appropriately licensed.

   Each package has to be licensed under an accepted OpenSource license. If you are unsure about the license, you should opt for the New BSD License. The PEAR Group has issued a License Announcement, which provides further details concerning this topic.

3. Code must be available in public code repository.

   The latest revision of the package's source code has to be available in a public SCM (Source Code Management) system such as the CVS server at cvs.php.net, the Subversion repository of Google Code, or at sites such as SourceForge. Hosting at Google Code or SourceForge is freely available under their terms of use at any time. Write access to cvs.php.net is available once the package has been accepted as a PEAR package.

   All packages must have a publicly available source repository in order to honor the need for access in order to provide patches for bugs or new features.

4. Extensible and "forward-compatible" code.

   Always keep in mind that your code should be extensible and that it has to be easy to add new features in the future. If it is easily predictable for you that there is no clean way to add new functionality to the codebase without breaking backwards compatibility, you should consider to review the code and to adapt it, before contributing it to PEAR.

   To this end, most PEAR packages make use of object oriented programming. Through concepts such as inheritance, polymorphism, patterns like singleton/factory/command, PEAR packages solve problems in elegant ways. There are numerous resources about object oriented programming all around the web and you will also find tons of books available for your reading pleasure. However we can can recommend Object-Oriented Programming Concepts on Sun's Java Homepage for a quick start.

5. Documentation in an appropriate format (plain text, docbook)

   Your code must come with appropriate documentation in one of the following formats:

   • Docbook XML

   • Plain Text

   If you write the documentation in Docbook XML and if the markup is valid, the documentation can be easily added to the official PEAR Manual, which you are reading right now.

   Note: As of August 2003, phpDocumentor is fully capable of converting in-code API documentation and external tutorials into Docbook XML. PhpDocumentor version 1.2.2 or greater is required. Install with pear install phpDocumentor. Use the XML:DocBook/peardoc2:default converter on your source code to generate output. The output should be generated directly into the peardoc/lang/package directory, where lang is en, or fr, etc.

   Be aware though that only shipping the API documentation does not suffice! Additionally your package has to come with usage examples and (even better) tutorials about its usage. More information can be found in the section describing how to write documentation

6. Regression tests in .phpt or PHPUnit format

   All developers have experienced the frustration of bugs. They are a fact of life in programming, but fortunately there are a few systems that can be used to catch them, kill them, and prevent their return. Regression tests should be included with every stable release, so that users can run them if a bug occurs to help you debug the package. Examples of .phpt regression tests can be found as part of the PEAR package in CVS. For examples of PHPUnit tests, see the Auth package.

7. The contributor ("you") must be willing to provide support for the package and must be willing to release future versions that at the very least fix bugs.

   If you are not willing to maintain your code over a long period of time, it makes little sense to contribute it. PEAR is the standard repository of PHP packages, and this comes with great responsibility. Maintaining means more than just providing support via the various mailing lists:

   You must be willing to not only fix bugs, but also integrate useful enhancements contributed by users of your packages, if they fit the design specifications of your package. You should expect to release new versions of your package regularly with bug fixes. If you will be unable to maintain your package for an extended period of time, it is expected that you will announce this to the PEAR developer mailing list, and assign another temporary lead maintainer or publicly document the fact that your package is temporarily unmaintained, and the approximate date that users can expect to receive support and bug fixes, if possible.

   Warning

   Code can be removed from PEAR if the lead maintainers are not willing to maintain the code anymore and if there is no other person that is willing to take over as the maintainer.

How to contribute code in practice

1. Finding an appropriate package name

   One of the most important tasks while contributing a new package to PEAR is finding an appropriate name for your package.

   The general syntax for package names is <Category>_<Name>. The value for <Category> should be chosen from a predefined list of categories that are available in PEAR (e.g. "HTTP", "Net", "HTML"). The second part is the name of the package (like "Upload", "Portscan", "Table").

   The categories that are currently available in PEAR are represented by the bold headings at the Package Browser. If you think that your package does not fit in any of the existing categories, you can ask the on the mailing list to create a new category. (PEAR is usually reluctant to do that.)

   Apart from this general syntax, the package names can also contain more than one category name. An example for this is HTML_Template_PHPLIB: The multiple categories indicate that the package PHPLIB is part of the category Template, that again is part of the HTML category. This naming scheme is necessary here since it's possible that there are Template systems in PEAR that don't work with HTML but with another technology. (The cases where more than one "category" is used are pretty rare.)

   If you need further advice or help for finding a name for your package, you should ask on the developers mailing list.

2. Announcing to the PEAR developers

   The second step while contributing is to announce your package in PEPr. Usually this announcement will spawn some discussion. After one week you may call for votes with PEPr and the developers will then start to vote for or against your proposal. (You are of course urged to join the upcoming discussion.) Announcing a package does of course not mean that it is already accepted! That will still take some time and likely some more efforts from your side.

   Note: The following passages are taken from the administrative document Handling Package Proposals, which describes proposing new packages in more details. Reading this document should be a mandatory step for PEAR newbies.

   Only the votes of active members of the PEAR community (must have a PEAR web account, however the proposer himself is not counted) are counted, however anyone may vote. Votes require that a final choice of package name is specified.

   The votes are added up, which means that one -1 offsets a +1. However -1 vote should always be considered to be serious and may lead to decisions being made on a case by case basis by the PEAR Group who reserves a veto (it is intended that in the future the PEAR QA team will assist the PEAR Group in such situations). Therefore a -1 vote *must* contain a comment explaining that decision, it is desirable that votes in favour (+1) should also be accompanied with an explanation when appropriate.

   A vote is accepted if the total of all votes exceeds +5.

   In case the proposal is not accepted the package can be further discussed on the list and the proposer may attempt to make another "call for vote" (it is expected that this is only done for sensible reasons).

3. Getting the necessary accounts

   Right now one can distinguish between two types of accounts related to PEAR:

   1. Pear.php.net account

      This account is always necessary for you, if you want to release your package through PEAR. With this account you have access to the necessary infrastructure on pear.php.net in order to propose, upload and roll new releases. The PEAR Group manages PEAR accounts and pearweb karma levels (i.e.: karma to use the web site to maintain packages).

   2. PHP CVS account

      If you want to administrate your code via CVS , you can also apply for a CVS account to have access to the pear CVS module on cvs.php.net. This makes it easier for other users to contribute to your code. The PHP Group (group@php.net) manage the PHP CVS server, which is used for maintaining PEAR packages. If you already have a PHP CVS account you will ask the PEAR Group for Karma for a given package or set of packages. Please send an email to pear-group@php.net specifying what packages you need commit access along with credentials (e.g.: the package "lead" email giving you his go or a QA member email announcing you are to be given access).

      If you already have a CVS repository somewhere else (e.g. on SourceForge), or if you don't want to maintain your code via CVS, you don't need the PHP CVS account. It is highly recommended to use some kind of public repository, so that users can try out any bug fixes you apply to the code, before a new release is rolled.

   To sign up for your pear.php.net account, go to the PEAR account request page and fill out the form there. The PEAR Group will then receive your request and someone will open your account, if the request sounds reasonable. You will be notified about that via email. Please note that you do NOT need a pear.php.net account to download packages from there.

   To get a PHP CVS account, go here to sign up for it. The PHP CVS account has to be approved by the PHP Group.

4. Registering the package

   Once you successfully went through the contribution procedure and got your pear.php.net account, you finish with registering your package. Registering does not mean that you are going to release a first version of your package. It just means that some basic information about the package will be added to the PEAR package database.

   The registration process is quite straightforward: Fill out the form on this site and submit the information. After you have done that, the PEAR Group has to finally approve your submission. This usually happens in a few hours and you will be notified about it via email.

   After having registered your package, you can create a first release, which is described here.

How to document code in practice

Writing documentation is covered in a dedicated section.

Introduction to the package definition file package.xml

The package definition file package.xml is, as the name already implies, a well-formed XML file that contains all information about a PEAR package.

This chapter will describe the allowed elements of the package definition file and it will discuss how to create such a file for your package.

The PEAR_PackageFileManager package simplifies the creation of package.xml. You can install PEAR_PackageFileManager via the usual command

$ pear install PEAR_PackageFileManager

A quick and dirty guide to version 2.0 of the package definition file package.xml

The package definition file package.xml is, as the name already implies, a well-formed XML file that contains all information about a PEAR package. Version 2.0 contains several important enhancements over version 1.0, including

• Channel support

• Binary PECL packages support (not fully implemented in PEAR 1.4.0)

• More specific dependency resolution

PECL developers: for more information on pecl-specific features, read here.

Special information for PECL developers

extsrcrelease and extbinrelease changes for PECL developers

<providesextension>PDO</providesextension>

<name>PDO_windowsbin</name>
<channel>pecl.php.net</channel>
<!-- snip -->
<providesextension>PDO</providesextension>
<srcpackage>PDO</srcpackage>

<name>Foo_windowsbin</name>
<uri>http://www.example.com/Foo_windowsbin-1.5.0.tgz</uri>
<!-- snip -->
<providesextension>Foo</providesextension>
<srcuri>http://www.example.com/Foo-1.5.0.tgz</srcuri>

Detailed Tag Reference for package.xml version 2.0

Each tag that needs further explanation is documented here (unfinished)

<channel>

<uri>

<lead>, <developer>, <contributor>, and <helper>

<version>

<stability>

<license>

<contents>

<dir>

<file>

tasks for <file>s

<compatible>

<dependencies>

<dep type="pkg" rel="has">Foo</dep>

<package>
 <name>Foo</name>
 <channel>pear.php.net</channel>
</package>

<dep type="pkg" rel="ge" version="1.0.0">Foo</dep>

<package>
 <name>Foo</name>
 <channel>pear.php.net</channel>
 <min>1.0.0</min>
</package>

<dep type="pkg" rel="gt" version="1.0.0">Foo</dep>

<package>
 <name>Foo</name>
 <channel>pear.php.net</channel>
 <min>1.0.0</min>
 <exclude>1.0.0</exclude>
</package>

<dep type="pkg" rel="le" version="1.0.0">Foo</dep>

<package>
 <name>Foo</name>
 <channel>pear.php.net</channel>
 <max>1.0.0</max>
</package>

<dep type="pkg" rel="ge" version="1.0.0">Foo</dep>

<package>
 <name>Foo</name>
 <channel>pear.php.net</channel>
 <max>1.0.0</max>
 <exclude>1.0.0</exclude>
</package>

<dep type="pkg" rel="ge" version="1.0.0">Foo</dep>
<dep type="pkg" rel="le" version="1.9.0">Foo</dep>

<package>
 <name>Foo</name>
 <channel>pear.php.net</channel>
 <min>1.0.0</min>
 <max>1.9.0</max>
</package>

<dep type="pkg" rel="not">Foo</dep>

<package>
 <name>Foo</name>
 <channel>pear.php.net</channel>
 <conflicts/>
</package>

<usesrole>

<usestask>

<phprelease>, <extbinrelease>, <extsrcrelease>, <bundle>

Prerequisites

Rolling a new release requires that the package to which the release belongs has been approved by the PEAR developers and that you have a valid PEAR website account. Information about meeting these two requirements can be found in the chapter Contributing your own code.

Please also read the various PEAR Group regulations that cover aspects like Version Naming, File Layout and other important topics not yet discussed in this manual. Furthermore there are a number of RFC's that followed these group regulations. These can be found under R for RFC in the finished PEPr proposals. Unfortunately these documents have not yet been included in a summarized coherent format in this manual. Please ask questions if you are in doubt about any of these documents.

Validating The Package Definition File

Next, you should check the package definition file (package.xml) for validity. This is done by running the command: pear package-validate package.xml. Fix the errors and warnings, if any, and proceed to the next step.

Packaging The Release Tarball

Now that your package has a valid package definition file, you can package the release tarball. Cd to the top-level directory of the package and run: pear package This will create the release tarball that will be used later to upload the new release.

Releasing The Package Through The Web Interface

First, you should login to the PEAR website using the account you've been given (see the first step).

Now, finally, you can release your package. This is done again using the convenient web interface. Use the form at http://pear.php.net/release-upload.php.

That's it! Your package has been released, an announcement has been sent to the mailing lists.

How to support the PEAR community

There are numerous ways to support the PEAR project, that are described in this part of the guide.

Why recommendations?

The following recommendations describe topics which were discussed and agreed upon by the PEAR developers on the developers mailinglist. They aren't strict rules, which you need to follow (like Coding Standards), but are intended as guidelines for a common API scheme and easier package interoperability. Please consider following them in your packages where possible.

Color Representation inside PEAR Packages

In case a package has to deal with colors, it is recommended that developers store and use an array representation of the color values in their PEAR packages. All values are in the range of 0..255.

The DocBook XML format

DocBook is an XML dialect that is used by a wide range of projects to maintain their documentation. Examples for DocBook usage in OpenSource projects are the documentations of KDE and PHP. PEAR has opted for using DocBook, because we believe that it provides a solid foundation for the technical documentation for PEAR packages.

The trade-off for using DocBook is that it is relatively hard to use. Testing documentation requires a number of tools to be installed and one needs to learn a (not very complicated) XML dialect. Once one is familiar with how DocBook works, they will enjoy writing documentation with it though.

The book [DocBook: The Definitive Guide], written by Norman Walsh and Leonard Muellner and published by O'Reilly & Associates, Inc., is available online and it makes up a great resource for people interested in learning DocBook.

Definitely check out the book's "DocBook Element Reference" section. This portion provides detailed information about each element, including which elements can (and must) be used as parents and children.

$ cvs -d :pserver:<user>@cvs.php.net:/repository login
     
     
[password]
     
     
$ cvs -d :pserver:<user>@cvs.php.net:/repository co peardoc
     

peardoc$ autoconf
peardoc$ ./configure --with-lang=en
peardoc$ make html
        

checking for docbook.dsl... defaulting - WARNING!!!
DSSSL NOT FOUND - WON'T WORK THIS WAY

peardoc$ ./make-partial.php
Include about-pear? [NO]
Include guide-newmaint? [NO]
Include guide-developers? [NO] y
Include guide.developers.intro? [NO]
Include guide.developers.meaning? [NO]
Include guide.developers.contributing? [NO]
Include guide.developers.packagedef? [NO]
Include guide.developers.release? [NO]
Include guide.developers.supporting? [NO]
Include guide.developers.recommendations? [NO]
Include guide.developers.documentation? [NO] y
Include core? [NO]
Include packages? [NO] y
Include package.authentication? [NO]
Include package.benchmarking? [NO]
Include package.caching? [NO]
Include package.configuration? [NO]
Include package.console? [NO]
Include package.database? [NO]
Include package.datetime? [NO]
Include package.encryption? [NO]
Include package.fileformats? [NO]
Include package.filesystem? [NO]
Include package.gtk? [NO]
Include package.html? [NO]
Include package.http? [NO] y
Include package.images? [NO]
Include package.internationalization? [NO]
Include package.logging? [NO]
Include package.mail? [NO]
Include package.math? [NO]
Include package.networking? [NO]
Include package.numbers? [NO]
Include package.payment? [NO]
Include package.pear? [NO]
Include package.php? [NO]
Include package.science? [NO]
Include package.streams? [NO]
Include package.structures? [NO]
Include package.system? [NO]
Include package.text? [NO]
Include package.tools? [NO]
Include package.xml? [NO]
Include package.webservices? [NO]
CONFIG_FILES=manual.xml CONFIG_HEADERS= ./config.status
creating manual.xml
/usr/bin/jade -wno-idref  -d html.dsl -V use-output-dir -t sgml ./phpdocxml.dcl manual.xml
         

Tips for good documentation

This section of the chapter does not deal with the specifics of organizing documentation in the peardoc standard, but instead with how to organize documentation logically.

1. First, every package solves a problem. What is this problem? Try to figure out what assumptions your end-users might not have about the problem (they may not realize that this is a problem that needs solving). For instance, a template package solves the problem of both separating design from code, and separating business logic from display logic. If possible, explain the problem in terms that even a novice programmer can understand.

2. Next, how does the package uniquely solve the problem? This is something that most documentation lacks. For example, there are many template engines. All of them solve the same problem, but none of them do it in the same way. A block-based template engine does not have any logic at all, whereas a template like Smarty defines a whole new template language. Some template engines compile their templates, others don't. What is unique about your package? Can someone who has never seen the code get a good idea of how it solves the problem?

3. Provide examples! Start right away with simple examples that show the basic feature set -- they will show users how to quickly start using the package. More complex examples will help the users in understanding advanced ways of using the package.

4. If your package exposes complex interfaces or multiple constants that can't be fully explained in one or two examples (which is very likely), it is still important to explain them thoroughly in the documentation. Document any interfaces that users must use, such as a database DSN, command-line arguments for applications, configuration file contents, or any other non-code elements.

5. Last, proofread your documentation. If possible, have someone else who is not as familiar with your project take a look at the documentation. They will catch assumptions that you have missed.

Using a customized role in a package.xml

To use a custom installation role that another programmer has written, there are three steps that are necessary. First, the <usesrole> tag should be used to define each custom role that is used in the package.xml. Next, the role should simply be used for the files it pertains to. Finally, a dependency on the package that provides the custom role should be added to the package.xml, just for completeness.

Pretty simple!

Defining a customized role for use in a package.xml

To define a custom role, you need to create a package containing a single file. Here is a sample package.xml that could be a custom role:

<?xml version="1.0"?> <package version="2.0" xmlns="http://pear.php.net/dtd/package-2.0" xmlns:tasks="http://pear.php.net/dtd/tasks-1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://pear.php.net/dtd/tasks-1.0 http://pear.php.net/dtd/tasks-1.0.xsd http://pear.php.net/dtd/package-2.0 http://pear.php.net/dtd/package-2.0.xsd"> <name>Chiarafoo</name> <channel>pear.chiaraquartet.net</channel> <summary>Chiarafoo role</summary> <description> The chiarafoo role installs files into your customized Foo directory </description> <lead> <name>Greg Beaver</name> <user>cellog</user> <email>cellog@php.net</email> <active>yes</active> </lead> <date>2005-03-21</date> <version> <release>1.0.0</release> <api>1.0.0</api> </version> <stability> <release>stable</release> <api>stable</api> </stability> <license uri="http://www.php.net/license">PHP License</license> <notes> Provides the chiarafoo file role </notes> <contents> <dir name="/" baseinstalldir="PEAR/Installer/Role"> <file name="Chiarafoo.xml" role="php"/> <file name="Chiarafoo.php" role="php"> <tasks:replace from="@package_version@" to="version" type="package-info"/> </file> </dir> <!-- / --> </contents> <dependencies> <required> <php> <min>4.2.0</min> </php> <pearinstaller> <min>1.4.3</min> </pearinstaller> </required> </dependencies> <phprelease/> </package>

The XML file Chiarafoo.xml should be similar to this file:

<role version="1.0"> <releasetypes>php</releasetypes> <installable>1</installable> <locationconfig>foo_dir</locationconfig> <honorsbaseinstall>1</honorsbaseinstall> <unusualbaseinstall /> <phpfile>1</phpfile> <executable /> <phpextension /> <config_vars> <foo_dir> <type>directory</type> <default><php_dir/><constant>DIRECTORY_SEPARATOR</constant><text>Foo</text></default> <doc>directory where foo files are installed</doc> <prompt>PHP foo directory</prompt> <group>File Locations</group> </foo_dir> </config_vars> </role>

The script in Chiarafoo.php is incredibly simple:

<?php /** * PEAR_Installer_Role_Chiarafoo * * PHP versions 4 and 5 * * LICENSE: This source file is subject to version 3.0 of the PHP license * that is available through the world-wide-web at the following URI: * http://www.php.net/license/3_0.txt. If you did not receive a copy of * the PHP License and are unable to obtain it through the web, please * send a note to license@php.net so we can mail you a copy immediately. * * @category pear * @package Chiarafoo * @author Greg Beaver <cellog@php.net> * @copyright 2005 Greg Beaver * @license http://www.php.net/license/3_0.txt PHP License 3.0 * @version CVS: $Id: customroles.xml,v 1.4 2005/11/03 05:06:52 cellog Exp $ * @link http://pear.chiaraquartet.net/index.php?package=Chiarafoo * @since File available since Release 0.1.0 */ /** * @category pear * @package Chiarafoo * @author Greg Beaver <cellog@php.net> * @copyright 2005 Greg Beaver * @license http://www.php.net/license/3_0.txt PHP License 3.0 * @version Release: @package_version@ * @link http://pear.chiaraquartet.net/index.php?package=Chiarafoo * @since Class available since Release 0.1.0 */ class PEAR_Installer_Role_Chiarafoo extends PEAR_Installer_Role_Common { /** * @param PEAR_Installer * @param PEAR_PackageFile_v2 * @param array file attributes * @param string relative path to file in package.xml */ function setup(&$installer, $pkg, $atts, $file) { // do something special with the installer } } ?>

Since PEAR 1.4.3, nothing else is necessary for a successful implementation of a file role.

The contents of the role's XML file must contain these tags:

• <releasetypes>

• <installable>

• <locationconfig>

• <honorsbaseinstall>

• <unusualbaseinstall>

• <phpfile>

• <executable>

• <phpextension>

• (optional) <config_vars>

Using a customized task in a package.xml

Tasks are defined in package.xml through the tasks namespace, which is currently http://pear.php.net/dtd/tasks-1.0. The current tasks namespace is defined by http://pear.php.net/dtd/tasks-1.0.xsd. Custom tasks bundled with PEAR include:

• <tasks:replace>

• <tasks:unixeol>

• <tasks:windowseol>

• <tasks:postinstallscript>

The xml for each of these tasks is documented here.

Creating customized tasks in PHP

Creating a custom task involves creating a class that validates xml, and performs the task when called upon. Tasks can be invoked in two situations: at package-time and at install-time. Each task can control whether it should be called at package-time, install-time, or at both times.

There are two kinds of tasks: simple and multiple. Most tasks are simple tasks. Simple tasks are self-contained: all customization is limited to that file. Multiple tasks are collected during installation and processed fully as a unit after files have been committed to disk, allowing more complex processing.

All simple tasks must define 3 methods, all multiple tasks must define 4 methods. These are:

• validateXml()

• init()

• startSession()

• run() (multiple tasks only)

Naming requirements for a post-install script PHP file

Post-install script files can be named anything one desires, but the class within the file must be the same name as the file with all path separators replaced by underscores. In other words, this postinstall script:

Path/To/Script.php

Must contain a class named Path_To_Script. Due to casing differences between operating systems, it is recommended to always use lowercased file names.

Structure of a post-install script

The post-install script class must contain two methods, one named init(), and the other named run(). The init() method is called at the same time as all other post-install scripts. The run() method is called at the conclusion of each parameter group in order to process the user's responses to queries.

PEAR

PEAR provides functions for handling errors and sets the behaviour in case of error. And, it gives package developers a set of functions to make their lives easier.

Introduction

require_once "PEAR.php";

class classname extends PEAR { ... }

Constants

PEAR::PEAR()

require_once 'PEAR.php';

PEAR::_PEAR()

require_once 'PEAR.php';

PEAR::getStaticProperty()

require_once 'PEAR.php';

<?php

require_once 'PEAR.php';

class myClass {

function setValue( $set) 
{
 $foo = &PEAR::getStaticProperty('myClass', "foo");
 $foo = $set;
}

function view()
{
 print PEAR::getStaticProperty('myClass', "foo");
}

}

myClass::setValue('value = foo');
myClass::view();
?>

value = foo

PEAR::registerShutdownFunc()