...
- 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;
- "." don't 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 don't abusing of use of do not overuse concatenation.
- "
.=
" need needs a space between its left and right members.Code Block borderStyle solid $a .= 'Debug';
Statements
- if, elseif, while, for: presence of need a space between the
if
keyword and the bracket()
.Code Block borderStyle solid if (<condition>) ... while (<condition>)
- When a combination of if and else are is used and that they should both can return a value, the else has to be avoided.
Code Block borderStyle solid if (<condition>) return false; return true;
Note title Recommendation We recommend one return per method / function
- When a method/function returns a boolean and the current method/function return '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 everytimeevery time, even when it is a public method.
- The order of the method properties should be:
visibility static function
namefunctionName()
.Code Block borderStyle solid private static function foo()
Method / Function names
- Method and function name always begins names always use CamelCase: begin with a lowercase character and each following words must begin with an uppercase character (CamelCase) .
Code Block borderStyle solid public function myExempleMethodWithALotOfWordsInItsNamemyExampleMethodWithALotOfWordsInItsName()
- Braces introducing method code have to be preceded by a carriage return.
Code Block borderStyle solid public function myMethod($arg1, $arg2) { [...] }
- Method and function names must be explicit, so such function names such as "
b()
" or "ef()
" are completly completely forbidden.Info title Exceptions The only exceptions are the translation function (called "
l()
" ) and debug the functions "(namedp()
", " andd()
").
Enumeration
Commas have to be followed (and only followednot preceded) by a space.
Code Block | ||
---|---|---|
| ||
protected function myProtectedMethod($arg1, $arg2, $arg3 = null) |
...
- 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
...
- Define names must be written in uppercase
- Define names have to be prefixed by "PS_" inside the core and module
Code Block borderStyle solid 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” "null" which must be lowercase
e.g. ": ENT_NOQUOTE
", "true
".
Configuration variables
Configuration variables follow the same rules as definesdefined above.
Strings
Strings have to be surrounded by simple quotes, never double ones.
Code Block | ||
---|---|---|
| ||
echo 'Debug'; $myObj->name = 'Hello '.$name; |
...
- Inside functions and methods, only the "//" comment tag is allowed.
- After the "//" comment tagmarker, a space “is required:
//
Comment“ is requiredComment
.Code Block borderStyle solid // My great comment
- The "//" comment tag marker is tolerated at the end of a code line.
Code Block borderStyle solid $a = 17 + 23; // A comment inside my exempleexample function
- Outside funcions of functions and methods, only the "/" and "/" comment tags markers are allowed.
Code Block borderStyle solid /* This method is required for compatibility issues */ public function foo() { // Some code explanation right here [ ...] }
- PHP Doc Element comment block is required before the declaration of the method declarations .
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 informations about the PHP Doc normsyntax: http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.pkg.html
Return values
- Return 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;
- Break The return statement can be used to break out of a function.
Code Block borderStyle solid return;
...
Function call preceded by a "@" is forbidden but beware with function / method call with login / password or path argmumentsarguments.
Code Block | ||
---|---|---|
| ||
myfunction() // In the following exempleexample, we put a @ for security reasons @mysql_connect([...]); |
Tags
- An There must be an empty line has to be left after the PHP opening tag.
Code Block borderStyle solid <?php require_once('my_file.inc.php');
- The PHP ending tag is forbidden
...
- 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);
- The indentation when When too much datas are data is inside an array, the indentation has to follow the following.
Code Block borderStyle solid $a = array( 36 => $b, $c => 'foo', $d => array(17, 23, 42), $e => array( 0 => 'zero', 1 => $one ) );
Bloc
Brasses Braces are prohibited when they only define only one instruction or a statement combination of statements.
Code Block | ||
---|---|---|
| ||
if (!$result)
return false;
for ($i = 0; $i < 17; $i++)
if ($myArray[$i] == $value)
$result[] = $myArray[$i];
else
$failed++;
|
Security
- All user datas 's data (datas data entered by users) have has to be castedcast.
Code Block borderStyle solid $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.
Code Block borderStyle solid public myMethod(Array $var1, $var2, Object $var3)
- For all other parameters, they have to be casted cast each time they are useused, but not 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); }
...
- Source code lines are limited to 120 characters.
- Functions and methods lines are limited to 80 with good justificationscharacters. Functions must have a good reason to have an overly long name: keep it to the essential!
Other
- It 's is forbidden to use a ternary into another ternary (such as
echo ((true ? 'true' : false) ? 't' : 'f');
). - We recommend to the use of
&&
and||
into your conditions:echo ('X' == 0 && 'X' == true
- Please don't use reference parameters (such as {{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
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 table, and with the suffix "_lang" e.g. 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 make 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 taken too also used in the name.
Code Block borderStyle solid SELECT ca.`id_product`, cu.`firstname` FROM `'.DB_PREFIX.'cart` ca, `'. _DB_PREFIX_.'customer` cu
- Indentation has to be done for each clause
Code Block borderStyle solid $query = 'SELECT pl.`name` FROM `'.PS_DBP.'product_lang` pl WHERE pl.`id_product` = 17';
- It’s It is forbidden to make a join JOIN in a WHERE clause.
Installing the code validator
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.
You can access download the PrestaShop code standard using SVN: http://svn.prestashop.com/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: http://www.phpsrc.org/projects/pti/wiki/Installation.
The configuration of the plugin is also very simple: http://www.phpsrc.org/projects/pti-php-codesniffer/wiki/Configuration. 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 : go to "PHP Tools" and choosing choose the PS standard that you downloaded earlier (see link above).Tip: if
Tip |
---|
If the file does not automatically validate, as it should, you can configure this in the "Preferences" menu, "Validation" |
...
option. Otherwise, just right-click on the folder/file in the |
...
file-tree, and choose "PHP Tools" in the contextual menu (which you can also be set as a shortcut). |
Command line (Linux)
You can install PHP CodeSniffer without having to use Eclipse, using the command line.
Code Block |
---|
apt-get install php-pear
pear install PHP_CodeSniffer
svn co http://svn.prestashop.com/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: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.
- Install PEAR: http://pear.php.net/
$> apt-get install php-pear
- Install PHP CodeSniffer in PEAR: http://pear.php.net/package/PHP_CodeSniffer
$> pear install PHP_CodeSniffer
- Add the PrestaShop standard that you downloaded from SVN earlier, and place it in PHP CodeSniffer's "Standards" folder.
$> svn co http://svn.prestashop.com/branches/norm/ /usr/share/php/PHP/CodeSniffer/Standards/Prestashop
- Launch PHP CodeSniffer
$> phpcs --config-set default_standard Prestashop
Using the program
The various options for this command are well explained in its documentation. For now, here 's is the easy way to launch it:
Code Block |
---|
$> phpcs --standard=/cheminpath/versto/normenorm/Prestashop /fichierfolder/ou/dossier/a/valider/or/fileToCheck |
In order to only display errors, not warnings:
Code Block |
---|
$> phpcs --standard=/cheminpath/versto/normenorm/Prestashop --warning-severity=99 /fichierfolder/ou/dossier/a/valider/or/fileToCheck |
If you have already meanually manually installed PHP CodeSniffer, the program should be in PEAR's "scripts" folder.
Note | ||
---|---|---|
Windows users: although the
|
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:
- Location: path to the
phpcs
program (orphpcs.bat
for Windows users). - Arguments: the arguments for the command line, for instance
--standard=Prestashop
${selected_resource_loc}.
- Location: path to the