PHP Coding Style

The following text is the IspCP team rules 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 simple or 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 ;";

But the better is like this to avoid concatenation:

$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'
);

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 IspCP_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
 *
 * The contents of this file are subject to the Mozilla Public License
 * Version 1.1 (the "License"); you may not use this file except in
 * compliance with the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS"
 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the
 * License for the specific language governing rights and limitations
 * under the License.
 *
 * The Original Code is "VHCS - Virtual Hosting Control System".
 *
 * The Initial Developer of the Original Code is moleSoftware GmbH.
 * Portions created by Initial Developer are Copyright (C) 2001-2006
 * by moleSoftware GmbH. All Rights Reserved.
 * Portions created by the ispCP Team are Copyright (C) 2006-2009 by
 * isp Control Panel. All Rights Reserved.
 *
 * @category	ispCP
 * @package	the_package
 * @subpackage	subpackage
 * @copyright 	2001-2006 by moleSoftware GmbH
 * @copyright 	2006-2009 by ispCP | http://isp-control.net
 * @version 	$Id$
 * @link 	http://isp-control.net
 */
 
/**
 * Short description for class
 *
 * Long description for class (if any)...
 *
 * @category	ispCP
 * @package	package
 * @subpackage	subpackage
 * @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
 * @filesource
 */
class ispCP_FooBar {
	/**
	 * Short description for method
	 *
	 * Long description for method (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 Method lable since Revision
	 * @deprecated Method deprecated in Revision
	 * @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

<?php
/**
 * ispCP ω (OMEGA) a Virtual Hosting Control System
 *
 * The contents of this file are subject to the Mozilla Public License
 * Version 1.1 (the "License"); you may not use this file except in
 * compliance with the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS"
 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the
 * License for the specific language governing rights and limitations
 * under the License.
 *
 * The Original Code is "ispCP - ISP Control Panel".
 *
 * The Initial Developer of the Original Code is ispCP Team.
 * Portions created by Initial Developer are Copyright (C) 2006-2010 by
 * isp Control Panel. All Rights Reserved.
 *
 * @category	ispCP
 * @package	package
 * @subpackage	subpackage
 * @copyright	2006-2010 by ispCP | http://isp-control.net
 * @author	Laurent Declercq <laurent.declercq@ispcp.net>
 * @version	SVN: $Id$
 * @link	http://isp-control.net ispCP Home Site
 * @license	http://www.mozilla.org/MPL/ MPL 1.1
 * @filesource
 */
 
/**
 * Short description for class
 *
 * Long description for class (if any)...
 *
 * @category	ispCP
 * @package	package
 * @subpackage	subpackage
 * @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 ispCP_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
	 * @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/

The names of the classes directly map to the directories in which they are stored. The root level directory of ispCP standard library (Only the classes) is the ”./include/ispCP” directory.

Classes names should be given descriptive names. Avoid using abbreviations where possible. Class names should always begin with the 'ispCP_' prefix, each letter that starts a new “word” is capitalized.

Examples of good class names are:

  ispCP_Config_Handler, ispCP_Registry, ispCP_Config_Handler_Db

Concret example:

The class:

class ispCP_Config_andler_Db {}

should live under the ./include/ispCP/Config/Handler/Db.php directory.

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 function and private class methods should be preceded by a single underscore. For example:

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

All class members have to be declared as public, private or protected. Private and Protected class members should be preceded by a single underscore. For example:

  public $somevar; 
  private $_anothervar;
  protected $_lastvar;
  public static $statvar;
 
  public function setConfigValue()
  private function _sortValues()
  protected function _checkInput()
  public 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.

Note: Usage of global variables is discouraged. Instead, it's recommended to use the registry to share your data (see the IspCP_Registry class).

All scripts contributed to ispCP must:

• Be stored as Unicode text using 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) The PHP closing tag (?>) should be omitted. Additionally there should be one line feed after the last line. This means that when the cursor is at the very end of the file, it should be one line below.

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.