PEAR Group - Administrative Documents

» Package Directory Structure

Published: 14th November 2003

The goal is to unify the directory naming inside CVS and after installation.

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

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

"Name" refers to the last part of the "The_Package_Name", all subclasses of the main class, should be put in there or subdirectories of it. You can refer to - the directory "Lite" as an example (this basically documents what we currently do anyway). These types of dirs are optional.

The "data" and "misc" dirs should be optional, because it will not make sense to have them for every single package in PEAR.

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

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

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

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