Style de codage

Démarcation du code PHP

Les codes PHP doivent toujours être délimités dans la forme complète, par les balises PHP standards :

  1. <?php
  2.  
  3. ?>

Les balises courtes d'ouvertures ("<?")ne sont pas autorisées. Pour les fichiers ne contenant que du code PHP, la balise de fermeture doit toujours être omise (Voir Général).

Chaînes de caractères

Chaînes littérales

Lorsqu'une chaîne est littérale (c'est-à-dire qu'elle ne contient pas de substitution de variables), l'apostrophe ou guillemet simple doit être utilisé pour démarquer la chaîne :

  1. $a = 'Exemple de chaîne de caractères';

Chaînes de caractères littérales avec apostrophes

Lorsque qu'une chaîne littérale contient des apostrophes, il est permis de les démarquer en utilisant les guillemets doubles. Ceci est particulièrement conseillé pour les requêtes SQL :

  1. $sql = "SELECT `id`, `name` from `people` "
  2.      . "WHERE `name`='Eric' OR `name`='Caroline'";
La syntaxe ci-dessus est préférée à l'échappement des apostrophes car elle est plus facile à lire.

Substitution de variables

La substitution des variables est permise en utilisant une de ces deux formes :

  1. $greeting = "Bonjour $name, bienvenue !";
  2.  
  3. $greeting = "Bonjour {$name}, bienvenue !";

Pour des raisons d'uniformité, cette forme n'est pas permise :

  1. $greeting = "Bonjour ${name}, bienvenue !";

Concaténation de chaînes

Les chaînes peuvent êtres concaténées en utilisant l'opérateur ".". Un espace doit toujours être ajouté avant, et après cet opérateur, cela permet d'améliorer la lisibilité :

  1. $company = 'Zend' . ' ' . 'Technologies';

Lors de la concaténation de chaînes avec l'opérateur ".", il est permis de couper le segment en plusieurs lignes pour améliorer la lisibilité. Dans ces cas, chaque nouvelle ligne doit être remplie avec des espaces, de façon à aligner le "." sous l'opérateur "=" :

  1. $sql = "SELECT `id`, `name` FROM `people` "
  2.      . "WHERE `name` = 'Caroline' "
  3.      . "ORDER BY `name` ASC ";

Tableaux

Tableaux indexés numériquement

L'utilisation d'indices négatifs n'est pas permise.

Un tableau indexé peut commencer avec n'importe quel nombre positif, cependant cette méthode est déconseillée. Il est conseillé de commencer l'indexation à 0.

Lors de la déclaration de tableaux indexés avec la construction array, un espace doit être ajouté après chaque virgule délimitante, pour améliorer la lisibilité :

  1. $sampleArray = array(1, 2, 3, 'Zend', 'Studio');

Il est aussi permis de déclarer des tableaux indexés sur plusieurs lignes en utilisant la construction array. Dans ce cas, chaque nouvelle ligne doit être remplie par des espaces jusqu'à ce que cette ligne s'aligne, comme il est montré dans l'exemple suivant :

  1. $sampleArray = array(1, 2, 3, 'Zend', 'Studio',
  2.                      $a, $b, $c,
  3.                      56.44, $d, 500);

Alternately, the initial array item may begin on the following line. If so, it should be padded at one indentation level greater than the line containing the array declaration, and all successive lines should have the same indentation; the closing paren should be on a line by itself at the same indentation level as the line containing the array declaration:

  1. $sampleArray = array(
  2.     1, 2, 3, 'Zend', 'Studio',
  3.     $a, $b, $c,
  4.     56.44, $d, 500,
  5. );

When using this latter declaration, we encourage using a trailing comma for the last item in the array; this minimizes the impact of adding new items on successive lines, and helps to ensure no parse errors occur due to a missing comma.

Tableaux associatifs

Lorsque de la déclaration de tableaux associatifs avec la construction array, il est conseillé de séparer la définition sur plusieurs lignes. Dans ce cas, chaque ligne successive doit être remplie par des espaces pour que les clés et les valeurs soient alignées :

$sampleArray = array('firstKey'  => 'firstValue',
                     'secondKey' => 'secondValue');

Alternately, the initial array item may begin on the following line. If so, it should be padded at one indentation level greater than the line containing the array declaration, and all successive lines should have the same indentation; the closing paren should be on a line by itself at the same indentation level as the line containing the array declaration. For readability, the various "=>" assignment operators should be padded such that they align.

  1. $sampleArray = array(
  2.     'firstKey'  => 'firstValue',
  3.     'secondKey' => 'secondValue',
  4. );

When using this latter declaration, we encourage using a trailing comma for the last item in the array; this minimizes the impact of adding new items on successive lines, and helps to ensure no parse errors occur due to a missing comma.

Classes

Déclaration de classes

Les classes doivent être nommées conformément aux conventions de nommage de Zend Framework.

L'accolade est toujours écrite dans la ligne sous le nom de la classe.

Toutes les classes doivent avoir un bloc de documentation conforme aux standards PHPDocumentor.

Tout code d'une classe doit être indenté avec 4 espaces.

Une seule classe est permise par fichier PHP.

Le placement de code additionnel dans un fichier de classe est permis, mais déconseillé. Dans ces fichiers, deux lignes vides doivent séparer la classe du code PHP additionnel.

Voici un exemple d'une déclaration de classe autorisée :

/**
 * Bloc de documentation
 */
class SampleClass
{
    // contenu de la classe
    // qui doit être indenté avec 4 espaces
}

Classes that extend other classes or which implement interfaces should declare their dependencies on the same line when possible.

  1. class SampleClass extends FooAbstract implements BarInterface
  2. {
  3. }

If as a result of such declarations, the line length exceeds the maximum line length, break the line before the "extends" and/or "implements" keywords, and pad those lines by one indentation level.

  1. class SampleClass
  2.     extends FooAbstract
  3.     implements BarInterface
  4. {
  5. }

If the class implements multiple interfaces and the declaration exceeds the maximum line length, break after each comma separating the interfaces, and indent the interface names such that they align.

  1. class SampleClass
  2.     implements BarInterface,
  3.                BazInterface
  4. {
  5. }

Variables membres de la classe

Les variables membres doivent être nommées en respectant les conventions de nommage de Zend Framework.

Toute variable déclarée dans une classe doit être listée en haut de cette classe, avant toute déclaration de méthode.

La construction var n'est pas permise. Les variables membres déclarent toujours leur visibilité en utilisant la construction private, protected, ou public. L'accès direct à ces variables membres en les rendant publiques est permis mais déconseillé. Il est préférable d'utiliser des accesseurs (set/get).

Fonctions et méthodes

Déclaration de fonctions et de méthodes

Les fonctions doivent être nommées en respectant les conventions de nommage de Zend Framework.

Les fonctions internes aux classes doivent toujours déclarer leur visibilité en utilisant la construction private, protected, ou public.

Tout comme les classes, l'accolade ouvrante est toujours écrite sous le nom de la fonction. Il n'y a pas d'espace entre le nom de la fonction et les parenthèses des arguments. Il n'y a pas d'espace entre la parenthèse fermante et l'accolade.

Les fonctions globales sont fortement déconseillées.

Voici un exemple d'une déclaration permise d'une fonction de classe :

  1. /*
  2. * Bloc de documentation
  3. */
  4. class Foo
  5. {
  6.     /**
  7.      * Bloc de documentation
  8.      */
  9.     public function bar()
  10.     {
  11.         // contenu de la fonction
  12.         // qui doit être indenté avec 4 espaces
  13.     }
  14. }

In cases where the argument list exceeds the maximum line length, you may introduce line breaks. Additional arguments to the function or method must be indented one additional level beyond the function or method declaration. A line break should then occur before the closing argument paren, which should then be placed on the same line as the opening brace of the function or method with one space separating the two, and at the same indentation level as the function or method declaration. The following is an example of one such situation:

  1. /**
  2. * Documentation Block Here
  3. */
  4. class Foo
  5. {
  6.     /**
  7.      * Documentation Block Here
  8.      */
  9.     public function bar($arg1, $arg2, $arg3,
  10.         $arg4, $arg5, $arg6
  11.     ) {
  12.         // all contents of function
  13.         // must be indented four spaces
  14.     }
  15. }

Le passage par référence est permis uniquement dans la déclaration de la fonction :

  1. /**
  2. * Bloc de documentation
  3. */
  4. class Foo
  5. {
  6.     /**
  7.      * Bloc de documentation
  8.      */
  9.     public function bar(&$baz)
  10.     {}
  11. }

L'appel par référence est interdit.

La valeur de retour ne doit pas être entourée de parenthèses. Ceci peut gêner à la lecture et peut aussi casser le code si une méthode est modifiée plus tard pour retourner par référence.

  1. /**
  2. * Bloc de documentation
  3. */
  4. class Foo
  5. {
  6.     /**
  7.      * INCORRECT
  8.      */
  9.     public function bar()
  10.     {
  11.         return($this->bar);
  12.     }
  13.  
  14.     /**
  15.      * CORRECT
  16.      */
  17.     public function bar()
  18.     {
  19.         return $this->bar;
  20.     }
  21. }

Usage de fonctions et méthodes

Les arguments d'une fonction sont séparés par un espace après la virgule de délimitation. Voici un exemple d'un appel de fonction qui prend trois arguments :

  1. threeArguments(1, 2, 3);

L'appel par référence est interdit. Référez vous à la section sur la déclaration de fonctions pour la méthode correcte de passage des argument par référence.

Pour les fonctions dont les arguments peuvent être des tableaux, l'appel à la fonction doit inclure la construction "array" et peut être divisé en plusieurs ligne pour améliorer la lecture. Dans ces cas, les standards d'écriture de tableaux s'appliquent aussi :

  1. threeArguments(array(1, 2, 3), 2, 3);
  2.  
  3. threeArguments(array(1, 2, 3, 'Zend', 'Studio',
  4.                      $a, $b, $c,
  5.                      56.44, $d, 500), 2, 3);
  6.  
  7. threeArguments(array(
  8.     1, 2, 3, 'Zend', 'Studio',
  9.     $a, $b, $c,
  10.     56.44, $d, 500
  11. ), 2, 3);

Structure de contrôle

If / Else / Elseif

Les structure de contrôles basées sur les constructions if et elseif doivent avoir un seul espace avant la parenthèse ouvrante de la condition, et un seul espace après la parenthèse fermante.

Pour la condition entre les parenthèses, les opérateurs doivent être séparés par des espaces pour une meilleure lisibilité. Les parenthèses internes sont conseillées pour améliorer le regroupement logique de longues conditions.

L'accolade ouvrante est écrite sur la même ligne que la condition. L'accolade fermante est toujours écrite sur sa propre ligne. Tout contenu présent à l'intérieur des accolades doit être indenté par 4 espaces.

  1. if ($a != 2) {
  2.     $a = 2;
  3. }

If the conditional statement causes the line length to exceed the maximum line length and has several clauses, you may break the conditional into multiple lines. In such a case, break the line prior to a logic operator, and pad the line such that it aligns under the first character of the conditional clause. The closing paren in the conditional will then be placed on a line with the opening brace, with one space separating the two, at an indentation level equivalent to the opening control statement.

  1. if (($a == $b)
  2.     && ($b == $c)
  3.     || (Foo::CONST == $d)
  4. ) {
  5.     $a = $d;
  6. }

The intention of this latter declaration format is to prevent issues when adding or removing clauses from the conditional during later revisions.

Pour les instruction "if" qui incluent "elseif" ou "else", les conventions de formatage sont similaires à celles de la construction "if". Les exemples suivants montrent le formatage approprié pour les structures "if" avec "else" et/ou les constructions "elseif" :

  1. if ($a != 2) {
  2.     $a = 2;
  3. } else {
  4.     $a = 7;
  5. }
  6.  
  7. if ($a != 2) {
  8.     $a = 2;
  9. } elseif ($a == 3) {
  10.     $a = 4;
  11. } else {
  12.     $a = 7;
  13. }
  14.  
  15. if (($a == $b)
  16.     && ($b == $c)
  17.     || (Foo::CONST == $d)
  18. ) {
  19.     $a = $d;
  20. } elseif (($a != $b)
  21.           || ($b != $c)
  22. ) {
  23.     $a = $c;
  24. } else {
  25.     $a = $b;
  26. }
PHP permet que ces instructions soient écrites sans accolades dans certaines circonstances. La convention de codage ne fait pas de différentiation et toutes les instructions "if", "elseif" et "else" doivent utiliser des accolades.

Switch

Les instructions de contrôle avec "switch" ne doivent avoir qu'un seul espace avant la parenthèse ouvrante de l'instruction conditionnelle, et aussi un seul espace après la parenthèse fermante.

Tout le contenu à l'intérieur de l'instruction "switch" doit être indenté avec 4 espaces. Le contenu sous chaque "case" doit être indenté avec encore 4 espaces supplémentaires.

  1. switch ($numPeople) {
  2.     case 1:
  3.         break;
  4.  
  5.     case 2:
  6.         break;
  7.  
  8.     default:
  9.         break;
  10. }

La construction default ne doit jamais être oubliée dans une instruction switch.

NOTE : Il est parfois pratique d'écrire une clause case qui passe à travers le case suivant en omettant l'inclusion de break ou return. Pour distinguer ce cas d'un bug, toute clause case ne contenant pas break ou return doit contenir le commentaire "// break intentionally omitted".

Documentation intégrée

Format de la documentation

Tous les blocs de documentation ("docblocks") doivent être compatible avec le format phpDocumentor. La description du format phpDocumentor n'est pas du ressort de ce document. Pour plus d'information, visitez » http://phpdoc.org/

Tous les fichiers de code source écrits pour Zend Framework ou qui opèrent avec ce framework doivent contenir un docblock du fichier, en haut de chaque fichier, et un docblock de classe immédiatement au dessus de chaque classe. Ci-dessous vous trouverez des exemples de tels docblocs.

Fichiers

Chaque fichier qui contient du code PHP doit avoir un bloc d'entête en haut du fichier qui contient au minimum ces balises phpDocumentor :

  1. /**
  2. * Description courte du fichier
  3. *
  4. * Description longue du fichier s'il y en a une
  5. *
  6. * LICENSE: Informations sur la licence
  7. *
  8. * @copyright  Copyright (c) 2005-2014 Zend Technologies USA Inc. (http://www.zend.com)
  9. * @license    http://framework.zend.com/license   BSD License
  10. * @version    $Id:$
  11. * @link       http://framework.zend.com/package/PackageName
  12. * @since      File available since Release 1.5.0
  13. */

Classes

Chaque classe doit avoir un docblock qui contient au minimum ces balises phpDocumentor :

  1. /**
  2. * Description courte de la classe
  3. *
  4. * Description longue de la classe, s'il y en a une
  5. *
  6. * @copyright  Copyright (c) 2005-2014 Zend Technologies USA Inc. (http://www.zend.com)
  7. * @license    http://framework.zend.com/license   BSD License
  8. * @version    Release: @package_version@
  9. * @link       http://framework.zend.com/package/PackageName
  10. * @since      Class available since Release 1.5.0
  11. * @deprecated Class deprecated in Release 2.0.0
  12. */

Fonctions

Chaque fonction, méthode, doit avoir un docblock contenant au minimum :

  • Une description de la fonction

  • Tous les arguments

  • Toutes les valeurs de retour possibles

Il n'est pas nécessaire d'utiliser la balise "@access" parce que le niveau d'accès est déjà connu avec les constructions "public", "private", "protected" utilisée pour déclarer la fonction.

Si une fonction/méthode peut lancer une exception, utilisez "@throws" :

  1. @throws exceptionclass [description]
blog comments powered by Disqus