Last Modified: 2008-06-03
Back to Coding Standards list
The following CS based on Zend’s and DB Medialab’s ones.
We really appreciate the author’s efforts and beleive we don’t violate their policies and licenses.
Describing the rules and guidelines for all possible PHP code occurrences in web applications.
Practice shows that developing in teams with more than one participant is almost impossible without common Coding Standards (CS).
Another benefit of CS usage is much more effective way to pass your deeds to another person and save time for both.
Please keep in mind, that in whole document below by word “Camel Case” we mean regular came case format but with first letter in lower case (“camelCase”), independently if it’s a prefix or regular word. Cases when first letter must be in upper case would be shown explicitly.
Incorrect
GetElementById
Correct
getElementById
It’s assumed that all rules are the must and not a guidelines, until opposite is saying explicitly.
Only two types of tags are allowed for PHP code.
Full – for any PHP code. Please note that closing tag is the must. Sometimes they say, that itisn’t required by PHP and should be omitted to prevent trailing spaces in the end of file — don’t listen them, just make sure you are using correct FTP uploader and PHP editor.
<?php
// yada yada yada
?>
Short – for direct inline outputs. You should avoid complex PHP statements in this case. Sometimes support of this tag is disabled on server, in this case use “global replace in files” function of your editor and replace “<?=” string with “<?php echo ” one (don’t forget about space in the replacement string).
<?=$result?>
There is lots of different extension variants on PHP files (.html, .php, .php3, .php4, .phtml, .inc, .class...). But there is only one main rule for PHP file extensions: all files that contain PHP code must have .php extension with no exceptions.
Using of tabs for identation is strongly advised, with tab's width set to 4 spaces.
Indent as much as needed, but no more. There are no arbitrary rules as to the maximum indenting level. If the indenting level is more than 4 or 5 levels you may think about code refactoring.
The target line length is 80 characters, i.e. developers should aim keep code as close to the 80-column boundary as is practical. However, longer lines are acceptable.
Avoid special characters in PHP files contents and output results. Use their entities instead.
Internation characters (any non-english ones) are prohibited as well.
Always try to avoid unintelligible names everywhere. You’ll forgot after couple of weeks what names “$var1” or “$var2” means and what is the difference between them. The same goes for all names and not variables only. Verbosity is highly encouraged.
When confronted with a situation where you could use an all upper case abbreviation instead use an initial upper case letter followed by all lower case letters. In other words, successive capitalized letters are never allowed.
Incorrect
parseXMLResponse
Correct
parseXmlResponse
Class names may only contain alphanumeric characters. Numbers are permitted in class names but are discouraged. Underscores are only permitted in place of the path separator for class libraries – the filename “HTML/Table.php” must map to the class name “Html_Table” (of course this rule doesn’t include “lib” or “includes” like folders).
Class names must be in camel notation with first letter in upper case.
Avoid adding “Class” or “Interface” words as prefixes or suffixes to class or interface names.
Incorrect
class sqlWrapper { }
class SQLWrapper { }
Correct
class SqlWrapper { }
class Sql_Wrapper { } // for SQL/Wrapper.php file
Function names may only contain alphanumeric characters, underscores are not permitted. Numbers are permitted in function names but are discouraged. Use camel case for function and method names.
Usually every method and function performs an action, so the name should make clear what it does: checkForErrors() instead of errorCheck(), dumpDataToFile() instead of dataFile(). This will also make functions and data objects more distinguishable.
Suffixes are sometimes useful:
For example: retryMax to mean the maximum number of retries, retryCnt to mean the current retry count.
Prefixes are sometimes useful:
For example: isHitRetryLimit.
Variable names may only contain alphanumeric characters. Underscores are not permitted. Numbers are permitted in variable names but are discouraged. Camel case for all variables and class members.
For class member variables that are declared with the “private” or “protected” construct, the first character of the variable name must be a single underscore. This is the only acceptable usage of an underscore in a variable name. Member variables declared “public” may never start with an underscore.
Verbosity is encouraged (as always). Variables should always be as verbose as practical. Terse variable names such as “$i” and “$n” are discouraged for anything other than the smallest loop contexts. If a loop contains more than 40 lines of code, the variables for the indices need to have more descriptive names.
Never use scope prefixes like “g” for global variables or “s” for static ones.
Incorrect
$_rest = 12;
class Example
{
private $Foo;
public $_bar;
}
Correct
$rest = 12;
class Example
{
private $_foo;
public $bar;
}
Constants may contain both alphanumeric characters and the underscore. Numbers are permitted in constant names. Constants must always have all letters capitalized.
To enhance readability, words in constant names must be separated by underscore characters.
Incorrect
define("hellomessage", "Hello world.");
define("HELLOMESSAGE", "Hello world.");
Correct
define("HELLO_MESSAGE", "Hello world.");
There are two brace placement strategies that are acceptable.
Place brace under and inline with keywords.
if (condition)
{
...
}
Traditional Unix policy of placing the initial brace on the same line as the keyword and the trailing brace inline on its own line with the keyword:
if (condition) {
...
}
if (condition)
{
}
foo($s);
return 1;
The most preferred layout is shown in example below.
if (condition) { // comment
// code
}
else if (condition) { // comment
// code
}
else { // comment
// code
}
Usage of braces even for single line conditioned code is the must.
If you have else if statements then it is usually a good idea to always have an else block for finding unhandled cases. Maybe put a log message in the else even if there is no corrective action taken.
Always put the constant on the left hand side of an equality/inequality comparison.
There are no spaces betwen parens and condition statement, but there must be one space character between statement parts.
Incorrect
if ( $errorNum==6&&!$parseResult ) {
...
}
Correct
if (6 == $errorNum && !$parseResult) {
...
}
One reason is that if you leave out one of the = signs, the parser will find the error for you. A second reason is that it puts the value you are looking for right up front where you can find it instead of buried at the end of your expression. It takes a little time to get used to this format, but then it really gets useful.
switch (...) {
case 1:
...
// fall through
case 2:
...
break;
case 3:
case 4:
...
break;
default:
...
break;
}
continue and break like goto should be used sparingly as they are magic in code. With a simple spell the reader is beamed to god knows where for some usually undocumented reason.
The two main problems with continue are:
Consider the following example where both problems occur:
while (TRUE) {
...
// A lot of code
...
if (condition) {
continue;
}
...
// A lot of code
...
if ( $i++ > STOP_VALUE) {
break;
}
}
Note: “A lot of code” is necessary in order that the problem cannot be caught easily by the programmer.
From the above example, a further rule may be given: mixing continue with break in the same loop is a sure way to disaster.
The trouble is people usually try and stuff too much code in between the ? and :. Here are a couple of clarity rules to follow:
Incorrect
(very long condition statement) ?
some long calculations goes here :
another strange logic;
Correct
(condition) ? live() : die();
No exceptions.
When a string is literal (contains no variable substitutions), the apostrophe or “single quote” is preferred to demarcate the string:
$a = 'Hello World!';
When a literal string itself contains apostrophes, it is permitted to demarcate the string with quotation marks or “double quotes”. It is preferred over escaping apostrophes, always try to avoid escaping, it makes code unreadable sometimes.
Incorrect, but possible if really needed
$a = 'Hello \'World\'!';
Correct (preferred)
$a = "Hello 'World'!";
Variable substitution is permitted when $ sign stays attached to variable name.
Incorrect
$a = "Hello ${name}!";
Correct
$a = "Hello $name!";
$a = "Hello {$name}!";
When using string concatenation, it’s proposed to omit spaces betwen concatenation operator, but the opposite is permitted.
Correct, but less preferred
$a = 'Hello' . ' ' . 'World!';
More preferred
$a = 'Hello'.' '.'World!';
For multiline strings definition concatenation operator must be at the end of previous line. For SQL statements it’s highly encouraged to omit per line concatenation operators to improve readability, and use them only if necessary (e.g. for inline funciton call).
It’s prohibited to start string constants after the = operator and use variable name length ident. All indents must be 4 characters length.
Incorrect
$someLongVariableName = "Hello World!"
. "What a ".getMood()." day today!"
. "Bye!";
Correct
$someLongVariableName =
"Hello World!".
"What a ".getMood()." day today!".
"Bye!";
// and for SQL statements
$sql = "
SELECT `id`, `name`
FROM customers
WHERE added = '".addcslashes($registrationDate)."'";
There are four rules for numerically indexed arrays
Incorrect
$someLongArrayName = array(1, 2,
6, 123
'hello!');
Correct
$foo = array(1, 2, 18);
$someLongArrayName = array(
1, 2,
6, 123
'hello!');
When declaring associative arrays with the array construct, it is encouraged to break the statement into multiple lines. In this case, each successive line must be padded with whitespace such that both the keys and the values are aligned:
$foo = array(
'name' => 'John',
'helloMessage' => 'Hello World!');
Classes must follow the rules below:
Class member variables must follow the rules below:
/**
* Documentation Block Here
*/
class TestPerson
{
public $name;
public $age;
private $_status;
// methods goes here
}
Methods inside classes must always declare their visibility by using one of the private, protected, or public constructs.
Like classes, the brace is always written on the line underneath the function name. There is no space between the function name and the opening parenthesis for the arguments.
Always separate function arguments with no spaces before comma and one space character after (the same as for numeric array arguments).
Pass-by-reference is permitted in the function declaration only. Call-time pass-by-reference is prohibited.
// simple function
bar($a1, $a2, &$a3) {
// code
}
// class declaration
/**
* Documentation Block Here
*/
class Foo
{
/**
* Documentation Block Here
*/
public function bar()
{
// entire content of function
// must be indented four spaces
}
}