PrestaShop development standard

Summary

#PHP	#PHP	#SQL
#Variable names	#Strings	#Table names
#Assignments	#Comments	#SQL query
#Operators	#Return values
#Statements	#Call
#Visibility	#Tags
#Method / Function names	#Indentation
#Enumeration	#Array
#Objects / Classes	#Bloc
#Defines	#Security
#Keywords	#Limitations
#Constants	#Other
#Configuration variables

PHP

Variable names

Corresponding to data from databases: $my_var
Corresponding to algorithm: $my_var
The visibility of a member variable does not affect its name: private $my_var

Assignments

There should be a space between variable and operators:
```
$my_var = 17;
$a = $b;
```

Operators

"+", "-", "*", "/", "=" and any combination of them (e.g. "/=") need a space between
left and right members
```
$a + 17;
$result = $b / 2;
$i += 34;
```
"." don't have space between left and right members
```
echo $a.$b;
$c = $d.$this->foo();
```
Recommendation

For performance reasons, please don't abusing of use of concatenation.
".=" need a space between left and right members
```
$a .= 'Debug';
```

Statements

if, elseif, while, for: presence of a space between the if keyword and the bracket
```
if (<condition>)
while (<condition>)
```
When a combination of if and else are used and that they should both return a value, the else has to be avoided.
```
if (<condition>)
	return false;
return true;
```
Recommendation

We recommend one return per method / function
When a method/function returns a boolean and the current method/function return depends on it, the if statement has to be avoided
```
public aFirstMethod()
{
	return $this->aSecondMethod();
}
```

Tests must be grouped by "entity"

if ($price AND !empty($price))
	[...]
if (!Validate::$myObject OR $myObject->id === NULL)
	[...]

Visibility

The visibility must be defined everytime, even when it is a public method.
The order of the method properties should be: visibility static function name()
```
private static function foo()
```

Method / Function names

Method and function name always begins with a lowercase character and each following words must begin with an uppercase character (CamelCase)
```
public function myExempleMethodWithALotOfWordsInItsName()
```
Braces introducing method code have to be preceded by a carriage return
```
public function myMethod($arg1, $arg2)
{
	[...]
}
```
Method and function names must be explicit, so such function names as "b()" or "ef()" are completly forbidden.
Exceptions

The only exceptions are the translation function called "l()" and debug functions "p()", "d()".

Enumeration

Commas have to be followed (and only followed) by a space.

protected function myProtectedMethod($arg1, $arg2, $arg3 = null)

Objects / Classes

Object name must be singular
```
class Customer
```
Class name must follow the CamelCase practice except that the first letter is uppercase
```
class MyBeautifulClass
```

Defines

Define names must be written in uppercase
Define names have to be prefixed by "PS_" inside the core and module
```
define('PS_DEBUG', 1);
define('PS_MODULE_NAME_DEBUG', 1);
```
Define names does not allow none alphabetical characters. Except “_”.

Keywords

All keywords have to be lowercase
e.g. as, case, if, echo, null

Constants

Constants must be uppercase except for "true" and "false" and “null” which must be lowercase
e.g. "ENT_NOQUOTE", "true"

Configuration variables

Configuration variables follow same rules as defines

Strings

Strings have to be surrounded by simple quotes, never double ones

echo 'Debug';
$myObj->name = 'Hello '.$name;

Comments

Inside functions and methods, only the "//" comment tag is allowed
After the "//" comment tag, a space “// Comment“ is required
```
// My great comment
```
The "//" comment tag is tolerated at the end of a code line
```
$a = 17 + 23; // A comment inside my exemple function
```

Outside funcions and methods, only the "/" and "/" comment tags are allowed

/* This method is required for compatibility issues */
public function foo()
{
// Some code explanation right here
[...]
}

PHP Doc Element comment is required before the method declarations

/**
 * Return field value if possible (both classical and multilingual fields)
 *
 * Case 1 : Return value if present in $_POST / $_GET
 * Case 2 : Return object value
 *
 * @param object $obj Object
 * @param string $key Field name
 * @param integer $id_lang Language id (optional)
 * @return string
 */
protected function getFieldValue($obj, $key, $id_lang = NULL)

For more informations

For more informations about the PHP Doc norm: http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.pkg.html

Return values

Return statement does not need brackets except when it deals with a composed
expression
```
return $result;
return ($a + $b);
return (a() - b());
return true;
```
Break a function
```
return;
```

Call

Function call preceded by a "@" is forbidden but beware with function / method call with login / password or path argmuments.

myfunction()
// In the following exemple we put a @ for security reasons
@mysql_connect([...]);

Indentation

The tabulation character ("\t") is the only indentation character allowed
Each indentation level must be represented by a single tabulation character
```
function foo($a)
{
	if ($a == null)
		return false;
	[...]
}
```

Array

The array keyword must not be followed by a space
```
array(17, 23, 42);
```

The indentation when too much datas are inside an array has to follow the following

$a = array(
	36 => $b,
	$c => 'foo',
	$d => array(17, 23, 42),
	$e => array(
		0 => 'zero',
		1 => $one
	)
);

Bloc

Brasses are prohibited when they define only one instruction or a statement combination

if (!$result)
	return false;

for ($i = 0; $i < 17; $i++)
	if ($myArray[$i] == $value)
		$result[] = $myArray[$i];
	else
		$failed++;

Security

All user datas (datas entered by users) have to be casted.

$data = Tools::getValue('name');

$myObject->street_number = (int)Tools::getValue('street_number');

All method/function's parameters must be typed (when Array or Object) when received.
```
public myMethod(Array $var1, $var2, Object $var3)
```

For all other parameters they have to be casted each time they are use, but not when
sent to other methods/functions

protected myProtectedMethod($id, $text, $price)
{
	$this->id = (int)$id;
	$this->price = (float)$price;
	$this->callMethod($id, $price);
}

Limitations

Source code lines are limited to 120 characters
Functions and methods lines are limited to 80 with good justifications

Other

It's forbidden to use a ternary into another ternary
We recommend to use && and || into your conditions
Please don't use reference parameters

SQL

Table names

Table names must begin with the PrestaShop "DB_PREFIX" prefix
```
[...] FROM `'. _DB_PREFIX_.'customer` [...]
```
Table names must have the same name as the object they reflect
e.g. "ps_cart"
Table names have to stay singular
e.g. "ps_order"
Language data have to be stored in a table named exactly like the object's one and with the suffix "_lang" e.g. "ps_product_lang"

SQL query

Keywords must be written in uppercase.

SELECT `firstname`
FROM `'. _DB_PREFIX_.'customer`

Back quotes ("`") must be used around field names and table names

SELECT p.`foo`, c.`bar`
FROM `'. _DB_PREFIX_.'product` p, `'. _DB_PREFIX_.'customer` c

Table aliases have to be make by taking the first letter of each word, and must be
lowercase

SELECT p.`id_product`, pl.`name`
FROM `'. _DB_PREFIX_.'product` p
NATURAL JOIN `'. _DB_PREFIX_.'product_lang` pl

When conflicts between table aliases occur, the second character has to be taken too

SELECT ca.`id_product`, cu.`firstname`
FROM `'.DB_PREFIX.'cart` ca, `'. _DB_PREFIX_.'customer` cu

Indentation has to be done for each clause

$query = 'SELECT pl.`name`
FROM `'.PS_DBP.'product_lang` pl
WHERE pl.`id_product` = 17';

It’s forbidden to make a join in WHERE clause

Installing the code validator

Voici un bref tutoriel pour installer la moulinette de norme sur son PC et l'utiliser pour valider ses fichiers. La moulinette de norme passe par PHP CodeSniffer qui est un package de PEAR, le standard Prestashop a été créé pour l'occasion, constitué de nombreuses règles reprises des standards déjà existants, plus un certain nombre de règles personnalisées pour coller davantage au projet.

This is a brief tutorial on how to install a code validator on your PC and use it to validate your files. The code validator uses PHP CodeSniffer, which is a PEAR package. The PrestaShop code standard was created specifically for CodeSniffer, using many rules taken from existing standards, with added customized rules in order to better fit our project.

You can access the PrestaShop code standard using SVN: http://dev.prestashop.com/svn/v1/branches/norm (you must perform this step before going any further with this tutorial)

Eclipse integration

Quick links:

If you use Eclipse, you can integrate code validation within the text editor using a plugin, which is very easy to install.

The configuration of the plugin is also very simple. In the list of available packages, only choose PHP CodeSniffer and PEAR if you do not yet have them.

You will then have to add the PrestaShop code standard to the Eclipse preferences, by going to "PHP Tools" and choosing the PS standard that you downloaded earlier (see link above).

Tip: if the file does not automatically validate, as it should, you can configure this in the "Preferences" menu, "Validation" item. Otherwise, just right-click on the folder/file in the filetree, and choose "PHP Tools" in the contextual menu (which you can also set as a shortcut).

Command line (Linux)

You can install PHP CodeSniffer without having to use Eclipse, using the command line.

apt-get install php-pear
pear install PHP_CodeSniffer
svn co http://dev.prestashop.com/svn/v1/branches/norm /usr/share/php/PHP/CodeSniffer/Standards/Prestashop
phpcs --config-set default_standard Prestashop

Using the program

In order to install the validator as a program that you can launch from the command line, follow these steps:

Install PEAR: http://pear.php.net/
Install PHP CodeSniffer in PEAR: http://pear.php.net/package/PHP_CodeSniffer
Add the PrestaShop standard that you downloaded from SVN earlier, and place it in PHP CodeSniffer's "Standards" folder.

The various options for this command are well explained in its documentation. For now, here's the easy way to launch it:

$> phpcs --standard=/chemin/vers/norme/Prestashop /fichier/ou/dossier/a/valider/

In order to only display errors, not warnings:

$> phpcs --standard=/chemin/vers/norme/Prestashop --warning-severity=99 /fichier/ou/dossier/a/valider/

If you have already meanually installed PHP CodeSniffer, the program should be in PEAR's "scripts" folder.

Windows users: although the phpcs.bat file should be in that "scripts" folder, you might have to edit it in order for it to work properly (replace the paths with yours):

path/to/php.exe \-d auto_apprend_file="" \-d auto_prepend_file{color} {color:#339966}\-d include_path="path/to/PEAR/" path/to/pear/scripts/phpcs %\*

Integrating the program to Eclipse's console (optional)

Click on the "External tools" button in the icon bar (a green arrow pointing at a small red folder).
Click on the "External tools configuration" tab.
Double-click on "Program" in order to create a configuration:
1. Location: path to the phpcs program (or phpcs.bat for Windows users).
2. Arguments: the arguments for the command line, for instance --standard=Prestashop ${selected_resource_loc}

Child pages

Development standard