PrestaShop 1.5
Child pages
  • Coding Standards

Versions Compared

Old Version 9

changes.mady.by.user Xavier Borderie

Saved on

compared with

New Version Current

changes.mady.by.user Xavier Borderie

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Table

...

of

...

content

...

Table of Contents

...

maxLevel3

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.

This is why, when writing anything for PrestaShop, be it a theme, a module or a core patch, you should strive to follow the following guidelines. They are the ones that the PrestaShop developers adhere to, and following them is the surest way to have your code be elegantly integrated in PrestaShop.

In short, having code consistency helps keeping the code readable and maintainable.

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.

Use lowercase letters, and separate words using underscores. Do not ever use CamelCase.

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

Assignments

  1. There should be a space between variable and operators:
Code Block
borderStylesolid
$my_var = 17;
$a = $b;
{code}


h3. Operators

# "{{+}}", "{{-}}", "{{*}}", "{{/}}", "{{=}}" and any combination of them

Operators

  1. "+", "-", "*", "/", "=" and any combination of them (e.g.

...

  1. "/=")

...

  1. need

...

  1. a

...

  1. space

...

  1. between

...

  1. their

...

  1. left

...

  1. and

...

  1. right

...

  1. members.

...

  1. Code Block

...

  1. borderStyle

...

  1. solid

...

  1. $a + 17;
$result = $b / 2;
$i += 34;

...

  2. "." does not have a space between its left and right members.
     Code Block
    borderStylesolid
    echo $a.$b;
$c = $d.$this->foo();

...
  1.  Note
    titleRecommendation
    For performance reasons, please do not overuse concatenation.
  2. ".=" needs a space between its left and right members.
     Code Block
    borderStylesolid
    $a .= 'Debug';

...
  2. 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
  1. if, elseif, while, for: need a space between the if keyword and the parentheses ().
     Code Block
    borderStylesolid
    if (<condition>)

...
  1. 
while (<condition>)

...
  2. When a combination of if and else is used and both can return a value, the else statement has to be omitted.
     Code Block
    borderStylesolid
    if (<condition>)
	return false;
return true;

...
  1.  Note
    titleRecommendation
    We recommend to use only one return statement per method/function.
  2. When a method/function returns a boolean and the current method/function's 
...
  1.  returned 
...
  1.  value 
...
  1.  depends 
...
  1.  on 
...
  1.  it, 
...
  1.  the 
...
  1. if
...
  1.  statement 
...
  1.  has 
...
  1.  to 
...
  1.  be 
...
  1.  avoided.
...
  1.  Code Block
...
  1. borderStyle
...
  1. solid
...
  1. public aFirstMethod()
{
	return $this->aSecondMethod();
}

...
  2. Tests must be grouped by entity.
     Code Block
    borderStylesolid
    if ($price 
...
  1. && !empty($price))
	...
if (!Validate::$myObject 
...
  1. || $myObject->id === NULL)
	...

...
Visibility
  1. The visibility must be defined every time, even when it is a public method.
  2. The order of the method properties should be: visibility static function functionName().
     Code Block
    borderStylesolid
    private static function foo()

...
Method / Function names
  1. Method and function names always use CamelCase: begin with a lowercase character and each following words must begin with an uppercase character.
     Code Block
    borderStylesolid
    public function myExampleMethodWithALotOfWordsInItsName()

...
  2. Braces introducing method code have to be preceded by a carriage return.
     Code Block
    borderStylesolid
    public function myMethod($arg1, $arg2)
{
	...
}

...
  2. Method and function names must be explicit, so function names such as b() or ef()are completely forbidden.
     Info
    titleExceptions
    The only exceptions are the translation function (called l()) and the debug functions (named p() and d()).
Enumeration
Commas have to be followed (and not preceded) by a space.
 Code Block
borderStylesolid
protected function myProtectedMethod($arg1, $arg2, $arg3 = null)
{code}


h3. Objects / Classes

# Object name must be singular.
{code:borderStyle=solid}
class Customer
{code}
# Class name must follow the CamelCase practice, except that the first letter is uppercase.
{code:borderStyle=solid}
class MyBeautifulClass
{code}


h3. Defines

# Define names must be written in uppercase.
# Define names have to be prefixed by "{{PS\_}}" inside the core and module.
{code:borderStyle=solid}

Objects / Classes
  1. Object name must be singular.
     Code Block
    borderStylesolid
    class Customer

  2. Class name must follow the CamelCase practice, except that the first letter is uppercase.
     Code Block
    borderStylesolid
    class MyBeautifulClass

Constants
  1. Constant names must be written in uppercase, except for "true", "false" and "null" which must be lowercase: ENT_NOQUOTE, true.
  2. Constant names have to be prefixed with "PS_" inside the core and module.
     Code Block
    borderStylesolid
    define('PS_DEBUG', 1);
define('PS_MODULE_NAME_DEBUG', 1);

...
  2. 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
borderStylesolid
echo 'Debug';
$myObj->name = 'Hello '.$name;
{code}


h3. Comments

# Inside functions and methods, only the "{{//}}" comment tag is allowed.
# After the "{{//}}" comment marker, a space is required: {{// Comment}}.
{code:borderStyle=solid}

Comments
  1. Inside functions and methods, only the "//" comment tag is allowed.
  2. After the "//" comment marker, a space is required:
     Code Block
    borderStylesolid
    // My great comment

...
  2. The "//
...
  1. " 
...
  1.  comment 
...
  1.  marker 
...
  1.  is 
...
  1.  tolerated 
...
  1.  at 
...
  1.  the 
...
  1.  end 
...
  1.  of 
...
  1.  a 
...
  1.  code 
...
  1.  line.
...
  1.  Code Block
...
  1. borderStyle
...
  1. solid
...
  1. $a = 17 + 23; // A comment inside my example function

...
  2. Outside of functions and methods, only the "/*" and "*/" comment markers are allowed.
     Code Block
    borderStylesolid
    /* This method is required for compatibility issues */
public function foo()
{
	// Some code explanation right here
	...
}

...
  2. A phpDoc comment block is required before the declaration of the method.
     Code Block
    borderStylesolid
    /**
 * 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)

...
  1.  Info
    titleFor more informations
    For more information about the PHP Doc syntax: http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.pkg.html
...
  1. .
Return values
  1. The return statement does not need brackets, except when it deals with a composed expression.
     Code Block
    borderStylesolid
    return $result;
return ($a + $b);
return (a() - b());
return true;

...
  2. The return statement can be used to break out of a function.
     Code Block
    borderStylesolid
    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
borderStylesolid
myfunction();

// In the following example, we put a @ for security reasons
@mysql_connect(...);
{code}


h3. Tags

# There must be an empty line after the PHP opening tag.
{code:borderStyle=solid}

Tags
  1. There must be an empty line after the PHP opening tag.
     Code Block
    borderStylesolid
    <?php

require_once('my_file.inc.php');

...
  2. The PHP closing tag is forbidden at the end of a file.
Indentation
  1. The tabulation character ("\t") is the only indentation character allowed.
  2. Each indentation level must be represented by a single tabulation character.
     Code Block
    borderStylesolid
    function foo($a)
{
	if ($a == null)
		return false;
	...
}

...
Array
  1. The array keyword must not be followed by a space.
     Code Block
    borderStylesolid
    array(17, 23, 42);

...
  2. When too much data is inside an array, the indentation has to be as follows:
     Code Block
    borderStylesolid
    $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
borderStylesolid
if (!$result)
	    return false;
 
for ($i = 0; $i < 17; $i++)
	    if ($myArray[$i] == $value)
		    {
        $result[] = $myArray[$i];
	else
		$failed++;
{code        return $result;
    }
  h3. Security else
# All users' data (data entered by users) has to be cast.
{code:borderStyle=solid}
        $failed++;

Security
  1. All users' data (data entered by users) has to be cast.
     Code Block
    borderStylesolid
    $data = Tools::getValue('name');

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

...
  1.  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 is pSQL($value): it helps protect your database against SQL injections.
  2. All method/function's 
...
  1.  parameters 
...
  1.  must 
...
  1.  be 
...
  1.  typed 
...
  1.  (when 
...
  1. Array
...
  1.  or 
...
  1.  Object) 
...
  1.  when 
...
  1.  received.
...
  1.  Code Block
...
  1. borderStyle
...
  1. solid
...
  1. public myMethod(Array $var1, $var2, Object $var3)

...
  2. For all other parameters, 
...
  1.  they 
...
  1.  have 
...
  1.  to 
...
  1.  be 
...
  1.  cast 
...
  1.  each 
...
  1.  time 
...
  1.  they 
...
  1.  are 
...
  1.  used, 
...
  1.  except 
...
  1.  when 
...
  1.  they 
...
  1.  are 
...
  1.  sent 
...
  1.  to 
...
  1.  other 
...
  1.  methods/functions.
...
  1.  Code Block
...
  1. borderStyle
...
  1. solid
...
  1. protected myProtectedMethod($id, $text, $price)
{
	$this->id = (int)$id;
	$this->price = (float)$price;
	$this->callMethod($id, $price);
}

...
Limitations
  1. Source code lines are limited to 150 characters wide.
  2. 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
  1. It is forbidden to use a ternary into another ternary, such as echo ((true ? 'true' : false) ? 't' : 'f');.
  2. We recommend the use of && and || into your conditions instead of AND and OR: echo ('X' == 0 && 'X' == true).
  3. Please refrain from using reference parameters, such as:
     Code Block
    function is_ref_to(&$a, &$b) { ... }
...
SQL
Table names
  1. Table names must begin with the PrestaShop "_DB_PREFIX_" prefix.
     Code Block
    borderStylesolid
    ... FROM `'. _DB_PREFIX_.'customer` ...

...
  2. Table names must have the same name as the object they reflect: "ps_cart".
  3. Table names have to stay singular: "ps_order".
  4. 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
  1. Keywords must be written in uppercase.
     Code Block
    borderStylesolid
    SELECT `firstname`
FROM `'.
...
  1. _DB_PREFIX_.'customer`

...
  2. Back quotes ("
...
  1. `
...
  1. ") 
...
  1.  must 
...
  1.  be 
...
  1.  used 
...
  1.  around 
...
  1.  SQL 
...
  1.  field 
...
  1.  names 
...
  1.  and 
...
  1.  table 
...
  1.  names.
...
  1.  Code Block
...
  1. borderStyle
...
  1. solid
...
  1. SELECT p.`foo`, c.`bar`
FROM `'.
...
  1. _DB_PREFIX_.'product` p, `'.
...
  1. _DB_PREFIX_.'customer` c

...
  2. Table aliases have to be named by taking the first letter of each word, and must be lowercase.
     Code Block
    borderStylesolid
    SELECT p.`id_product`, pl.`name`
FROM `'.
...
  1. _DB_PREFIX_.'product` p
NATURAL JOIN `'.
...
  1. _DB_PREFIX_.'product_lang` pl

...
  2. When conflicts between table aliases occur, the second character has to be also used in the name.
     Code Block
    borderStylesolid
    SELECT ca.`id_product`, cu.`firstname`
FROM `'._DB_PREFIX_.'cart` ca, `'.
...
  1. _DB_PREFIX_.'customer` cu

...
  2. A new line has to be created for each clause.
     Code Block
    borderStylesolid
    $query = 'SELECT pl.`name`
FROM `'.
...
  1. _
...
  1. DB_PREFIX_.'product_lang` pl
WHERE pl.`id_product` = 17';

...
  2. It is forbidden to make a JOIN in a WHERE 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.
...
You 
...
 can 
...
 download 
...
 the 
...
 PrestaShop 
...
 code 
...
 standard 
...
 using 
...
Git: https://
...
github.
...
com/
...
PrestaShop/
...
PrestaShop-norm-validator (you 
...
 must 
...
 perform 
...
 this 
...
 step 
...
 before 
...
 going 
...
 any 
...
 further 
...
 with 
...
 this 
...
 tutorial).
...
 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:
  1. Go to Settings -> Inspection -> PHP -> PHP Code Sniffer.
  2. Set the path to the phpcs executable.
  3. 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.
You can add two shortcuts (for instance, F9 to display everything and Ctrl+F9 to hide warnings) in your .vimrc file in normal and insert mode :
 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 PhpStorm to use PHP CodeSniffer, you can also install it so that it can be called from the command line.
  1. Install PEAR: http://pear.php.net/
...

  1. $> 
...
  1.  apt-get 
...
  1.  install 
...
  1.  php-pear
...
  2. Install 
...
  1.  PHP 
...
  1.  CodeSniffer 
...
  1.  in 
...
  1.  PEAR: 
...
  1. http://pear.php.net/package/PHP_CodeSniffer
...

  1. $> 
...
  1.  pear 
...
  1.  install 
...
  1.  PHP_CodeSniffer
...
  2. Add 
...
  1.  the 
...
  1.  PrestaShop 
...
  1.  standard 
...
  1.  that 
...
  1.  you 
...
  1.  downloaded 
...
  1.  from 
...
  1.  SVN 
...
  1.  earlier, 
...
  1.  and 
...
  1.  place 
...
  1.  it 
...
  1.  in 
...
  1.  PHP 
...
  1.  CodeSniffer's 
...
  1.  "Standards" 
...
  1.  folder.
...

  1. $> git clone https://
...
  1. github.
...
  1. com/
...
  1. PrestaShop/PrestaShop-norm-validator/
...
  1. usr/share/php/PHP/CodeSniffer/Standards/Prestashop
...
  2. Set the Prestashop standard as the default one
    $> phpcs --config-set 
...
  1.  default_standard 
...
  1. Prestashop
The various options for this command are well explained in its documentation. For now, here is the easy way to launch it:
 Code Block
$> phpcs --standard=/path/to/norm/Prestashop /folder/or/fileToCheck{code}


In 
...
 order 
...
 to 
...
 only 
...
 display 
...
 errors, 
...
 not 
...
 warnings:
...
}
 Code Block
$> phpcs --standard=/path/to/norm/Prestashop --warning-severity=99 /folder/or/fileToCheck{code}


If 
...
 you 
...
 have 
...
 already 
...
 manually 
...
 installed 
...
 PHP 
...
 CodeSniffer, 
...
 the 
...
 program 
...
 should 
...
 be 
...
 in 
...
 PEAR's 
...
/scripts
...
 folder.
...
 Note
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):


{
 Code Block
}
path/to/php.exe -d auto_apprend_file="" -d auto_prepend_file -d include_path="path/to/PEAR/" path/to/pear/scripts/phpcs
{code}
{note}


h3. 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 (or {{phpcs.bat}} for Windows users).
## Arguments: the arguments for the command line, for instance {{\-\-standard=Prestashop}}.