Message-ID: <1053885537.375794.1710837601773.JavaMail.root@confluence-doc2-production> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_375793_320101686.1710837601767" ------=_Part_375793_320101686.1710837601767 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html Development standard

Development standard

Table of contents

=20 =20

PrestaShop dev= elopment standard

Summary

#PHP=

#PHP=

#SQL=

#Variable names

#Str= ings

#= Table names

= #Assignments

#Co= mments

#SQ= L query

#O= perators

#Return values

#= Statements

#Call

#= Visibility

#Tags

#Method / Function names

= #Indentation

= #Enumeration

#Array=

#Objects / Classes

#Bloc

#Def= ines

#Se= curity

#Ke= ywords

= #Limitations

#C= onstants

#Other=

#Configuration variables

PHP

Variable names

  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: pri= vate $my_var.

Assignments

  1. There should be a space between variable and operators:
=20
$my_var =
=3D 17;
$a =3D $b;
=20

Operators

  1. "+", "-", "*", "/", "=3D" and any combination of them (e.g. "/=3D") = need a space between their left and right members.

    =20
    $a + 17;
    $result =3D $b / 2;
    $i +=3D 34;
    
    =20
  2. "." does not have a space between its left and right members.

    =20
    echo $a.=
    $b;
    $c =3D $d.$this->foo();
    
    =20

    Recommendation

    For performance reasons, please do not overuse concatenation.

  3. ".=3D" needs a space between its left and right members= .

    =20
    $a .=3D =
    'Debug';
    
    =20

Statements

  1. if, elseif, while, for: need a space between the if key= word and the bracket ().

    =20
    if (<=
    condition>)
    ...
    while (<condition>)
    
    =20
  2. When a combination of if and else is used and both can return a valu= e, the else has to be avoided.

    =20
    if (<=
    condition>)
    =09return false;
    return true;
    
    =20

    Recommendation

    We recommend one return per method / function

  3. When a method/function returns a boolean and the current method/func= tion's returned value depends on it, the if statement has to be avoided

    =20
    public a=
    FirstMethod()
    {
    =09return $this->aSecondMethod();
    }
    
    =20
  4. Tests must be grouped by "entity"

    =20
    if ($pri=
    ce AND !empty($price))
    =09...
    if (!Validate::$myObject OR $myObject->id =3D=3D=3D NULL)
    =09...
    
    =20

Visibility

  1. The visibility must be defined every time, even when it is a public met= hod.
  2. The order of the method properties should be: visibility static function functionName().

    =20
    private =
    static function foo()
    
    =20

Method / Function names=

  1. Method and function names always use CamelCase: begin with a lowerca= se character and each following words must begin with an uppercase characte= r.

    =20
    public f=
    unction myExampleMethodWithALotOfWordsInItsName()
    
    =20
  2. Braces introducing method code have to be preceded by a carriage ret= urn.

    =20
    public f=
    unction myMethod($arg1, $arg2)
    {
    =09...
    }
    
    =20
  3. Method and function names must be explicit, so function names such a= s b() or ef()are completely forbidden.

    Exceptions

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

Enumeration

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

=20
protecte=
d function myProtectedMethod($arg1, $arg2, $arg3 =3D null)
=20

Objects / Classes

  1. Object name must be singular.

    =20
    class Cu=
    stomer
    
    =20
  2. Class name must follow the CamelCase practice, except that the first= letter is uppercase.

    =20
    class My=
    BeautifulClass
    
    =20

Defines

  1. Define names must be written in uppercase
  2. Define names have to be prefixed by "PS_" inside the core and module=

    =20
    define('=
    PS_DEBUG', 1);
    define('PS_MODULE_NAME_DEBUG', 1);
    
    =20
  3. Define names does not allow none alphabetical characters. Except "_".

Keywords

All keywords have to be lowercase: as, case, if, echo, null= .

Constants

Constants must be uppercase, except for "true", "false" and "null" which= must be lowercase: ENT_NOQUOTE, true.

Configuration variabl= es

Configuration variables follow the same rules as defined above.

Strings

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

=20
echo 'De=
bug';
$myObj->name =3D 'Hello '.$name;
=20

Comments

  1. Inside functions and methods, only the "//" comment tag is allowed.
  2. After the "//" comment marker, a space is required: // Comment= .

    =20
    // My gr=
    eat comment
    
    =20
  3. The "//" comment marker is tolerated at the end of a code line.

    =20
    $a =3D 1=
    7 + 23; // A comment inside my example function
    
    =20
  4. Outside of functions and methods, only the "/" and "/" comment markers are allowed.

    =20
    /* This =
    method is required for compatibility issues */
    public function foo()
    {
    =09// Some code explanation right here
    =09...
    }
    
    =20
  5. PHP Doc comment block is required before the declaration of the meth= od.

    =20
    /**
     * 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 =3D NULL)
    
    =20

    For more informations

Return values

  1. The return statement does not need brackets, except when it deals wi= th a composed expression.

    =20
    return $=
    result;
    return ($a + $b);
    return (a() - b());
    return true;
    
    =20
  2. The return statement can be used to break out of a function.

    =20
    return;
    
    =20

Call

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

=20
myfuncti=
on()
// In the following example, we put a @ for security reasons
@mysql_connect(...);
=20

Tags

  1. There must be an empty line after the PHP opening tag.

    =20
    <?php
    
    require_once('my_file.inc.php');
    
    =20
  2. The PHP ending tag is forbidden

Indentation

  1. The tabulation character ("
    t") is the = only indentation character allowed.
  2. Each indentation level must be represented by a single tabulation ch= aracter.

    =20
    function=
     foo($a)
    {
    =09if ($a =3D=3D null)
    =09=09return false;
    =09...
    }
    
    =20

Array

  1. The arraykeyword must not be followed by a space.

    =20
    array(17=
    , 23, 42);
    
    =20
  2. When too much data is inside an array, the indentation has to follow= the following.

    =20
    $a =3D a=
    rray(
    =0936 =3D> $b,
    =09$c =3D> 'foo',
    =09$d =3D> array(17, 23, 42),
    =09$e =3D> array(
    =09=090 =3D> 'zero',
    =09=091 =3D> $one
    =09)
    );
    
    =20

Bloc

Braces are prohibited when they only define one instruction or a combina= tion of statements.

=20
if (!$re=
sult)
=09return false;

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

Security

  1. All user's data (data entered by users) has to be cast.

    =20
    $data =
    =3D Tools::getValue('name');
    
    $myObject->street_number =3D (int)Tools::getValue('street_number');
    
    =20
  2. All method/function's parameters must be typed (when Array or Object= ) when received.

    =20
    public m=
    yMethod(Array $var1, $var2, Object $var3)
    
    =20
  3. For all other parameters, they have to be cast each time they are us= ed, except when they are sent to other methods/functions.

    =20
    protecte=
    d myProtectedMethod($id, $text, $price)
    {
    =09$this->id =3D (int)$id;
    =09$this->price =3D (float)$price;
    =09$this->callMethod($id, $price);
    }
    
    =20

Limitations

  1. Source code lines are limited to 150 characters.
  2. Functions and methods lines are limited to 80 characters. Functions mus= t 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 ec= ho ((true ? 'true' : false) ? 't' : 'f');).
  2. We recommend the use of && and || int= o your conditions: echo ('X' =3D=3D 0 && 'X' =3D=3D true
  3. Please don't use reference parameters (such as {{function is_ref_to(&am= p;$a, &$b) { ... }}}).

SQL

Table names

  1. Table names must begin with the PrestaShop "DB_PREFIX" pref= ix.

    =20
    ... FROM=
     `'. _DB_PREFIX_.'customer` ...
    
    =20
  2. Table names must have the same name as the object they reflect: "ps_car= t".
  3. Table names have to stay singular: "ps_order".
  4. Language data have to be stored in a table named exactly like the objec= t's table, and with the "_lang" suffix "ps_product_lang".

SQL query

  1. Keywords must be written in uppercase.

    =20
    SELECT `=
    firstname`
    FROM `'. _DB_PREFIX_.'customer`
    
    =20
  2. Back quotes ("`") must be used around SQL field names and table name= s.

    =20
    SELECT p=
    .`foo`, c.`bar`
    FROM `'. _DB_PREFIX_.'product` p, `'. _DB_PREFIX_.'customer` c
    
    =20
  3. Table aliases have to be named by taking the first letter of each wo= rd, and must be lowercase.

    =20
    SELECT p=
    .`id_product`, pl.`name`
    FROM `'. _DB_PREFIX_.'product` p
    NATURAL JOIN `'. _DB_PREFIX_.'product_lang` pl
    
    =20
  4. When conflicts between table aliases occur, the second character has= to be also used in the name.

    =20
    SELECT c=
    a.`id_product`, cu.`firstname`
    FROM `'.DB_PREFIX.'cart` ca, `'. _DB_PREFIX_.'customer` cu
    
    =20
  5. Indentation has to be done for each clause

    =20
    $query =
    =3D 'SELECT pl.`name`
    FROM `'.PS_DBP.'product_lang` pl
    WHERE pl.`id_product` =3D 17';
    
    =20
  6. It is forbidden to make a JOIN in a WHERE clause.

Installing the co= de validator

This is a brief tutorial on how to install a code validator on your PC a= nd 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 specifical= ly for CodeSniffer, using many rules taken from existing standards, with ad= ded customized rules in order to better fit our project.

You can download the PrestaShop code standard using Git: https://github.com/PrestaShop/PrestaShop-norm-val= idator (you must perform this step before going any further with this t= utorial).

Eclipse integration

Quick links:

If you use Eclipse, you can integrate code validation within the text ed= itor 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-codesni= ffer/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 pr= eferences: go to "PHP Tools" and choose the PS standard that you downloaded= earlier (see link above).

If the file does not automatically validate, as it should, you can confi= gure this in the "Preferences" menu, "Validation" option. Otherwise, just r= ight-click on the folder/file in the file-tree, and choose "PHP Tools" in t= he contextual menu (which you can also be set as a shortcut).

Command line (Linux)

You do not have to use Eclipse to use PHP CodeSniffer, you can also inst= all it so that it can be called from the command line.

  1. Install PEAR: http://pear.php.net/
    $> apt-get install p= hp-pear
  2. Install PHP CodeSniffer in PEAR: http://pear.php.= net/package/PHP_CodeSniffer
    $> pear install PHP_CodeSniffe= r
  3. Add the PrestaShop standard that you downloaded from SVN earlier, and p= lace it in PHP CodeSniffer's "Standards" folder.
    $> git clone = https://github.com/PrestaShop/PrestaShop-= norm-validator /usr/share/php/PHP/CodeSniffer/St= andards/Prestashop
  4. Launch PHP CodeSniffer
    $> phpcs --config-set default_stand= ard Prestashop

Using the program

The various options for this command are well explained in its documenta= tion. For now, here is the easy way to launch it:

=20
$> ph=
pcs --standard=3D/path/to/norm/Prestashop /folder/or/fileToCheck
=20

In order to only display errors, not warnings:

=20
$> ph=
pcs --standard=3D/path/to/norm/Prestashop --warning-severity=3D99 /folder/o=
r/fileToCheck
=20

If you have already manually installed PHP CodeSniffer, the program shou= ld be in PEAR's "scripts" folder.

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

=20
path/to/=
php.exe -d auto_apprend_file=3D"" -d auto_prepend_file -d include_path=3D"p=
ath/to/PEAR/" path/to/pear/scripts/phpcs
=20

Integrating the program to Eclipse's console (optional)

  1. Click on the "External tools" button in the icon bar (a green arrow poi= nting at a small red folder).
  2. Click on the "External tools configuration" tab.
  3. 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 --sta= ndard=3DPrestashop.
------=_Part_375793_320101686.1710837601767--