PHP Programming/Coding Standards

Indenting and Line Length
Use an indent of one tab (no spaces! Good IDEs can convert this to pseudo spaces - 2, 4, etc.). If you use Emacs to edit your code, you should set indent-tabs-mode to nil. 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 judgement. This applies to all file types: PHP, HTML, CSS, JavaScript, etc.

Indentation rules should be applied in the source file that will be edited by others. The visual appeal of HTML output should not be taken into consideration when writing code that generates HTML.

Validation
As of September 2006, the DocType on our documents will be XHTML 1.0 Transitional. Therefore, compliant HTML according to the XHTML 1.0 standard should be used at all times. Exceptions should be just that. A good reference for the XHTML elements can be found at DevGuru.

Also, to ensure that the box model is done correctly by Internet Explorer 6, we must use the following DocType on all pages. Only this doc type is to be used. No other information should be placed before it.

Example DocType

Element Usage
When at all possible, try and use standard HTML elements properly. "Div Soup" should be avoided at all times. "Div Soup" refers to HTML where a div (or span) is used when it is not needed. For example, if you need a word to be bolded, do not use a &lt;span&gt; tag and apply a style. Instead, use the &lt;strong&gt; tag.

Tables should be used only when data needs to be displayed in columns. One cell tables should never be used.

One common exception is needing to use &lt;div&gt; tags in place of &lt;p&gt; tags when the contents of the tag will be other block level elements such as &lt;ul&gt;.

Example HTML

CSS Standards
Inline styles should be avoided!

Styles in CSS files should be as specific as possible. One should always try to avoid using a bare class name. If you are styling an object that has a container, your style should reference the continer as well as the element being styled. The more verbose your styles in your CSS the less likely you will mess up another element on another page accidentally.

The most efficient way to style an element is by styling that type of element inside a container. If only one element needs to be styled in a special way, it should be assigned and id and styled using the id and preferably a container.

Here is some HTML from our sidebar:

Example Article HTML

And here is a small bit of how we style those elements.

Example CSS

This verbosity ensures that other elements are not accidentally styled.

Request Vars
Although our servers currently have register_globals enabled, PHP 6 will remove this option. Therefore, in new code, you should always use the super globals $_GET, $_POST, and $_COOKIE. $_REQUEST should be used only when it is known for sure that a variable could be supplied using multiple methods.

PHP & HTML
No "template system" such as Smarty will be used. PHP itself is a templating language. A best effort should be made to arrange your code by putting logic at the top of file and output at the bottom of the file. Sometimes that will require looping the same information twice. However, this will make the code much more maintainable.

Example PHP/HTML Mix

Control Structures
These include if, for, while, <tt>switch</tt>, etc. Example <tt>if</tt> statement

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. Example <tt>switch</tt> statement

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. Example function call

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 are similar to function calls with the beginning brace on the same line as the function declaration. Example <tt>function</tt> definition

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. Longer <tt>function</tt> example

Comments
Complete inline documentation comment blocks (docblocks) must be provided. Please read the Sample File and Header Comment Blocks sections to learn the specifics of writing docblocks for PHP. Further information can be found on the phpDocumentor website.

Non-documentation comments are strongly encouraged. A 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 (<tt>/* */</tt>) and standard C++ comments (<tt>//</tt>) are both fine. The use of Perl / shell style comments (<tt>#</tt>) is strongly discouraged.

Including Code
Anywhere you are unconditionally including a class file, use <tt>require_once</tt>. Anywhere you are conditionally including a class file, use <tt>include_once</TT>. 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 <tt>require_once</tt> will not be included again by <tt>include_once</tt>.

PHP Code Tags
Always use <tt><?php ?></tt> to delimit PHP code, not the <tt><? ?></tt> shorthand. This is the most portable way to include PHP code on different operating systems and server setups.

Header Comment Blocks
All source code files shall contain a "page-level" docblock at the top of each file and a "class-level" docblock immediately above each class or function. Example docblocks

Short Descriptions
Short descriptions must be provided for all docblocks. They should be a quick sentence, not the name of the item. Please read the Coding Standard's Sample File about how to write good descriptions.

@author
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.

@since
This tag is required when a file or class is added after the package's initial release. Do not use it in an initial release.

@deprecated
This tag is required when a file or class is no longer used but has been left in place for backwards compatibility.

Order and Spacing
To ease long-term readability of the source code, the text and tags must conform to the order and spacing provided in the example above. This standard is adopted from the JavaDoc standard.

Example URLs
Use example.com, example.org and example.net for all example URLs and email addresses, per RFC 2606.

Classes
Classes should be given descriptive names. Avoid using abbreviations where possible. Class names should always begin with an uppercase letter and use mixed case to separate words.

Examples of good class names are:

Log NetFinger HTMLUploadError

Functions, Methods and Variable Names
Functions, methods and variable names should be named using the Unix C style. If applicable, functions should have the package or library name as a prefix to avoid name collisions. Names should be all lowercase with each new "word" separated by an underscore(<tt>_</tt>). Some examples:

connect get_data build_some_widget

$i $count $temp_array

Private class members (meaning class members that are intended to be used only from within the same class in which they are declared are preceded by a single underscore. For example:

_sort _init_tree $this->_status

Constants and Global Variables
Constants and global variables 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 a package named <tt>DB</tt> begin with <tt>DB_</tt>.

Note: The true, false and null constants are excepted from the all-uppercase rule, and must always be lowercase.

File Formats
All scripts must:


 * Be stored as ASCII text
 * Use ISO-8859-1 character encoding
 * Be Unix formatted, which means:
 * 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.
 * It is recommended that the last character in the file is a line feed. This means that when the cursor is at the very end of the file, it should be one line below the last line of text. Some utilities, such as diff, will complain if the last character in the file is not a line feed.

Sample File
Each docblock in 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.

Please take note of the vertical and horizontal spacing. They are part of the standard.