PHP Coding Style

The following text is a recommendation for coding. See this text as guideline.

Use an indent of 1 tab. Tab width: 4. It is recommended to keep lines length at 80 characters long for better code readability.

Strings are always surrounded in double quotes. SQL statements are always written with back ticks:

$sql = "SELECT `id`, `name` from `people` WHERE `name`='Fred' OR `name`='Susan'";

When concatenating strings with the ”.” operator, it is permitted to break the statement into multiple lines to improve readability. In these cases, each successive line should be padded with tabs such that the ”.” operator is aligned under or behind the ”=” operator:

$sql = "SELECT `id`, `name` FROM `people` "
     . "WHERE `name` = 'Susan' "
     . "ORDER BY `name` ASC ";

An indexed array may be started with any non-negative number, however this is discouraged and it is recommended that all arrays have a base index of 0. Negative numbers are not permitted as indices.

When declaring indexed arrays with the array construct, a trailing space must be added after each comma delimiter to improve readability:

$sampleArray = array(1, 2, 3, "ispCP");

It is also permitted to declare multiline indexed arrays using the “array” construct. In this case, each successive line must be padded with tabs such that beginning of each line aligns as shown below:

$sampleArray = array(
	1, 2, 3, "ispCP",
 	$a, $b, $c,
	56.44, $d, 500
);

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:

$sampleArray = array(
	'firstKey'  => 'firstValue',
	'secondKey' => 'secondValue'
);

Control Structures These include if, for, while, switch, etc. Here is an example “if statement”, since it is the most complicated of them:

<?php
if ((condition1) || (condition2)) {
 	action1;
} elseif ((condition3) && (condition4)) {
 	action2;
} else {
	defaultaction;
}
?>

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.

For switch statements:

<?php
switch (condition) {
	case 1:
		action1;
 		break;
 
	case 2:
 		action2;
 		break;
 
	default:
 		defaultaction;
 		break;
}
?>

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. Here's an example:

<?php
$var = foo($bar, $baz, $quux);
?>

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 tabs may be inserted to promote readability:

<?php
$short		= foo($bar);
$long_variable	= foo($baz);
?>

Class declarations have their opening brace on the same line like the class name is:

<?php
class fooBar {
 
	//... code goes here
 
}
?>

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. Here is a slightly longer example:

<?php
function translate(&$string, $javascript = false) {
 	if (is_boolean($javascrip)) {
 		$result = $string;
 	} else {
 		$result = htmlspecialchar($string);
 	}
 
 	return $result;
}
?>

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

Non-documentation comments are strongly encouraged. A general 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. Use of Perl/shell style comments (#) is discouraged.

Anywhere you are unconditionally including a class file, use require_once. Anywhere you are conditionally including a class file (for example, factory methods), 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.

Always use <?php ?> to delimit PHP code, not the <? ?> shorthand.

<?php
/**
 * ispCP ω (OMEGA) a Virtual Hosting Control System
 *
 * @copyright 	2001-2006 by moleSoftware GmbH
 * @copyright 	2006-2008 by ispCP | http://isp-control.net
 * @version 	SVN: $ID$
 * @link 		http://isp-control.net
 * @author 		ispCP Team
 *
 * @license
 *   This program is free software; you can redistribute it and/or modify it under
 *   the terms of the MPL General Public License as published by the Free Software
 *   Foundation; either version 1.1 of the License, or (at your option) any later
 *   version.
 *   You should have received a copy of the MPL Mozilla Public License along with
 *   this program; if not, write to the Open Source Initiative (OSI)
 *   http://opensource.org | osi@opensource.org
 */
 
/**
 * Short description for class
 *
 * Long description for class (if any)...
 *
 * @author	Original Author <author@example.com>
 * @author	Another Author <another@example.com>
 * @copyright 	2006-2008 by ispCP | http://isp-control.net
 * @version	Version of the Class
 * @see		Other Functions (in other Files)
 * @since	Class available since Revision
 * @deprecated	Class deprecated in Revision
 */
class fooBar {
 	/**
 	 * Short description for function
 	 *
 	 * Long description for function (if any)...
 	 *
 	 * @author	Original Author <author@example.com>
 	 * @author	Another Author <another@example.com>
 	 * @copyright 	2006-2008 by ispCP | http://isp-control.net
 	 * @version	Version of the Function
 	 * @see		Other Functions (in other Files)
 	 * @since	Function available since Revision
 	 * @deprecated	Function deprecated in Revision
 	 *
 	 * @access	public
 	 * @global	Type	$gvar	Description of the gvar
 	 * @param	Type 	$tpl	Description of the Input
 	 * @param	Type 	$var1	Description of the Input
    	 * @param	Type	$var2   Description of the Input
 	 * @return	Type 		The returned value
 	 */	
 	function connect(&$tpl, $var1, $var2 = false) {
 		global $tpl;
 		// Code goes here
 
 		return $result;
 	}
 
}
?>

Optional Tags @author @see

For more information to phpDoc see http://manual.phpdoc.org/

Classes should be given descriptive names. Avoid using abbreviations where possible. Class names should always begin with an lowercase letter, each letter that starts a new “word” is capitalized. Examples of good class names are:

  login, inputChecks, databaseUpdate

Functions and methods should start with a lowercase letter and each letter that starts a new “word” is capitalized. Some examples:

  connect(), writeLog(), buildSomeWidget()

Private class members (meaning class members that are intended to be used only from within the same class in which they are declared; PHP does not yet support truly-enforceable private namespaces) are preceded by a single underscore. For example:

  _sort(), _checkInput(), $this->_select()

When using PHP5 in Future:

All class members have to be declared as public, private, protected. Protected class members (meaning class members that are intended to be used only from within the same class in which they are declared or from subclasses that extend it) are not preceded by a single underscore. For example:

  public $somevar; 
  private $anothervar;
  protected $lastvar;
  static $statvar;
 
  public function setConfigValue()
  private function sortValues()
  protected function checkInput()
  static function show()

Constants 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 the Database package all begin with DB_.

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

If your package needs to define global variables, their name should start with a single underscore followed by the package name and another underscore.

All scripts contributed to ispCP must:

• Be stored as ASCII text
• Use UTF-8 character encoding
• Be Unix formatted

“Unix formatted” means two things:

1) 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.

2) There should be one line feed after the closing PHP tag (?>). This means that when the cursor is at the very end of the file, it should be one line below the closing PHP tag.

Starting on 01 January 2008, all new code that is suggested for inclusion into ispCP must be E_STRICT-compatible. This means that it must not produce any warnings or errors when PHP's error reporting level is set to E_STRICT.

The development of existing packages that are not E_STRICT-compatible can continue as usual. If however a new major version of the package is released, this major version must then be E_STRICT-compatible.

This part of the Coding Standards describes how errors are handled in ispCP files that are developed for PHP 5 and 6. It uses Exceptions, introduced in PHP 5.0 with Zend Engine 2, as the error handling mechanism.