Introduction

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

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

• require_once can introduce up to a 10% performance penalty on high-volume sites using multi-processor web servers due to increased latency. However, most users would experience at most 2% performance penalty on single-processor systems (as measured by Yahoo! engineer Gopal Vijayaraghavan)
• include_path is required in order to use a package. This makes it difficult to bundle a PEAR package within another application with its own include_path, to create a single file containing needed classes, to move a PEAR package to a phar archive without extensive source code modification.
• When top-level require_once is mixed with conditional require_once, this can result in code that is uncacheable by opcode caches such as APC (to be bundled with PHP 6).
• Relative require_once requires that include_path already be set up to the correct value, making it impossible to use a package without proper include_path.

Some of the benefits of require_once:

• You know right away if a file is missing, with a Fatal Error: missing file X (this is mitigated by using __autoload() with PEAR2_Autoload()).
• End-users don't need to know what files are within a package to use it (also mitigated by using __autoload() with PEAR2_Autoload()).

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

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

• construct a customized solution for loading needed files

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

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