PHP Programming/Coding Standards< PHP Programming
Indenting and Line LengthEdit
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.
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.
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 <span> tag and apply a style. Instead, use the <strong> 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 <div> tags in place of <p> tags when the contents of the tag will be other block level elements such as <ul>.
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:
And here is a small bit of how we style those elements.
This verbosity ensures that other elements are not accidentally styled.
See PHP Syntax Below. The languages are similar enough that the same rules should apply in most cases.
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 & HTMLEdit
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.
These include if, for, while, switch, etc.
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.
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.
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:
Function declarations are similar to function calls with the beginning brace on the same line as the function declaration.
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.
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 (/* */) and standard C++ comments (//) are both fine. The use of Perl / shell style comments (#) is strongly discouraged.
Anywhere you are unconditionally including a class file, use require_once. Anywhere you are conditionally including a class file, use include_once. 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 require_once will not be included again by include_once.
PHP Code TagsEdit
Always use <?php ?> to delimit PHP code, not the <? ?> shorthand. This is the most portable way to include PHP code on different operating systems and server setups.
Header Comment BlocksEdit
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.
Required Tags That Have Variable ContentEdit
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.
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.
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.
This tag is required when a file or class is no longer used but has been left in place for backwards compatibility.
Order and SpacingEdit
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.
Use example.com, example.org and example.net for all example URLs and email addresses, per RFC 2606.
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 NamesEdit
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(_). 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 VariablesEdit
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 DB begin with DB_.
Note: The true, false and null constants are excepted from the all-uppercase rule, and must always be lowercase.
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.
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.