Summary

• Title: PEAR2 Package Naming Standard
• Version: 0.1.1
• Status: Defunct
• Type: Informative Document
• Wiki link: http://wiki.php.net/pear/rfc/PEAR2_Naming_Standards
• Last updated: December 20th, 2009

This RFC is no longer under consideration, as per the PEAR Group meeting discussion on 12/20/2009.

• Name: Travis Swicegood
• Name: Joshua Eichorn
• Email: pear-group@php.net

• This RFC is under the BSD License

• Currently only pear-group however, future is http://news.php.net/php.pear.dev

This document is intended to introduce developers to a naming scheme within PEAR2 that reflects a how PEAR2 packages should be named within PHP 5.3's new namespaces.

This RFC outlines the various challenges that have been faced by people using PEAR1 packages and how a new PEAR2 naming standard can help.

• All namespaces are lowercased
• Packages should be named: pear2\<package_name>\<ClassName>
• Packages own all sub-namespaces within their package and can use them however they wish
• All underscores (_) in the package name (i.e., everything that's lowercase) will not be translated as anything other than underscores
• Underscores within the <ClassName> portion will be treated like PEAR1 to allow for sub-directories without specifying a sub-namespace

• Embedding PEAR1 code within an existing SVN repository is hard
• Currently tracking multiple PEAR packages within the same category is hard via svn:externals
• There is no differentiation between namespace and class name (i.e., in PEAR2\Pyrus\Installer, is PEAR2 a class, and what about PEAR2\Pryus?)

Our current structure was born out of a need to segregate files in a logical way with no namespaces and/or packages. Using the standard “Some_Class” notation was helpful to provide a semi-logical directory structure. As a side effect, classes ended up with names that did not properly reflect what they did if taken outside of the convention.

For example, MDB2's Driver classes. The class itself should be called Driver, but in order to keep all drivers in the same directory, they are named along the lines of MDB2_Driver_mysql. The true package here is a “mysqldriver” with a relation to MDB2. If the traditional naming scheme is continued in PEAR2 and the _ is replaced with \, the package name will now be MDB2\Driver\mysql. Under the proposed naming convention the wording of the names could be reworked to read more like plain English: pear2\mdb2_mysqldriver. The fully-qualified class name would be pear2\mdb2_mysqldriver\Driver.

As the above example demonstrates, this addresses three separate issues:

1. It removes the legacy naming convention that inverts the noun and adjective. That makes the package name read more like true English. You have a “mysql driver”, not a “driver mysql”.
2. It allows the sub-package to be handled inside its own directory. With \ being the only portion of the code that is replaced inside its own directory, this puts all of the mdb2 drivers in directories along side the mdb2 package so they can be tracked separately by version control systems such as Subversion and Git via svn:externals or git-submodules without having to first stage the code in a staging directory.
3. By changing the package to lowercase it becomes immediately apparent what the instantiable class is. This removes all ambiguity from a PEAR2\MDB2\Driver\Mysql style of naming.

• namespace - the namespace declared at the top of a file containing a class, function, or variable
• fully-qualified name - the full name of a class, including its namespace

N/A

This section tries to outline any possible problems within this proposal to either:

• Outline ways that they are addressed, or
• Bring them up for discussion

Many developers use sub-directories to organize their packages into logical groups of operation. This becomes necessary as packages become larger. While we would like to have developers use a modular approach for their packages along the lines of what MDB2 has done, for some packages this type of package, sub-package structure may be overkill.

To handle multiple directories within a package, this proposal offers two solutions.

1. Each package owns all namespaces within its package namespace. pear2\foobar can define any additional sub-namespaces it wishes to and each sub-namespace will follow the same directory naming schema.
2. The last portion of the fully-qualified name will follow traditional PEAR1 style of _ to DIRECTORY_SEPARATOR replacement. This means that the pear2\foobar\Foo_Bar class will exist within the pear2/foobar/Foo/Bar.php file; likewise, pear2\foobar\foo\Bar_Foo translates into pear2/foobar/foo/Bar/Foo.php. Put more simply, anything that has an uppercase letter in its name (i.e., any class) continues to use the traditional PEAR1 naming-to-directory mapping.

Any new naming schema requires transition. Whether it is replacing _ with \, or something more involved, any change will require some effort on the part of developers. Unfortunately, this is an issue that can not be dealt with. The PEAR Group believes this opportunity to take advantage of the new namespace functionality for updating our naming schema to something more logical is worth any temporary inconvenience to developers while they reprogram their wetware.