PEAR Manual List of authors Edited by Martin Jansen Alexander Merz 26-09-2004 Copyright © 2001, 2002, 2003, 2004 by The PEAR Documentation Group Copyright Copyright © 2001 - 2004 by the PEAR Documentation Group. This material may be distributed only subject to the terms and conditions set forth in the Open Publication License, v1.0 or later (the latest version is presently available at http://www.opencontent.org/openpub/). Distribution of substantively modified versions of this document is prohibited without the explicit permission of the copyright holder. Distribution of the work or derivative of the work in any standard (paper) book form is prohibited unless prior permission is obtained from the copyright holder. The PEAR Documentation Group consists of all the people that have contributed documentation to the PEAR manual. Representatives are listed on the front page of this manual. In case you would like to contact the group, please write to pear-doc@lists.php.net. Copyright for the XML_RPC documentation The documentation of the XML_RPC package has originally been written by Edd Dumbill as an independent document on his homepage and is published as part of the PEAR Manual under the following license restrictions: Copyright © 1999,2000,2001 by Edd Dumbill, Useful Information Company All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of the "XML-RPC for PHP" nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. _________________________________________________________________ Table of Contents Preface About this Manual The structure of the Manual Authors and Contributors I. About PEAR 1. Introduction 2. Installation 3. Support 4. Coding Standards 5. Contributing 6. FAQ - Frequently Asked Questions II. New Maintainers' Guide 7. Introduction 8. When to contribute (and when not to contribute) 9. Getting started with the community 10. The formal proposal process III. Developer Guide 11. Introduction 12. PEAR's meaning for developers 13. Contributing your own code 14. The package definition file package.xml 15. Releasing A Package 16. Supporting PEAR development 17. Recommendations 18. Writing documentation IV. Core components 19. PEAR base classes 20. PPM classes V. Packages 21. Authentication 22. Benchmarking 23. Caching 24. Configuration 25. Console 26. Database 27. Date and Time 28. Encryption 29. File Formats 30. File System 31. HTML 32. HTTP 33. Images 34. Internationalization 35. Logging 36. Mail 37. Math 38. Networking 39. Numbers 40. Payment 41. PEAR 42. PHP 43. Science 44. Streams 45. System 46. Text 47. Tools and Utilities 48. XML 49. Web Services VI. PECL Packages I. Advanced PHP debugger II. PHP bytecode Compiler III. Imagick IV. KADM5 V. Radius VI. Paradox File Access VII. PostScript document creation VIII. Satellite CORBA client extension IX. PostgreSQL Session Save Handler X. Soap XI. SPPLUS Payment System XII. Net_Gopher XIII. oggvorbis _________________________________________________________________ Preface PEAR is the PHP Extension and Application Repository. _________________________________________________________________ About this Manual This manual is written in XML using the DocBook XML DTD, using DSSSL (Document Style and Semantics Specification Language) for formatting. The tools used for formatting HTML versions are Jade, written by James Clark and The Modular DocBook Stylesheets written by Norman Walsh. The basic structure is based on the great work already done by the PHP documentation group. Read About the PHP manual for more details. _________________________________________________________________ The structure of the Manual This guide explains the general structure, layout, and conventions used in the PEAR manual. The manual is divided into six main parts, they are: * About PEAR This section contains a gentle introduction to what PEAR is and has to offer. Included is general information about installing and using PEAR, support options, and answers to frequently asked PEAR related questions. * Developer Guide General information about developing and releasing PEAR-Packages. * Core components This section contains documentation about the core PEAR classes. These core components are the base to every PEAR class and understanding the basics will allow general use of the PEAR library. Topics include the PEAR base, PEAR administration, error handling through use of the PEAR_Error object, and system commands. These classes are generally shipped with every source PHP distribution. * Packages There are many PEAR packages with the number growing every day. Most every package is documented and most are not installed by default. For information on installing PEAR classes on your system, be sure to read the Installation chapter. Each documented class contains basic documentation about the packages publically available functions. There may also be additional information like an introduction, list of available constants, and example uses of the given package. Additional information may also exist within the package source files themselves. The description of each function may contain some or all of the following parts: + Synopsis Shows the structure and prototype of the function. + Description Gives a description about what the function does. + Parameter Describes each parameter for the function along with the paramater types and names. Both required and optional parameters are listed. + Returns Describes the returned value, if the function doesn't fail. + Throws Describes the returned PEAR_Error objects, if the function fails. + Note Additional notes and information about the function. An example note would be if the function can be called statically. + See Links to other related functions or manual entries. + Example An example use of the function or class. * PECL Packages PECL Packages are regular PHP extensions written in C. The documentation structure should follow the Package section above. * Contributing to PEAR Contains information for writing your own PEAR Packages. _________________________________________________________________ Authors and Contributors The following is a list of people that are helping to maintain this documentation. If you would like to contact one of them, please write to pear-doc@lists.php.net. * Daniel Convissor * David Costa * Thomas V.V. Cox * Martin Jansen * Alan Knowles * Clay Loveless * Alexander Merz * Stefan Neufeind * Jon Parise * Tobias Schlitt * Stephan Schmidt * Mika Tuupola * Michael Wallner (In alphabetic order.) I. About PEAR Table of Contents 1. Introduction 2. Installation 3. Support 4. Coding Standards 5. Contributing 6. FAQ - Frequently Asked Questions _________________________________________________________________ Chapter 1. Introduction The PEAR Manifest PEAR is dedicated to Malin Bakken, born 1999-11-21. _________________________________________________________________ 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-sourced code for PHP users * A system for code distribution and package maintenance * A standard style for code written in PHP, specified here * The PHP Foundation Classes (PFC), see more below * 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 with the PEAR Group as the governing body. The project has been founded by Stig S. Bakken in 1999 and quite a lot of people have joined the project since then. _________________________________________________________________ Structured Library of PHP Code The code in PEAR is partitioned in "packages". Each package is a separate project with its own development team, version number, release cycle, documentation and a defined relation to other packages (including dependencies). Packages are distributed as gzipped tar files with a description file inside, and installed on your local system using the PEAR installer. There are two types of packages: source packages (containing source files only), and binary packages (containing platform-specific binary files, and possible source files). Installing source packages with C code obviously requires a C build environment. PEAR defines a package tree, where each "node" in the tree is represented by a part of the package name. The nodes are organized by simple descriptive topics, and each part is separated by an underscore. Examples of package names are "MP3_Id", "Archive_Tar" and "HTTP_Post". Packages may relate to eachother through explicit dependencies, but there is no automatic relation between for example a package and its "parent" in the package tree (for example, "HTTP_Post" is by default independent of "HTTP"). A few top-level nodes in the package tree called "sub-repositories" have special functions, currently these are PECL, Gtk and App. For each of these, different rules apply, see more in the description of each sub-repository below. A style guide, the PEAR Coding Standards (short PCS), exists to ease collaboration between PEAR developers, to help quality and portability, and to help PEAR contributors to provide consistent-looking-and-feeling APIs. For packages in the PFC, this standard applies strictly, for non-PFC packages it applies more relaxed. _________________________________________________________________ Code Distribution and Package Maintenance All PEAR packages are registered in and uploaded to a central database available at pear.php.net. Open-sourced third-party packages may also be registered and uploaded. Closed-source packages may be installed by the PEAR installer, but the PEAR database is for open-source code only. Pear.php.net will provide both a human-friendly (HTML) and machine-friendly (currently XML-RPC) interface to the PEAR database. Package downloads are done with plain HTTP. Other functions the pear.php.net site will provide are: * user account management (integrated with the CVS server) * package management * release management Packages are distributed as a gzipped tar file with an XML description file inside. The description file contains some information about the package, a list of files and their roles, and dependencies. _________________________________________________________________ The PHP Foundation Classes The PHP Foundation Classes is a subset of PEAR that focuses on quality, generality, interoperability and compatibility. If PHP is going to continue bundling PEAR packages beyond the installer, it will bundle the PFC. Focus on quality means that no packages or releases with less than "stable" quality are accepted in the PFC. Generality means that packages should not be more than reasonably specific to any type of environment (such as an output format like HTML, an operating system, a web server or SAPI backend etc). Interoperable packages work well with other packages, have stable, standardized APIs, prefer other well-established (and also interoperable) components and also work well in different environments (PHP version, SAPI backend, operating system etc.) Compatibility is not just about supporting the same syntax and semantics as earlier versions, it is also about planning ahead when writing the code. Designing code so it would be easy, or at least possible, to add features that are likely to appear later, gives code that is also "forward-compatible". _________________________________________________________________ The PHP Extension Community Library (PECL)PECL PECL (pronounced "pickle") used to be a sub-repository of PEAR for C extensions ala those distributed with PHP 4, in fact, having somewhere to move extensions to from PHP was one of the motivations when creating PECL. Extensions in PECL follow PHP's coding standards rather than PEAR's, but they are distributed and installed as PEAR packages. The process of moving an extension from PHP to PECL is referred to as "pickling". In October 2003 PECL has become an independent project, which does not belong to PEAR anymore. (Except for the infrastructure, which PECL borrows from PEAR.) More information and all PECL packages can now be found on the PECL homepage. During the PECL spin-off, the project has also been renamed from "PHP Extension Code Library" to "PHP Extension Community Library". _________________________________________________________________ Gtk PackagesGtk Gtk packages are packages that provide software which uses the technology of the PHP-GTK project. Code in this sub-repository follows PEAR's coding standards. Right now there is no definitive plan on how they will be released in PEAR. _________________________________________________________________ Application PackagesApp TBD _________________________________________________________________ Chapter 2. Installation This chapter describes, how to install packages from PEAR. _________________________________________________________________ Introduction This chapter requires that you are already familiar with the general structure of PEAR. The base installation that comes with the PHP distribution as part of the PFC, 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 are not part of the PFC can be installed with the PEAR package manager. The manager is comparable to Debian's "apt-get". 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 Unix/Linux/BSD When using PHP >= 4.3.0, the PEAR Package Manager is already installed unless one has used the ./configure option --without-pear. For all versions prior to 4.3.0 or if you want to re-install the Package Manager, you can use the following provisional way: $ lynx -source http://go-pear.org/ | php Note: Some Linux distributions (e.g. Redhat) seem to be using links instead of lynx as the name for their command line browser. If this is the case for you, you need to change the above line correspondingly. _________________________________________________________________ Windows After you have downloaded and installed PHP, you have to manually execute the batch file located in e.g. c:\php\go-pear.bat. The setup will ask you some questions and afterwards the PEAR Package Manager will be installed in the path, which you have specific during installation. Finally you have to add that installation path to your PATH environment (Start > Control Panel > System > Environment). After that you can access the PEAR Package Manager by running the command pear in a Windows Command Prompt. To update your PEAR installation from go-pear.org, request http://go-pear.org/ in your browser and save the output to a local file go-pear.php. You can then run php go-pear.php in a Windows Command Prompt to start the update process. _________________________________________________________________ PEAR in hosting environments If you are running your site at a web hosting provider with no direct access to the server (via local logins, Telnet or SSH), you can't use the PEAR Package Manager. If you are customer of a smart web hosting company, the chances are very well that the most commonly used PEAR packages are already installed on the machine that is hosting your site. If that is not the case or if you need additional packages, you should contact your provider and ask them nicely to install the package. If they refuse to do so, you can either look for a new web hosting company or you can install the package manually. _________________________________________________________________ Command line installer Prerequisites The following description requires the latest version of the PEAR package manager to be installed. 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. _________________________________________________________________ Fully-automatic installation Using the command line installer is pretty straightforward and easy to use. Simply run the following line on your shell: $ pear install has to be replaced with the name of the package you want to install (e.g. HTTP_Upload). To get a list of the available packages, you can point your browser to the PEAR package browser or you can run: $ pear remote-list This command returns a list of all packages that are available in PEAR at the moment. _________________________________________________________________ Semi-automatic installation If you have downloaded a package release from pear.php.net as a gzipped tar archive, you can also install it locally. To do this, run the following line on your shell: $ pear install .tgz This command will automatically install the package and does not require an online connection. .tgz has to be replaced with the name of the downloaded file. _________________________________________________________________ Commands and Variables Here's a list of commands available to the pear command line tool. Many of these commands may require root access to the server. Command Description build Build the extension from source bundle Download and unpack a PECL extension clear-cache Clear the XML-RPC cache config-get Echo a specific configuration setting config-help Show information about a setting config-set Set a specific configuration setting value config-show Show all configuration setting values cvsdiff Execute and display a "cvs diff -u" on all files within the package cvstag Set a CVS release tag download Download a package but not install it download-all Downloads every available package info Display information about a package install Install a package, will report with success or failure list List installed packages list-all List all packages, packaged and/or available list-upgrades List available upgrades for the installed packages login Connects and authenticates to the remote PEAR server logout Logs out from the remote PEAR server makerpm Builds a RPM spec file from a PEAR package package Build a package package-dependencies Show package dependencies package-validate Validate package consistency remote-info Information about remote packages remote-list List remote packages run-tests Run regression tests search Search the remote package database shell-test Do a shell script test sign Sign a package distribution file uninstall Uninstall and remove a packge upgrade Upgrade a packge to the current version (see also: preferred_state) upgrade-all Upgrade all packages (see also: list-upgrades) And here's a list of available PEAR configuration variables. Use the config-get, config-help, config-set, and config-show command options to use these configuration variables. While installing PEAR on the system, PEAR will attempt to replace the default values with values specific to the given server. Adjust accordingly. Variable Name Description Default Value bin_dir Directory where executables are installed /usr/bin doc_dir Directory where documentation is installed /usr/lib/php/docs ext_dir Directory where loadable extensions are installed ./ php_dir Directory where PHP files are installed (like PEAR files) /usr/lib/php cache_dir PEAR installer cache directory, and used by XMLRPC /tmp/pear/cache data_dir Directory where data files are installed /usr/lib/php/data php_bin The PHP CLI or CGI binary for executing scripts /usr/bin/php test_dir Directory where regression tests are installed /usr/lib/php/tests cache_ttk Number of seconds that the local cache is used, and not updated (Time To Kill) 3600 preferred_state Preferred package state: stable, beta, alpha, devel, or snapshot stable umask umask used when creating files (Unix-like systems only) 22 verbose Debug log level: 0-3 where 3 is full debug mode. 1 http_proxy The optional HTTP proxy address (host:port) used when downloading packages master_server PEAR server pear.php.net password PEAR password (used by maintainers) sig_bin Signature handling program /sw/bin/gpg sig_keydir Signature key directory /etc/pearkeys sig_keyid The key used for signing sig_type Package signature type (only gpg) gpg username PEAR username (used by maintainers) _________________________________________________________________ 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. _________________________________________________________________ Installing a local copy of PEAR through SSH To install PEAR through SSH, you can use this command sequence to set up a local copy of PEAR: $ pear -s -c ~/.pearrc -d doc_dir=~/pear/docs -d ext_dir=~/pear/ext \ -d php_dir=~/pear/lib -d data_dir=~/pear/data -d test_dir=~/pear/tests \ -d cache_dir=~/pear/cache -d bin_dir=~/pear/bin This will create a local configuration file in a file in your home directory named .pearrc. In addition, it will create a directory structure based on a subdirectory of your home directory named pear that contains all of the packages that you install. Then, if you add ~/pear/bin to your path as the first entry in .bashrc (or whatever your startup file is), and run the command: $ pear -c ~/.pearrc install Archive_Tar PEAR Console_Getopt XML_RPC You will have a local version of PEAR that supersedes the system's copy. To use the files you have installed, you should set your PHP include_path in either the code that uses your PEAR packages like so: Or, in an .htaccess file for apache using php_value. _________________________________________________________________ Installing a local copy of PEAR through ftp In order to install a local copy of PEAR through ftp, you must have an ftp client that can set permissions on upload. First, create a directory that is NOT in your publicly accessible web space, and name it anything you'd like. Set it to be readable and writable by any user (permissions 0777). Then, download a copy of http://go-pear.org and save it as go-pear.php. Upload go-pear.php to a subdirectory of your publicly accessible web space. It is a very good idea to password-protect the directory containing go-pear.php with an .htaccess file. Next, browse to the go-pear.php file. If your web address is http://www.example.com, you have placed go-pear.php in public_html/install/go-pear.php, and http://www.example.com will browse to public_html/, then browse to http://www.example.com/install/go-pear.php. Follow the installation prompts. When asked where to install PEAR, choose the directory you created to be readable and writable by any user. You will need to know the location of the cli version of PHP. To find this, browse to this script and copy the output: After PEAR has been installed, you can use the web installer to install and upgrade packages just as you would with any other PEAR installation. To use the files, you must set the include path in scripts on the website. _________________________________________________________________ Manual installation Installing packages manually is no recommended way, but a lot of people run into problems using the automated ways, when their sites are located in web hosting environments with no shell access. In the following paragraphs, we will demonstrate how to install packages manually on a site with the following path scheme: The document root of the site is /var/www/www.example.com/htdocs/. On the same level than htdocs there is another directory called includes. This directory can not be accessed via HTTP but via FTP or WebDAV. The installation consists of some easy to follow steps: 1. Download the package: You can download the package from the PEAR homepage with your web browser. If you do not know the URL of the package information page for the package, you can use the package browser to view the currently available packages. 2. Upload the package source code After having downloaded the .tgz file of the package, you have to extract the contents of the archive file to a temporary directory on your local machine. After that you must upload the source code via FTP, WebDAV or another method to the directory /var/www/www.example.com/includes/, so that the source code for Mail_Mime now e.g. resides in /var/www/www.example.com/includes/Mail/. 3. Adjust your include_path directive. Now you have to adjust PHP's include_path directive so that it contains the location where you just uploaded the source code. If you have access to the php.ini configuration file for your site, you have to add /var/www/www.example.com/includes/ to the directive there. If you do not have access to the configuration, you have to set the include_path in each script where you want to use the package: ini_set("include_path", '/var/www/www.example.com/includes/' . PATH_SEPARATOR . ini_get("include_path")); 4. After having finished the installation, you can now make use of the package: require_once "Mail/Mime.php"; $mime = ... If you have more questions concerning manual installation, you can ask on the user mailing list. _________________________________________________________________ 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. You should use a package from CVS only, if: * The maintainer recommended it for you. * You want to help in development of a package. * You really need a special patch or function, which is not currently released. 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/, i.e. cvs -d :pserver:cvsread@cvs.php.net:/repository checkout pear/HTTP_Client. 2. Check the package.xml file, especially the fileset entries. They must match the existing files and directory structure. If they differ, contact the maintainer and ask for an update of package.xml. 3. Create a valid package using the PEAR Installer pear package 4. If you have already the package installed: remove it to avoid versions problems: pear uninstall 5. Install your package archive: pear install Now, you have an CVS version installed! You should upgrade to a official release of the package as early as possible. Before you install the official release, uninstall the CVS version to avoid version problems. _________________________________________________________________ Chapter 3. Support This chapter describes, how you can get support, if you have questions concerning PEAR. _________________________________________________________________ The mailing lists Overview As in most other open-source projects, the support is done via mailing lists. In our case, we currently have five PEAR related mailing lists: * General list * Developers list * Documentation list * Webmaster list * CVS commit list * Core list * Quality Assurance list The first four lists are intended to help you, if you have questions. Please read below to get to know, what list fits to your needs. The CVS commit list is intended for people that are contributing to PEAR: All commits to our revision control system (CVS) are send to this list. The core and QA lists are intended for people that want to take part in the development of PEAR. You can subscribe to the PEAR mailing lists via this website. _________________________________________________________________ The General mailing list The PEAR general mailing list is the mailing list, where you ask, if you have a question about installing PEAR, using a certain PEAR package etc. The list is no support forum for question concerning the usage of PHP. Please use php-general@lists.php.net instead. _________________________________________________________________ The Developers mailing list As the name already tells you, this list is the place where the developers of PEAR come together to make decisions, to discuss about code and to handle things that are related to this. If you are no developer of PEAR itself, this list is of no real interest for you, unless * you want to get to know what's going on behind PEAR * you want to contribute code to PEAR * you have found a bug in a PEAR package and want to supply a patch for that. The adress for this list is pear-dev@lists.php.net. _________________________________________________________________ The documentation mailing list This list is the place, where all the things concerning the PEAR documentation, the manual etc. are discussed. If you want to help out documenting PEAR packages, don't hesitate to drop a mail there. _________________________________________________________________ The QA mailing list People being interested in improving the overall quality of PEAR come together on the QA list. The Quality Insurance team is always seeking people that want to help. If you are interested, just sign up and announce yourself on the mailing list. _________________________________________________________________ The Webmaster mailing list If you have found a problem on our website or have a question concerning the site, you can email the guys on pear-webmaster@lists.php.net . _________________________________________________________________ The core mailing list This list is the place, where the core infrastructure of PEAR is discussed. Members of this list also come from other PHP projects such as PECL and PHP QA, since the PEAR infrastructure is also relevant to these projects (like the PEAR installer, the PEAR website etc.). Specifically the list is concerned with the following topics: * New main features for the PEAR website * PEAR installer development * PEAR standards definition _________________________________________________________________ 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. _________________________________________________________________ Chapter 4. Coding Standards Note: The PEAR Coding Standards apply to code that is part of the official PEAR distribution (that is, either distributed with PHP or available for download from the PHP PEAR repository). _________________________________________________________________ Indenting and Line Length 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): (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 that you break lines at approximately 75-85 characters. There is no standard rule for the best way to break a line, use your judgment and, when in doubt, ask on the PEAR Quality Assurance mailing list. _________________________________________________________________ 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); _________________________________________________________________ Function Definitions Function declarations follow the "one true brace" convention: 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 Inline documentation for classes should follow the PHPDoc convention, similar to Javadoc. More information about PHPDoc can be found here: http://www.phpdoc.org/ 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(). Note: include_once() and require_once() are statements, not functions. You don't need parentheses around the filename to be included. _________________________________________________________________ PHP Code Tags Always use 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 core PEAR distribution should contain the following comment block as the header: /* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */ // +----------------------------------------------------------------------+ // | PHP version 4 | // +----------------------------------------------------------------------+ // | Copyright (c) 1997-2004 The PHP Group | // +----------------------------------------------------------------------+ // | This source file is subject to version 3.0 of the PHP license, | // | that is bundled with this package in the file LICENSE, and is | // | available through the world-wide-web at the following url: | // | 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 world-wide-web, please send a note to | // | license@php.net so we can mail you a copy immediately. | // +----------------------------------------------------------------------+ // | Authors: Original Author | // | Your Name | // +----------------------------------------------------------------------+ // // $Id:$ There's no hard rule to determine when a new code contributor 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. Simple code reorganization or bug fixes would not justify the addition of a new individual to the list of authors. 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. _________________________________________________________________ Using CVS This section applies only to packages using CVS at cvs.php.net. Include the $Id$ CVS keyword in each file. As each file is edited, add this tag if it's not yet present (or replace existing forms such as "Last Modified:", etc.). 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: RELEASE_n_n_n (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. QA_n_n_n (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. MAINT_n_n_n (branch, optional) If you need to make "micro-releases" (for example 1.2.1 and so on after 1.2.0), 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. Only the RELEASE tag is required, the rest are recommended for your convenience. Below is an example of how to tag the 1.2.0 release of the Money_Fast package: $ cd pear/Money_Fast $ cvs tag RELEASE_1_2_0 T Fast.php T README T package.xml By doing this you make it possible for the PEAR web site to take you through the rest of your release process. Here's an example of how to create a QA branch: $ 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 The QA_2_0_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. _________________________________________________________________ Example URLs Use example.com, example.org and example.net for all example URLs and email addresses, per RFC 2606. _________________________________________________________________ Naming Conventions Classes Classes should be given descriptive names. Avoid using abbreviations where possible. Class names should always begin with an uppercase letter. The PEAR class hierarchy is also reflected in the class name, each level of the hierarchy separated with a single underscore. Examples of good class names are: Log Net_Finger HTML_Upload_Error _________________________________________________________________ Functions and Methods 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: connect() getData() buildSomeWidget() XML_RPC_serializeData() 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 preceded by a single underscore. For example: _sort() _initTree() $this->_status _________________________________________________________________ Constants Constants should always be all-uppercase, with underscores to separate words. Prefix constant names with the uppercased name of the class/package they are used in. For example, the constants used by the DB:: package all begin with DB_. _________________________________________________________________ Global Variables 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. _________________________________________________________________ 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. _________________________________________________________________ Sample File The Id CVS keyword you see in the example below contains the data for the file used to create the document you are reading now. When creating your own PEAR scripts, replace the data there with a blank keyword: $Id:$ 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. 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. | // | Your Name | // +----------------------------------------------------------------------+ // // $Id: standards.xml,v 1.26 2004/06/12 15:50:06 danielc Exp $ require_once 'PEAR.php'; // {{{ constants /** * This is a "Docblock Comment," also known as a "docblock." The class' * docblock, below, contains a complete description of how to write these. */ define('NET_SAMPLE_OK', 1); // }}} // {{{ 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_ph pDocumentor.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 @access * 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 * @version $Id: standards.xml,v 1.26 2004/06/12 15:50:06 danielc Exp $ * @access public * @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, begining 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. * * @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: */ ?> _________________________________________________________________ Chapter 5. Contributing This chapter describes the different ways in which one could contribute to PEAR. _________________________________________________________________ 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. Next step is to submit the patch. Send a mail to pear-dev@lists.php.net and Cc 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 adresses are available on the package information page on http://pear.php.net/. Note: If you are using Outlook or Outlook Express, please change the file extension of the diff file to .txt, because Outlook's MIME-Type detection depends on the file extension and attachments with a MIME-Type not equal to text/plain will be rejected by our mailinglist software. Note: If your patch does break backwards compatibility, the chances are fairly good that the maintainers won't be happy about it. Thus you should always try to fix a bug in a way that does not seriously change the public API. But if there is absolutely no way to keep backwards compatibility and/or if your patch contains a groundbraking improvement, even API changes are fine. _________________________________________________________________ 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 to link "Package 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 a 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 ;-). _________________________________________________________________ Chapter 6. FAQ - Frequently Asked Questions _________________________________________________________________ What is PEAR? This is described here. _________________________________________________________________ How to become a PEAR contributor and/or how to get CVS access to PEAR? This is described here. _________________________________________________________________ I have written a PHP module in C. What are the rules of including this in PEAR? Answer written by Stig Bakken and Martin Jansen. If you just want to make a simple extension that does not follow the PEAR coding standards, put it in pear/PECL/ extname (that is where extensions from php-src/ext/extname will be moved). If you want to write an extension following PEAR's function/class naming, put it in pear/Foo_Bar or whatever the right name is. _________________________________________________________________ Why is PEAR seperated into pear/ and php-src/pear/? The first elements of PEAR were stored in the directory php-src/pear and so they were bundled with each new PHP release. For future releases of PEAR this isn't workable because PEAR will become too big to be bundled with every release of PHP. So there was a decision to commit all new elements to an own top level directory pear. The other elements which are currently remaining in php-src/pear will be moved to the new top level directory soon. Only the PFC code and the PEAR package manager code will be bundled with every new release automatically. _________________________________________________________________ Why does the directory structure of pear/ and php-src/pear/ differ? Answer written by Stig Bakken. The directory structure of php-src/pear/ matches that of the install tree (by default /usr/local/lib/php), and are organized as a simple hierarchy. However, the directory structure of pear/ is based on what package the files belong to. Where files are located in each package directory is completely independent from where they end up being installed, this is all determined by the package description file. _________________________________________________________________ Why a flat directory structure instead of a deep? Answer written by Stig Bakken. In CVS, PEAR code is organized by package instead of hierarchical like it would finally be installed. For example, if you want to use the XML_RPC class, you include "XML/RPC.php". It's easy to think that in CVS, this file should be in pear/XML/RPC.php, but that's not the case. XML_RPC is an independent package with its own directory in CVS, in this case the RPC.php file is actually located at pear/XML_RPC/RPC.php. The package description file (package.xml) is used to say where the files should finally be installed. The reason CVS is organized this way is that it makes package administration much easier. _________________________________________________________________ Can I commit experimental/unstable stuff? Yes. But make sure, that you mark up the experimental/unstable status of the project in the documentation. The best place to do this is in the package.xml in the -tag. The values for this tag are alpha early stages of development, all things could change (API, behavoir) without notice, expect lots of bugs beta API should normally not change, usable software, expect bugs devel a release for other developers who want early access to test and give feedback, code quality may vary from pre-alpha to stable stable the software was tested, the API fixed, the documentation wrote and is the recommended release for users and production enviroments snapshot a CVS snapshot from a certain date _________________________________________________________________ Am I expected to add examples and/or test files to my package and where to store them? Examples are a good idea, especially when your class has a complex API. But examples are only a part of a documentation. Don't create examples instead of a documentation. You should store the documentation and the examples in a sub directory 'docs' of the package directory. Test scripts are recommended when your class has to be compiled, requires special extentions/programs or needs correctly installed additional files (i.e. templates, graphics). Store them in sub directory called 'tests'. _________________________________________________________________ Are different packages or classes with similar features allowed? There is no problem with competitive packages, but we want to avoid pollution with 10 template classes, 7 different mail classes, and 3 different layers for databases doing the same only with different function names. First of all, do a reality check: Why do I want to commit a new package? Really bad answers are "To see my name in PEAR" or "I didn't understand the API of the existing class". A good reason for a new class is often, that you are missing a function, behaviour or speed in an existing implementation. In this case, you should take a look at this class, if it possible to extend this class. If not, then you have a good reason to commit a new class. "If not" means, it isn't possible to add the required functionality without changing the basics of this class. If you write a new class, try to keep API compatibility with existing classes as far as possible! If it isn't possible to keep the class compatible himself, try to create a wrapper class to keep compatibility. Don't care, if this wrapper needs a lot of time or memory, a wrapper class only has to keep compatibility and make migration easier. Committing a competitive class has to be announced on the PEAR developers mailinglist! _________________________________________________________________ I have a question about PEAR. Where should I ask? * General questions about the usage of PEAR components should be posted to the mailing list pear-general@lists.php.net. * All technical discussions concerning the development of PEAR components should be posted to pear-dev@lists.php.net. * Question concerning the website can be sent to pear-webmaster@lists.php.net. Information on subscribing this mailing lists can be found here. On all mailing lists mentioned above the language is english and the way you ask questions should always be polite :-). _________________________________________________________________ A required package includes a package, my package needs it too. Should I include it again? Yes. You should include every package, you need with require_once() or include_once (), also when it is included already by another package. _________________________________________________________________ Does PEAR work on windows? To make PEAR work on Windows, you simple need to add the PEAR installation dir (e.g. c:\php\pear) to the include_path directive in your php.ini. Note: There are some classes (like Schedule/At.php), that do not work on Windows, because they use *nix specific commands. _________________________________________________________________ What licenses are allowed in PEAR/PECL? Answer written by Jan Lehnardt, Tomas V.V. Cox and Rasmus Lerdorf. Currently PEAR supports the following list of licenses: * PHP License * Apache License * LGPL * BSD style Other licenses may be added to this list on a case-by-case basis. Please get in touch with the PEAR developers mailing list for this. For PECL extensions that are linked into PHP, the license must be compatible with the PHP license. That means you can not GPL a PECL extension or you would be violating the GPL. Note also that if you write an extension that links against a GPL'ed library you will be violating the GPL. If you need to link against a GPL'ed library, get permission from the author of the library. To set the license of you PEAR/PECL package, put it in the head of all source code files of your package and also the type of it inside the tag of your package description file (package.xml). _________________________________________________________________ Why does the PEAR coding standard insist on space-only indentation? Answer written by Stig Bakken. Using spaces and avoiding tabs is the only way to ensure that a piece of code is rendered consistently in all editors and viewers. Many editors render tabs as 4 spaces, and a lot of editors, terminal programs and utilities render tabs as 8 spaces. Example: printf("%s", $arg); Here, there are 7 spaces before "$arg". If this code was written in an editor with 4-space tabs, it would store it as one tab and three spaces. Now, if another developer edits the same file in an editor with 8-space tabs, it will look like this: printf("%s", $arg); Likewise, consider this code written with 8-space tabs: if ($foo && $bar) { } If viewed in a 4-space-tab editor, it will look like this: if ($foo && $bar) { } In a community like PEAR where people use lots of different systems and editors, using tabs simply doesn't work. People will end up doing whitespace commits fixing rendering in their editor, while breaking it for others. With only spaces it will look the same to everyone. Jamie Zawinski has written a piece on the subject too. There is also a tool called Astyle which can help you convert your code to the appropriate style. _________________________________________________________________ Is there a tool to help PEAR manual translators to track files changes? Working on the translations is not just translating an English file and commiting the results. Much of the work is needed to update the already translated ones, to get in sync with the content of the English files. To follow the modifications in the English tree, you should subscribe to the PEAR documentation mailing list to get CVS commit messages, or read the archives. If you never update your files, the translations can get useless. Updating a foreign language file can get difficult, as you may not know when and who translated that file, so you may not know where you should look for the updates needed. We have one system for tracking the revisions and modification dates of the files in peardoc. _________________________________________________________________ The Revision Comments Instead of storing all responsibilities in a central file, the revision comment system stores them in the files they provide information about. Information about translator, revision numbers, and status information is stored in the revision comment. Let's see what would be in the header of the example file bookinfo.xml file in this case: We can see the revision number for the last english file used to update the translation (EN-Revision: 1.16), the translator cvs account name. But we can also add some other status information in the case it is needed (eg. "partial" for incomplete translations). This revision comment system is basically about storing the information in the XML files, and not in a central place. This is extremely convenient now, as there are more than 1300 files in the English tree. Currently, all three fields (English revision, Maintainer, Status) are needed. Maintainer is intended to be a CVS user name, or some nickname without a space, status can be anything without a space. Note, that this header is not updated by CVS (in contrast with $Revision, which is updated automatically). This is only updated when you edit the contents of the comment yourself. You may see this as a good thing, but using these comments, you lose the quick look on the whole list of your files. No, you do not lose this, but get much more! If you would like to build a full list of you files, you can go to the /peardoc/ directory and run: ./scripts/revcheck_pear.php xx > revcheck.html Here xx is the imaginary language code. After running this script you'll get a revcheck.html in the same directory. You can find revision comparisions and links to diffs for all the files in this language. You can also add a further restriction parameter, the maintainer name, so the script will only list the files corresponding to the given maintainer. There are some optional extensions introduced for this script, to be available in this generated HTML page. This is why the translation.xml files are introduced. Here comes a simple translation.xml file for the imaginary xx language : This is some introductory text for the xx language translators about who is the manager of the translation, and where to find more information. This paragraph is printed on the top of the generated revcheck.html page. In this file, you can add users without a CVS account, and can assign ready documents or work-in-progress files to them. The biggest advantage of using this addon is that all this information is used to generate dynamic tables of translators and files in the revcheck.html file. All translators are linked to from the individual files they are assigned to, and there is a nice table showing the state of files for all the translators. Assigning ready files may be needed if a time consuming update is in progress on that file. There are two optional parameters you can add to a , if you would like to record it: the date and revision. Date is assumed to be the date when the work was started, revision is the checked out revision of the English file used to start the work (denoted as CO-Revision in the generated table). There is currently no fixed format for the date parameter. Another addon to this system is just to give credit to all people who worked on one file, and not just the current maintainer. To achieve this goal, we added the credit comments. One credit comment in eg. history.xml may look like this (in case Joe Doe translated the file initially, but Jane followed him to be the maintainer): The credits comment can contain a comma-separated list. These comments only affect the display of the translators table in revcheck.html. II. New Maintainers' Guide Table of Contents 7. Introduction 8. When to contribute (and when not to contribute) 9. Getting started with the community 10. The formal proposal process _________________________________________________________________ Chapter 7. Introduction If you are planning to contribute a new package to the PEAR project, this guide will provide you with the necessary information to get you started The Right Way (tm). We will start by describing the cases in which it makes sense to contribute and in which not. After we have ensured that the package you want to contribute fits into PEAR, we will describe how to get started with the community. Once you are confident about the inner workings of the PEAR developer community, we will explain how to start the formal process of proposing a new package and we will give some tips for making your first package as successful as possible. _________________________________________________________________ Chapter 8. When to contribute (and when not to contribute) In this chapter we describe the cases in which it makes sense to contribute code to PEAR and in which it does not. This description is by no means complete. If you are unsure, if your contribution could be included into PEAR, contact the developers mailing list. _________________________________________________________________ Cases in which it makes sense to contribute 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. (XXX: Add link here.) 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 does not make sense to contribute A rough rule of thumb is that code which solves a problem that exists in one or only very few projects is not convenient for inclusion into PEAR because most people will not benefit from it. However, this does not mean that "niche software" cannot be included in PEAR. In the Math section we have a number of elaborate packages that solve different kinds of algebraic problems. While those problems do not occur in average applications, the packages are very abstract and scientific projects benefit a lot. Apart from code that does not fit into PEAR because of a lack of abstractness, there is another type of code that currently cannot be contributed to PEAR: Full web applications. Despite the fact that the "A" in PEAR stands for "Application" there is a simple reason why applications are not yet supported: Until now nobody has gotten around to make the infrastructure like the PEAR installer capable of handling packages that provide complete web applications. When the situation changes, this site will be updated. _________________________________________________________________ Chapter 9. Getting started with the community Upon determining your code fits into PEAR, you should get started with the PEAR community. In this chapter we will provide several ways, in which you can establish a first contact with the other PEAR developers, which will hopefully be your future open source fellows. Additionally we will tell you the different places, where you can find more information about the inner workings and rules of PEAR. _________________________________________________________________ Communication with other PEAR developers Mailing lists naturally are the most important way to communicate in projects like 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 of major importance for you: This mailing list is the place where the maintainers get together to discuss various aspects of their packages and this list is also the place where new packages are discussed. If you would like to get started with maintaining packages in PEAR, you are expected to be subscribed to this mailing list. (Subscription instructions) Note: During your first steps in the PEAR community, you may stumble across the term "pear-dev", which is the abbreviation for the developers mailing list in PEAR's lingo. Some people enjoy communicating via IRC channels. We are running the channel #pear in the server network of EFnet. At this channel some of the most active PEAR developers hang out regularly. However for serious inquiries or discussions, you should mail to the developers mailing list. _________________________________________________________________ More written information * The PEAR Group occasionally publishes so called Administrative Documents, which describe the Group's decisions. You are expected to 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, so you do not need to visit the site frequently. * This manual contains the Developer Guide, which provides valueable information as well. * The Coding Standards describe the standards which PEAR code must adhere to. _________________________________________________________________ Chapter 10. The formal proposal process In the early times of PEAR, all new packages were proposed by an informal email to the PEAR developers mailing list. Over the time, the number of new proposals increased quite dramatically, making it hard to keep track of all the proposals. A web-ased proposal handling system was established to solve these problems. The system is called PEPr. It is pronounced like the spice and stands for "PEAR Proposal system". This chapter describes the requirements and the workflow for a PEPr-based proposal. After that we will provide you with information, on how to actually start a proposal. Finally, you will learn what to do once the proposal is finished. After reading this chapter, you will will be able to start a proposal for your code right away. _________________________________________________________________ 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 10-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 Before starting the proposal process in PEPr, a thread should be started for each new package on the developers mailing list. This intermediate step is preferred for the sake of convenience, because it is easier and more comfortable for us to hit a single key in our mail client to join a discussion than to open a browser window and look up the right page on the website. 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. Also please note that PEAR is an international project, with people coming from different cultural backgrounds. Because of that most people in the community are not native english speakers. Do not worry if your English is not perfect and, most importantly, be aware that sometimes misunderstandings may happen. It is important that everybody involved tries to be as clear as possible. Once you feel that you have addressed all questions/suggestions/critics raised during the mailing list discussion, you can go ahead with starting the formal PEPr process. _________________________________________________________________ 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. _________________________________________________________________ Stage 1: Creating a draft At first your proposal is a draft. This simply means you can edit it, view it and it is shown up on the PEPr overview page as a draft. This stage is for you to play around with PEPr, to shape your proposal nicely and to prepare it for the proposal process. You can switch to the next stage when ever you want to publish your proposal and get feedback from the PEAR community. _________________________________________________________________ Stage 2: Moving to the Proposal stage After switching to the stage Proposal you have a real proposal. Either through email or through PEPr itself the community will give you hints and ask questions about the proposed package. Generally it is a good idea to follow these suggestions, but sometimes people in the community will have different visions for your package, which should be sorted out during this stage. After a week of comments you may switch to the next phase. You should only switch to the next stage, if you are sure that the PEAR community will accept your package. _________________________________________________________________ Stage 3: Calling for votes The next stage is the voting stage, during which you may not change your proposal anymore. You may not edit nor delete the proposal from now on. During the proposal stage, "Call for Votes," every active PEAR maintainer may give one vote on the proposal. Votes are given using the numbers -1, 0 and +1, where -1 means "I'm against this package to be added to PEAR in the current form," +1 says "I'm in favour of getting this package into PEAR in the current form" and 0 means "I have looked at your package, but I am undecided." The time to vote for a package is 7 calendar days. If after this time less than 5 votes have been cast, the developers get another 7 days to cast their votes. After this time the voting is ended, whether there are 5 votes or not. Votes on proposals can be bound to a condition. These conditional votes indicate that you have to fulfil a certain condition the voters expect to be fulfilled. If there are conditional votes you are expected to read and follow them! The conditions on a vote will be provided in the votes comment. Each vote may have comments. Reading those is always a good idea! _________________________________________________________________ Stage 4: Proposal Finished Now your proposal is finished. To determine if the proposal was successful or not, the sum of all votes is computed. If the result is greater or equal to 5 the proposal has been accepted. Otherwise we are sorry to say, that the community has decided to reject it. Have a look at their comments during proposal and vote stage to find out why. Maybe you can rework your package and propose it again, but please do not try to hand in a proposal the same way twice. If your proposal has been accepted, you may put your package into PEAR. If this is your first proposal, please contact the PEAR Group via email to get your current PEAR website account upgraded to a full featured developer account. After that, you can register your package and upload releases. The process of preparing and uploading a release is described in the Developer Guide. _________________________________________________________________ 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. III. Developer Guide Table of Contents 11. Introduction 12. PEAR's meaning for developers 13. Contributing your own code 14. The package definition file package.xml 15. Releasing A Package 16. Supporting PEAR development 17. Recommendations 18. Writing documentation _________________________________________________________________ Chapter 11. Introduction A guide to PEAR written for developers by developers. _________________________________________________________________ Purpose of this text The intention of this guide is to provide people, who want to contribute to PEAR, with all necessary information to start working effectively. The first part of this guide will cover the advantages a developer will have when using PEAR code in his every-day work. After that we will show you how to contribute your own code to PEAR. Finally the guide will point out, in which ways a developer can support the PEAR project. _________________________________________________________________ Chapter 12. PEAR's meaning for developers _________________________________________________________________ Code of high quality PEAR only accepts contributed code which is of high quality and which is compliant to the PEAR Coding Standards. For you this means that you are using code that has a more or less consistent API, is based on the same standard components and provides the same error reporting mechanism everywhere. Note that this does not apply for code that is contributed to PECL: In PECL all code has to follow the PHP coding standards. _________________________________________________________________ Chance to release your own code PEAR gives you the chance to contribute your code to an enourmous number of PHP developers: To get more information about how to contribute your code in PEAR, read here. _________________________________________________________________ Chapter 13. Contributing your own code PEAR is driven by an open source oriented developer community. Thus there is a chance for everybody to contribute code (in form of a new package or as an improvement for an existing package) to the project. However PEAR aims to keep the quality of the packages at a very high level. Because of that there are certain requirements for contributions, which are listed below. _________________________________________________________________ Requirements for contributing code We are making certain demands on both the code and the maintainers of packages: 1. Code must be conforming 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 the decision has been made that they are absolutely necessary. There is no sense in discussing about this. 2. 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. In this context it may be helpful to become familiar with the basics of object oriented programming. Eventhough PHP 4 does not come with full object oriented support yet, the knowledge will possibly help you in maintaining an extensible state for your package code. 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. 3. 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 4. 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 PFC DB package. For examples of PHPUnit tests, see the Auth package. 5. 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 the maintainership. _________________________________________________________________ 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 _. The value for 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 choiceof 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: a. 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. b. 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. 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. _________________________________________________________________ Chapter 14. The package definition file package.xml _________________________________________________________________ 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 _________________________________________________________________ Allowed elements The toplevel element in package.xml is the element . The allowed sub elements are: * : The name of the package. * : Short summary of the package's description. * : Full length description of the package. * : The license of the package (LGPL, PHP License etc.). * : Information about the maintainers of the package. + maintainer: Information about a single maintainer. (May be used multiple times.) o : The account name of the user. o : The role the user has during package development. (Can be either lead, developer, helper.) o : The realname of the user. o : The email address of the user. * : Information about the current release. + : The version number of the release. + : The state of the release. (Can be one of stable, dev, beta, alpha, devel, or snapshot.) + : The date when the release has been rolled. + : Releasenotes + o : Filename o : Name of a subdirectory. This subdirectory can again contain entries. + : List of dependencies of the package. o name : For more information about dependencies, please see below. * : Changelog-like information about the package. + o : Version of the specific release. o : State of the specific release. o : Date when the specific release has been rolled. o : Changelog information _________________________________________________________________ Creating a package definition file Example 14-1. Basic package.xml Money_Fast Make money fast. This package helps you to make money pretty fast. PHP License foo Joe Foo foo@example.com lead 1.0 2002-05-27 stable This is the first release. Fast.php This package.xml can serve as a template for you as it already contains all necessary elements. In most cases you only need to change the character data between the tags in order to use the example in your package. Example 14-2. Example for nested directories [...] 1.0 2002-07-23 stable This is the first release. Fast.php Calculator.php Currency.php Stocks.php README.txt tutorial.txt NASDAQ.php DAX.php In this example you get to know a very handy feature: When you have a directory in your package that only contains files of the same type, you can add to role attribute even to the tag instead of adding it to every single tag. With the knowledge you aquired during this chapter you should now be able to produce a package definition file for your own package. If you still have questions concerning the topic, don't hesitate to ask on the mailinglist. _________________________________________________________________ The file roles The role-attribute in the tag defines what type the file has and in which location it should be installed. Table 14-1. Possible values Value Destination dir php PHP source file the directory is determined by the package name ext Extension, dynamically loadable library the PHP extension directory or PHP_PEAR_EXTENSION_DIR if defined doc Documentation file {PEAR_documentation_dir}/Package_Name/ data Package related data files (graphics, data tables etc) {PEAR_data_dir}/Package_Name/ test Package related test files (unit-tests etc) {PEAR_test_dir}/Package_Name/ script Package related shell scripts the PHP binary directory or PHP_PEAR_BIN_DIR if defined src and extsrc C or C++ source code not copied directly - used to build a extension _________________________________________________________________ Defining Dependencies The PEAR Package Manager supports checking for different system capabilities. You define those dependencies with the tag: Example 14-3. package.xml with dependencies The following example shows how to specificy dependencies for PHP 4.3.0 or better and XML_Parser 1.0. [...] XML_Parser _________________________________________________________________ The type-attribute The following types are supported: Table 14-2. type values Value Meaning Example pkg Package depends on a certain Package "HTML_Flexy" ext Extension depends on a certain PHP extension "curl" php PHP depends on a certain PHP version "4.2" prog Program depends on a certain Program avaible in the system path "latex" os Operating System depends on a certain OS version "Linux" sapi Server API depends on a certain Server API "Apache" zend Zend depends on a certain version of the Zend API "2" Warning The DTD for the package definition file supports further types, but those are not supported yet. _________________________________________________________________ The rel-attribute The rel-attribute defines the relationship between the existing capability and the required. Table 14-3. rel values Value Meaning Can be used with has has the existing capability must have the requirement - version-attribute is not required pkg, ext, php, prog, os, sapi, zend eq equal the the existing capability must exactly match the version value pkg, ext, php, prog, os, sapi, zend lt less than the existing capability must be less than the version value pkg, ext, php, zend le less than or equal the existing capability must be less than or equal to the version value pkg, ext, php, zend gt greater than the existing capability must be greater than the version value pkg, ext, php, zend ge greater than or equal the existing capability must greater than or equal to the version value pkg, ext, php, zend Has will be used if no other value has been defined. _________________________________________________________________ The version-attribute The attribute version defines the version that is used to compare. _________________________________________________________________ The optional-attribute The attribute optional can be used when a dependency is not required but having the package installed can bring enhanced functionalities. The only legal values are "yes" and "no". If the optional attribute is not present, a dependency is required. When optional="yes" is used, this attribute will result in installation messages similar to the following messages: $ pear install Optional dependencies: Package `XML_Tree' is recommended to utilize some features. Package `MDB' is recommended to utilize some features. _________________________________________________________________ Chapter 15. Releasing A Package The steps required from package maintainers to release a package. _________________________________________________________________ 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 this two requirements can be found in the chapter Contributing your own code. _________________________________________________________________ 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. Note: For help with writing the package definition file see the package definition file description. _________________________________________________________________ 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. Note: Please note that the zlib extension needs to be enabled in your PHP build in order to create the release tarball. Next, you should install the package locally by running: pear install (file is the tarball you just created). This is done to ensure that the package definition file is not only valid but also contains valid information. You should manually check that every file is installed in the right place. If your package contains test scripts, which is highly recommended, you should run them. If anything fails at this stage, correct it and re-package and re-test. When everything seems OK, proceed. _________________________________________________________________ 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. _________________________________________________________________ Chapter 16. Supporting PEAR development How to support the PEAR community There are numerous ways to support the PEAR project, that are described in this part of the guide. _________________________________________________________________ Reporting and fixing bugs There is a chapter devoted to reporting and fixing bugs in the "Reporting Bugs" section of the manual, found here. _________________________________________________________________ Contributing new features to packages If you have a feature you would like to see included in a package, don't hesitate to contact the maintainer of the package. You can find out who the maintainer of a package is by browsing the package list on the PEAR website and selecting the desired package. The maintainer(s) is/are listed on the package information page. _________________________________________________________________ Becoming the new maintainer for an unmaintained package If a developer has given up the maintainership of his package, you can take over this job. If you feel brave enough to answer support questions, fix bugs and manage release cycles, you can contact the previous maintainer or the PEAR developers mailing list and announce your will to maintain the package. _________________________________________________________________ Buying things from wishlists For all the PEAR developers, PEAR is a project they are working on in their free-time, which means that they don't earn any money with it. If you or the company you are working for is using a PEAR package in one of your/their (commercial) products, you/they can do this for free, of course. But if you think that the author of the package you are using desires some credits, it would be nice to buy something from his wishlist at Amazon or another internet store. To see if a PEAR developer has registered his wishlist, surf to the Account information page and select the developer from the list there. If he has a wishlist, it's noted somewhere on the detail page. _________________________________________________________________ Chapter 17. Recommendations 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 Stardards), 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. _________________________________________________________________ RGB represesentation The following snippet defines an array that holds the RGB definition of the green coloring that is used in the official PEAR logo. $color = array(0x33, 0x99, 0x00); or $color = array(51, 153, 0); Please note that the internal, numerical representation of both forms of the example are equal. The values represent the RGB (red, green, blue) values. It was decided not to use "r", "g" and "b" as indices for the array, because numerical indices allow easier creation of color arrays in the sourcecode, make handling less complicated and are an already commonly used array representation for colors. _________________________________________________________________ RGB representation with alpha-values Since this an extension of the RGB representation above, it is recommended to use a forth value for alpha-channel-prepresentation. An example of the "PEAR-green" with aprox. 80% intensity would be: $color = array(0x33, 0x99, 0x00, 0xCC); For consistency the alpha-value is also from the range 0..255. A value of 255 means fully opaque (full color-intensity, same as in RGB- notation), 0 means fully transparent. Please note this is in contrast to the alpha-value used by imagecolorallocate(). The alpha-representation used in PEAR was choosen for consistency with the other RGB values and because it is commonly accepted practise in many other applications (image-processing tools, etc.). _________________________________________________________________ Other color representations than RGB(A) Since RGB/RGBA will used for graphic generation on a computer we decided to leave out an optional type-identifier classifying colors as RGB/RGBA. However for different color-representations an identifier is needed. The optional identifier "type" can be added to the color array. $color = array(0x33, 0x99, 0x00, 0xCC, "type" => "RGB"); Currently the following types are definied, with array-indices from 0..n follwing the colornames listed behind them: * RGB - red, green, blue * CYMK - cyan, yellow, magenta, black (key) Please note that also the RGBA representation has the type "RGB" since it's closely related. _________________________________________________________________ Conversion to/between the color-representations The PEAR-package Image_Color will (hopefully soon) contain all needed functions to convert arbitrary color formats to the internal RGBA representation and convert different color representations. Status: Currently Image_Color already offers functions to convert color-names (e.g. "green") and hex-representations-strings (e.g. "#339900") to the PEAR-RGBA-format. We are working to get alpha- channel support added hopefully soon and will later add funtions for CYMK-conversion as well. _________________________________________________________________ Chapter 18. Writing documentation This chapter provides a detailed description how to write documentation using one of the supported formats. It is aimed at both PEAR developers that are already maintaining packages in PEAR and at people who are planning to contribute a new package. _________________________________________________________________ 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. _________________________________________________________________ Required software Even if DocBook XML can (like any other XML file) be written using a normal text editor, it is optimal for users to install some software on their machine in order to test the validity of the documenting efforts. A list of the required software and a installation instruction can be found in the PHP Documentation HOWTO. Apart from providing information about the software, this HOWTO also provides a ton of other useful information that goes far beyond this chapter. One is encouraged to completely read it. (Chapter II can be skipped, because it only contains information that is very PHP specific.) Unfortunately, installing that software can be difficult under some circumstances. If you are unable to get it working, don't use that as an excuse for not writing documentation. There are two test servers that every two hours automatically download peardoc from CVS and build the manual. Any parsing errors your changes cause will show up in the logs the next time the build happens: http://www.appelsiini.net/~tuupola/php/peardoc2/peardoc.txt (time zone: EET = UTC+2, EEST = UTC+3) http://pear.php-tools.net/peardoc.log (time zone: CET = UTC+1, CEST = UTC+2) http://pear.php-tools.net/peardoc-error.log These automatic builds also give you an idea of what your changes will look like in the actual manual. This is helpful because the manual on the PEAR website is only built once per week (Sundays ~12:00 UTC). http://www.appelsiini.net/~tuupola/php/peardoc2/ http://pear.php-tools.net/peardoc/ Warning The manual on the PEAR website is built only once per week. Any XML validation errors will cause the build to fail. If the main build fails, the old version remains in place, meaning the manual will be out of date. Therefore, always check the test build logs to ensure your changes are valid. More importantly, do not commit updates shortly before the main build happens (Sundays ~12:00 UTC). Once the necessary software is in place, one has to get the latest version of the XML sources from PEAR's CVS repository: $ cvs -d :pserver:@cvs.php.net:/repository login [password] $ cvs co peardoc If you do not own an account for cvs.php.net, please choose cvsread as the username. When asked for the password, type phpfi. After that the directory ./peardoc will contain a local copy ("sandbox") of the latest sources. If you are not yet familiar with CVS, then the online book "Open Source Development with CVS" will provide you with all the necessary information. _________________________________________________________________ Directory structure This chapter will not describe all the details about the directory structure, because one can find out the essentials about it by browsing the previously created directory peardoc. As a starting point for package documentors peardoc/en/package/ fits well. If one has further questions concerning the directory structure, they can ask on the documentation mailinglist. _________________________________________________________________ Writing documentation Instead of a long and boring description for writing documentation using DocBook, we would like to point you to a bunch of "reference documents", from which you should be able to learn quickly: * peardoc/authoring The CVS tree has a complete set of DocBook XML templates. These files provide the standard of how PEAR documentation should look. The simplest way to utilize them is to copy them to your working directory, rename them accordingly, edit the contents to match the reality of your program and then upload them to your package's directory in the repository. * HTTP Request The documentation for HTTP_Request, which is a relatively small package, only consists of a bunch of end-user documentation, which describes all of the basic features of the package. Each feature description includes at least one example. For small packages with only a handful of methods this documentation type is absolutely enough. * XML Beautifier XML_Beautifier is a package that is also relatively compact, but which supports different configuration options. These options are described in the documentation Additionally the documentation gives usage examples and (unlike HTTP_Request) also includes API documentation for its methods. * DB DB is a large PEAR package and has excellent documentation, including usage examples. The DB docs carefully adhere to the formatting specified in peardoc/authoring. The link above goes to the DocBook source code in the CVS repository. It might be helpful to exa