Section 12.2. PEAR Standards

12.2. PEAR Standards

PEAR's Coding Standard, or PCS for short, is primarily meant for developers of PEAR packages. Some of it is useful for those who just use PEAR packages as well, especially the section about how different types of symbols are named. Even if you are not planning to develop any PEAR packages yourself, it is a good idea to read the section on naming so you know what to expect when you use PEAR packages.

12.2.1. Symbol Naming

Different types of symbols, such as function or variable names, have naming schemes designed to make each type of symbol stand out from each other.

12.2.1.1 Constants

Constant names are all uppercase, with the (uppercased) package name as a prefix. Here are some examples:

 PEAR_ERROR_DIE     (from PEAR package) AUTH_EXPIRED       (from Auth package, without namespaces) DB_DATAOBJECT_INT  (from DB_DataObject package) 

Optionally, if you do not care about PHP 4 compatibility, use class const variables. With class const variables, you must use the properly capitalized class name, and then the constant name in all uppercase:

 PEAR_Error::DIE    (from PEAR package) Auth::EXPIRED      (from Auth package, without namespaces) DB_DataObject::INT (from DB_DataObject package) 

12.2.1.2 Global Variables

With the advent of static class variables in PHP 5, there is little reason to use global variables in library code anymore. Packages that are PHP 4-compatible cannot use static class variables, of course. Here is PEAR's naming convention for globals:

 $_Package_Name_variable 

The convention is $_{Package_Name}_{lowercased_variable_name}. The lowercasing is for clearly separating the package name part (which requires an initial capital letter in each underscore-separated element), and the variable name part.

12.2.1.3 Functions

Functions are named simply with the package name prefixed as for constants. The package name has its case preserved; the part following the prefix is studlyCaps with an initial lowercase letter. Here is an example:

 function Package_Name_functionName() {     print "Röyksopp<br />\n"; } 

If the function is "private," which means that it is not intended for use outside the package that defines it, the name is prefixed with an underscore:

 function _Package_Name_privateFunction() {     print "Dadafon<br />\n"; } 

Note that this applies to functions, not methods.

12.2.1.4 Classes

Class names are also prefixed with the package name, or may be the same as the package name. The rules for use of upper- and lowercase characters are the same for package names and class names. Here are some examples:

 class Package_Name ... class Package_Name_OtherClass ... 

There is one exception to the "initial uppercase letter" rule for classes: Objects returned by factory methods and such may have a class name where the generated part of the class name is all lowercase. The factory implementation may not always know the right capitalization, so if you always lowercase the variable part of the class name, you are safe.

For example, the DB package uses this scheme for its driver classes, which are called DB_mysql, DB_oci8, and so on, rather than DB_MySQL and DB_OCI8.

12.2.1.5 Methods

Methods are named with an initial lowercase letter and an uppercase letter at the start of every word or token after the first, just like Java. Acronyms and abbreviations that are normally written in all uppercase are kept in uppercase. Here are some examples:

 class Foo {     function test() ...     function anotherTest() ...     function toHTML() ... } 

For private methods, you have two options. If you care about PHP 4 compatibility, prefix the names of "private" methods with an underscore:

 class Foo      {          function _privateMethod() ...      } 

Note that in PHP 5, this method is actually public. The leading underscore is just a naming convention.

If PHP 4 compatibility is not an issue, use private function without the underscore prefix:

 class Foo      {          private function privateMethod() ...      } 

12.2.1.6 Member Variables

The only requirement for member variables is that private members should be underscore-prefixed in PHP 4-compatible code. There is no notion of "protected" for PHP 4:

 class Foo {     var $public_member;     var $_private_member; } 

For PHP 5-only code, use the private/protected/public modifiers properly:

 class Foo {     public $member_variable;     protected $protected_member;     private $private_member;     static $static_classvar;     const CLASS_CONSTANT; } 

12.2.2. Indentation

PEAR uses four-character indentation, with spaces only (no tabs!). This part of the PEAR coding standards alone has caused more controversy than any other part, so it deserves some explanation.

Users expect the tab key in their editor to do some form of indentation. This may range from simply inserting a tab character into the file, or something clever like looking at the indentation of the previous line to figure out how to indent the current line. It does not have to insert a tab character into the source file.

When someone views a source file with tab characters in it, it is up to the viewer program how they are rendered. Traditionally, from the old days of VT100 UNIX terminals and typewriters, tab characters were rendered by moving the cursor to the next multiple-of-eight column. The Emacs editor renders tabs as up to eight spaces by default; most Windows and Macintosh editors use four spaces. Most editors let you configure the tab width, which gives even more possibilities. The result is that if you put a tab character in a file, the reader of the file is likely to see different indentation than you intended, because his viewer program renders the tab differently from your editor.

There are many examples of this, but rest assured that the only reliable way of rendering a certain amount of whitespace at the beginning of a line is using only space characters. For more rant on this issue, look at http://www.jwz.org/doc/tabs-vs-spaces.html.

Here is an example that demonstrates the PEAR indentation style:

 <?php class IndentExample {     static $tmpfiles = array();     function sampleMethod($dbh, $id)     {         $results = $dbh->getAll('SELECT * FROM bar WHERE id = ?',                                 array($id));         if (PEAR::isError($results)) {             return $results;         }         foreach ($results as $row) {         switch ($row[0]) {             case 'foo':                 print "A foo-style row<br />\n";                 break;             case 'bar':                 print "A bar-style row<br />\n";                 break;             default:                 print "Something else...<br />\n";                 break;             }         }     } } function clean_up() {     foreach (IndentExample::$tmpfiles as $tmpfile) {         if (file_exists($tmpfile)) {             unlink($tmpfile);         }     }     IndentExample::$tmpfiles = array(); } ?>