...
Table of Contents | ||
---|---|---|
|
Coding Standards
Consistency is important, even more so when writing open-source code, since the code belongs to millions of eyeballs, and bug-fixing relies on these teeming millions to actually locate bugs and understand how to solve it.
...
If use an IDE, you can use the CodeSniffer code validator to help you write better code.
PHP
Variable names
Just like class, method and function names, variable names should be written in English so as to be readable to as many people as possible.
...
- 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:
Code Block | ||
---|---|---|
| ||
$my_var = 17; $a = $b; |
Operators
"
+
", "-
", "*
", "/
", "=
" and any combination of them (e.g. "/=
") need a space between their left and right members.Code Block borderStyle solid $a + 17; $result = $b / 2; $i += 34;
"
.
" does not have a space between its left and right members.Code Block borderStyle solid echo $a.$b; $c = $d.$this->foo();
Note title Recommendation For performance reasons, please do not overuse concatenation.
"
.=
" needs a space between its left and right members.Code Block borderStyle solid $a .= 'Debug';
When testing a boolean variable, do not use a comparison operator, but directly use the value itself, or the value prefixed with an exclamation mark:
Code Block // do not use this if ($var == true) // ...nor this if ($var == false) // use this if ($var) // ...or this if (!$var)
Statements
if
,elseif
,while
,for
: need a space between theif
keyword and the parentheses()
.Code Block borderStyle solid if (<condition>) while (<condition>)
When a combination of
if
andelse
is used and both can return a value, theelse
statement has to be omitted.Code Block borderStyle solid if (<condition>) return false; return true;
Note title Recommendation We recommend you to use only one
return
statement per method/function.When a method/function returns a boolean and the current method/function's returned value depends on it, the
if
statement has to be avoided.Code Block borderStyle solid public aFirstMethod() { return $this->aSecondMethod(); }
Tests must be grouped by entity.
Code Block borderStyle solid if ($price AND !empty($price)) ... if (!Validate::$myObject OR $myObject->id === NULL) ...
Visibility
- The visibility must be defined every time, even when it is a public method.
The order of the method properties should be:
visibility static function functionName()
.Code Block borderStyle solid private static function foo()
Method / Function names
Method and function names always use CamelCase: begin with a lowercase character and each following words must begin with an uppercase character.
Code Block borderStyle solid public function myExampleMethodWithALotOfWordsInItsName()
Braces introducing method code have to be proceeded by a carriage return.
Code Block borderStyle solid public function myMethod($arg1, $arg2) { ... }
Method and function names must be explicit, so function names such as
b()
oref()
are completely forbidden.Info title Exceptions The only exceptions are the translation function (called
l()
) and the debug functions (namedp()
andd()
).
Enumeration
Commas have to be followed (and not preceded) by a space.
Code Block | ||
---|---|---|
| ||
protected function myProtectedMethod($arg1, $arg2, $arg3 = null) |
Objects / Classes
Object name must be singular.
Code Block borderStyle solid class Customer
Class name must follow the CamelCase practice, except that the first letter is uppercase.
Code Block borderStyle solid class MyBeautifulClass
Constants
- Constant names must be written in uppercase, except for "true", "false" and "null" which must be lowercase:
ENT_NOQUOTE
,true
. Constant names have to be prefixed with "
PS_
" inside the core and module.Code Block borderStyle solid define('PS_DEBUG', 1); define('PS_MODULE_NAME_DEBUG', 1);
- Constant names should only use alphabetical characters and "_".
Keywords
All keywords have to be lowercase: as, case, if, echo, null
.
Configuration variables
Configuration variables follow the same rules as defined above.
Strings
Strings have to be surrounded by simple quotes, never double ones.
Code Block | ||
---|---|---|
| ||
echo 'Debug'; $myObj->name = 'Hello '.$name; |
Comments
- Inside functions and methods, only the "
//
" comment tag is allowed. After the "
//
" comment marker, a space is required:Code Block borderStyle solid // My great comment
The "
//
" comment marker is tolerated at the end of a code line.Code Block borderStyle solid $a = 17 + 23; // A comment inside my example function
Outside of functions and methods, only the "
/*
" and "*/
" comment markers are allowed.Code Block borderStyle solid /* This method is required for compatibility issues */ public function foo() { // Some code explanation right here ... }
A phpDoc comment block is required before the declaration of the method.
Code Block borderStyle solid /** * 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)
Info title For more informations For more information about the PHP Doc syntax: http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.pkg.html.
Return values
The
return
statement does not need brackets, except when it deals with a composed expression.Code Block borderStyle solid return $result; return ($a + $b); return (a() - b()); return true;
The
return
statement can be used to break out of a function.Code Block borderStyle solid return;
Call
Performing a function call preceded by a "@
" is forbidden, but beware of function/method call with login/password or path arguments.
Code Block | ||
---|---|---|
| ||
myfunction(); // In the following example, we put a @ for security reasons @mysql_connect(...); |
Tags
There must be an empty line after the PHP opening tag.
Code Block borderStyle solid <?php require_once('my_file.inc.php');
- The PHP closing tag is forbidden at the end of a file.
Indentation
- The tabulation character ("
\t
") is the only indentation character allowed. Each indentation level must be represented by a single tabulation character.
Code Block borderStyle solid function foo($a) { if ($a == null) return false; ... }
Array
The
array
keyword must not be followed by a space.Code Block borderStyle solid array(17, 23, 42);
When too much data is inside an array, the indentation has to be as follows:
Code Block borderStyle solid $a = array( 36 => $b, $c => 'foo', $d => array(17, 23, 42), $e => array( 0 => 'zero', 1 => $one ) );
Block
Braces are prohibited when they only define one instruction or a combination of statements.
Code Block | ||
---|---|---|
| ||
if (!$result) return false; for ($i = 0; $i < 17; $i++) if ($myArray[$i] == $value) { $result[] = $myArray[$i]; return $result; } else $failed++; |
Security
All users' data (data entered by users) has to be cast.
Code Block borderStyle solid $data = Tools::getValue('name'); $myObject->street_number = (int)Tools::getValue('street_number');
Note getValue()
does not protect your code from hacking attempts (SQL injections, XSS flaws and CRSF breaches). You still have to secure your data yourself.
One PrestaShop-specific securization method ispSQL($value)
: it helps protect your database against SQL injections.All method/function's parameters must be typed (when
Array
orObject
) when received.Code Block borderStyle solid public myMethod(Array $var1, $var2, Object $var3)
For all other parameters, they have to be cast each time they are used, except when they are sent to other methods/functions.
Code Block borderStyle solid 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 wide.
- Functions and methods lines are limited to 80 characters. Functions must have a good reason to have an overly long name: keep it to the essential!
Other
- It is forbidden to use a ternary into another ternary, such as
echo ((true ? 'true' : false) ? 't' : 'f');
. - We recommend the use of
&&
and||
into your conditions:echo ('X' == 0 && 'X' == true)
. Please refrain from using reference parameters, such as:
Code Block function is_ref_to(&$a, &$b) { ... }
SQL
Table names
Table names must begin with the PrestaShop "
_DB_PREFIX_
" prefix.Code Block borderStyle solid ... FROM `'. _DB_PREFIX_.'customer` ...
- Table names must have the same name as the object they reflect: "
ps_cart
". - Table names have to stay singular: "
ps_order
". - Language data have to be stored in a table named exactly like the object's table, and with the "
_lang
" suffix: "ps_product_lang
".
SQL query
Keywords must be written in uppercase.
Code Block borderStyle solid SELECT `firstname` FROM `'._DB_PREFIX_.'customer`
Back quotes ("
`
") must be used around SQL field names and table names.Code Block borderStyle solid SELECT p.`foo`, c.`bar` FROM `'._DB_PREFIX_.'product` p, `'._DB_PREFIX_.'customer` c
Table aliases have to be named by taking the first letter of each word, and must be lowercase.
Code Block borderStyle solid 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 also used in the name.
Code Block borderStyle solid SELECT ca.`id_product`, cu.`firstname` FROM `'._DB_PREFIX_.'cart` ca, `'._DB_PREFIX_.'customer` cu
A new line has to be created for each clause.
Code Block borderStyle solid $query = 'SELECT pl.`name` FROM `'._DB_PREFIX_.'product_lang` pl WHERE pl.`id_product` = 17';
- It is forbidden to make a
JOIN
in aWHERE
clause.
Installing the code validator (PHP CodeSniffer)
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 (http://pear.php.net/package/PHP_CodeSniffer/). 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.
...
Info |
---|
In order for it to be recognized as a basic standard, it must be placed in the CodeSniffer's / Standards folder |
PhpStorm integration
If you use PhpStorm (http://www.jetbrains.com/phpstorm/), follow these steps:
- Go to Settings -> Inspection -> PHP -> PHP Code Sniffer.
- Set the path to the
phpcs
executable. - Set the coding standard as "PrestaShop" (which is only available if you did put in CodeSniffer's
/Standards
folder).
Integration to vim
Several plugins are available online. For instance, you can use this one: https://github.com/bpearson/vim-phpcs/blob/master/plugin/phpcs.vim
Put in your ~/.vim/plugin
folder.
...
Code Block |
---|
nmap <C-F9>:CodeSniffErrorOnly<CR> imap <C-F9> <Esc>:CodeSniffErrorOnly<CR> nmap <F9>:CodeSniff<CR> imap <F9> <Esc>:CodeSniff<CR>a |
Command line (Linux)
You do not have to use Eclipse to use PHP CodeSniffer, you can also install it so that it can be called from the command line.
...