Page History

...

C'est pourquoi, lorsque vous écrivez du code pour PrestaShop, que ce soit pour un thème, un module ou une modification du coeur du logiciel, vous devez faire en sorte de suivre les indications qui suivent. Elles sont déjà suivies par les développeurs de PrestaShop, et les suivre également est la manière la plus sûr sûre de voir votre code s'intégrer dans PrestaShop de manière élégante.

...

Si vous utilisez un éditeur, vous pouvez utiliser le validateur CodeSniffer pour vous aider à mieux écrire votre code.

PHP

Noms des variables

Tout comme le nom des classes, des méthodes et des fonctions, le nom des variables doit toujours être écrit en anglais, afin d'être compréhensible par le plus grand nombre.

Utilisez des caractères minuscules, et séparez les mots par des caractères soulignés. N'utilisez jamais le format camelCase.

1. Pour les données en provenance de la base de données : $my_var.
2. Pour les algorithmes : $my_var.
3. La visibilité d'une variable membre n'affecte pas son nom : private $my_var.

...

1. "+", "-", "*", "/", "=" et toute combinaison de ces opérateurs (ex. : "/=") doivent avoir une espace avant et après.

   Code Block
   borderStyle solid
   $a + 17; $result = $b / 2; $i += 34;

2. "." doit ne pas avoir d'espace avant ou après.

   Code Block
   borderStyle solid
   echo $a.$b; $c = $d.$this->foo();

   Note
   title Recommandation
   Pour des raisons de performance, n'abusez pas des concaténations.

3. ".=" doit avoir une espace avant et après.

   Code Block
   borderStyle solid
   $a .= 'Debug';

4. Lorsque vous testez une variable booléenne (true/false), n'utilisez pas a un opérateur de comparaison, mais testez directement la valeur elle-même, ou la valeur préfixe d'un point d'exclamation :

   Code Block
   // ne faites pas ceci if ($var == true) // ...ni ceci if ($var == false) // faites ceci if ($var) // ...ou ceci if (!$var)

...

1. Le nom des méthodes et fonctions doivent utiliser la méthode CamelCase : commencer par un caractère en minuscule, chaque mot suivant doit commencer par un caractère en majuscule :

   Code Block
   borderStyle solid
   public function myExampleMethodWithALotOfWordsInItsName()

2. Les accolades qui ouvrent le code d'une méthode doit être précédé précédées d'un retour à la ligne :

   Code Block
   borderStyle solid
   public function myMethod($arg1, $arg2) { ... }

3. Le nom des méthodes et fonctions doit être explicite ; les noms tels que b() ou ef() sont donc à proscrire :

   Info
   title Exceptions
   Les seules exceptions admises sont la fonction de traduction (nommée l()) et et les fonctions de débogage (nommées p() et d()).

...

Les virgules doivent être suivies (et non précédées) d'une un espace :

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

...

1. Le nom des constantes doit être écrit en majuscule, sauf pour true, false et null qui doivent être en minuscule : ENT_NOQUOTE, true.

2. Le nom des constantes doit être préfixé avec "PS_" dans un module ou le coeur de PrestaShop :

   Code Block
   borderStyle solid
   define('PS_DEBUG', 1); define('PS_MODULE_NAME_DEBUG', 1);

3. Le nom des constantes ne doivent doit utiliser que des caractères alphabétiques, ainsi que le signe "_".

...

1. À l'intérieur d'une fonction et d'une méthode, seul le commentaire de type "//" est autorisé.

2. Il doit y avoir une un espace à l'ouverture d'un signe de commentaire "//" :

   Code Block
   borderStyle solid
   // My great comment

3. Le marqueur de commentaire "//" est toléré à la fin d'une ligne de code :

   Code Block
   borderStyle solid
   $a = 17 + 23; // A comment inside my example function

4. En dehors des fonctions et méthodes, seuls les marqueurs "/*" and "*/" sont autorisés :

   Code Block
   borderStyle solid
   /* This method is required for compatibility issues */ public function foo() { // Some code explanation right here ... }

5. Un commentaire phpDoc est requis en ouverture de méthode :

   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 À propos de phpDoc
   Pour plus d'information sur la syntaxe phpDoc : http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.pkg.html.

Valeurs retournées

1. La déclaration return ne nécessaire nécessite pas de parenthèses, sans de sauf dans le cas d'une expression composée :

   Code Block
   borderStyle solid
   return $result; return ($a + $b); return (a() - b()); return true;

2. La déclaration return peut être utilisée pour sortir d'une méthode :

   Code Block
   borderStyle solid
   return;

...

1. Le mot-clé array ne doit pas être suivi d'une un espace :

   Code Block
   borderStyle solid
   array(17, 23, 42);

2. Lorsqu'il y a trop de données dans un tableau, l'indentation doit être comme suit :

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

...

Les accolades sont à éviter lorsqu'elles n'encadrent qu'un une seule instruction ou une combinaison de déclarations :

if (!$result)
	    return false;
 
for ($i = 0; $i < 17; $i++)
	    if ($myArray[$i] == $value)
		    {
        $result[] = $myArray[$i];
	else
		        return $result;
    }
    else
        $failed++;

Sécurité

1. Toutes les données en provenance de l'utilisateur doivent être typées :

   Code Block
   borderStyle solid
   $data = Tools::getValue('name'); $myObject->street_number = (int)Tools::getValue('street_number');

2. Tous les paramètres de méthodes/fonctions doivent être typés (avec Array ou Object) dès récupération :

   Code Block
   borderStyle solid
   public myMethod(Array $var1, $var2, Object $var3)

3. Tous les autres paramètres doivent être typés à chaque utilisation, sauf quand ils sont envoyés à d'autres méthodes/fonctions :

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

...

1. Chaque ligne du code source doit s'arrêter à 120 150 caractères.
2. Les lignes de fonctions/méthodes doivent s'arrêter à 80 caractères. Une fonction doit avoir une bonne raison d'avoir un long nom : ne gardez que l'essentiel !

...

1. Les mots-clés doivent être écrits en majuscule :

   Code Block
   borderStyle solid
   SELECT `firstname` FROM `'._DB_PREFIX_.'customer`

2. Le caractère accent grave ("`") doit encadrer les noms des champs SQL et des tables SQL :

   Code Block
   borderStyle solid
   SELECT p.`foo`, c.`bar` FROM `'._DB_PREFIX_.'product` p, `'._DB_PREFIX_.'customer` c

3. Les alias de table doivent être nommés en prenant la première lettre de chaque mot, le tout en minuscule :

   Code Block
   borderStyle solid
   SELECT p.`id_product`, pl.`name` FROM `'._DB_PREFIX_.'product` p NATURAL JOIN `'._DB_PREFIX_.'product_lang` pl

4. Lorsque d'un conflit survient entre deux alias de tables, le second caractère doit également être ajouté dans le nom :

   Code Block
   borderStyle solid
   SELECT ca.`id_product`, cu.`firstname` FROM `'._DB_PREFIX_.'cart` ca, `'._DB_PREFIX_.'customer` cu

5. L'indentation doit être faite pour chaque clause :

   Code Block
   borderStyle solid
   $query = 'SELECT pl.`name` FROM `'._DB_PREFIX_.'product_lang` pl WHERE pl.`id_product` = 17';

6. Il est interdit de faire un JOIN dans une clause WHERE.

Installation

...

du validateur de code (PHP CodeSniffer)

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 (http://pear.php.net/package/PHP_CodeSniffer/). La norme PrestasShop a été créée pour l'occasion, constituée de nombreuses règles reprises des normes déjà existantsexistantes, plus un certain nombre de règles personnalisées pour coller davantage au projet.

La norme PrestaShop est disponible via SVN Git ici : httphttps://devgithub.prestashop.com/svn/v1/branches/normPrestaShop/PrestaShop-norm-validator (cette étape est obligatoire pour la suite).

...

1. Aller dans Settings -> Inspection -> PHP -> PHP Code Sniffer ;
2. Choisir le chemin vers l'exécutable phpcs , ;
3. Choisir le coding standard "PrestaShop" (disponible uniquement si vous l'avez bien placé dans le dossier des standards de CodeSniffer).

Intégration à Eclipse

Documentation officielle, en anglais :

• Official installation guide: http://www.phpsrc.org/projects/pti/wiki/Installation
• Official configuration guide: http://www.phpsrc.org/projects/pti-php-codesniffer/wiki/Configuration

Si vous utilisez Eclipse (http://www.eclipse.org/), vous pouvez faire en sorte que la validation de norme s'intègre directement à l'éditeur à l'aide d'un plugin, dont l'installation (très simple) est décrite sur cette page : http://www.phpsrc.org/projects/pti/wiki/Installation.

Pour configurer le plugin, tout est expliqué sur cette page (encore une fois très simple) : http://www.phpsrc.org/projects/pti-php-codesniffer/wiki/Configuration (dans la liste des packages disponibles, choisissez seulement PHP CodeSniffer et PEAR si vous ne l'avez pas déjà).

Il vous faudra ajouter la norme PrestaShop dans les préférences d'Eclipse : allez dans PHP Tools et choisissez le standard PrestaShop récupéré du SVN (lien plus haut).

Intégrer l'exécutable à la console d'Eclipse (facultatif)

1. Cliquer sur le bouton "external tools" dans la barre des icônes (une flèche verte avec un petit dossier rouge)
2. Cliquer sur l'onglet external tools configuration
3. Double cliquer sur "Program" pour créer une configuration
   1. "Location" : chemin vers l'executable phpcs, ou phpcs.bat sous Windows
   2. "Arguments" : les arguments de la ligne de commande, par exemple --standard=Prestashop ${selected_resource_loc}

1. /Standards de CodeSniffer).

Intégration à vim

Plusieurs plugins existent sur le net. Par exemple, vous pouvez utiliser celui-ci : https://github.com/bpearson/vim-phpcs/blob/master/plugin/phpcs.vim
Placez-le dans votre dossier ~/.vim/plugin .

Vous pouvez rajouter deux raccourcis (par exemple, F9 pour tout afficher et Ctrl+F9 pour masquer les warnings) dans votre fichier .vimrc en mode normal et insertion:

nmap <C-F9> :CodeSniffErrorOnly<CR>
imap <C-F9> <Esc>:CodeSniffErrorOnly<CR>
nmap <F9> 			:CodeSniff<CR>
imap <F9> <Esc>:CodeSniff<CR>a

...

Vous n'êtes pas obligé d'utiliser PhpStorm ou Eclipse pour profiter de la norme. Vous pouvez également installer PHP CodeSniffer afin de l'appeler en ligne de commande :

1. Installez PEAR : http://pear.php.net/
   $> apt-get install php-pear
2. Installez PHP CodeSniffer dans PEAR : http://pear.php.net/package/PHP_CodeSniffer
   $> pear install PHP_CodeSniffer
3. Ajoutez la norme PrestaShop que vous avez téléchargez du SVN, et placez-la dans le dossier /Standards de CodeSniffer
   $> svn co http://svn.prestashop.com/branches/norm/ /usr/share/php/PHP/CodeSniffer/Standards/Prestashop
4. Configurez Prestashop comme étant la norme de base
   $> phpcs --config-set default_standard Prestashop

...