A.4. Style de codage
Précédent | Annexe A. Convention de codage PHP du Framework Zend | Suivant

## A.4. Style de codage

### A.4.1. Démarcation du code PHP

Les code PHP doit toujours être délimité par la form complète, les balise PHP standards :

    <?php

    ?>

Les balises courtes d'ouvertures ne sont pas autorisées.

### A.4.2. Chaînes de caractères

#### A.4.2.1. Chaînes litérrales

Lorsqu'une chaîne est litérrale (i.e elle ne contient pas de substitution de variables), l'apostrophe ou guillemet simple doit être utilisé pour démarquer la chaîne :

    $a = 'Example String';

#### A.4.2.2. Chaînes de caractères litérrales avec apostrophes

Lorsque qu'une chaîne litérrale 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 :

    $sql = "SELECT `id`, `name` from `people` WHERE `name`='Fred' OR `name`='Susan'";

La syntaxe ci-dessus est préférée à l'échappment des aspostrophes.

#### A.4.2.3. Substitution de variables

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

    $greeting = "Bonjour $name, bienvenue!";

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

    // Cette forme n'est pas permise :

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

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

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

#### A.4.2.4. Concatenation 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é:

    $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 "=" :

    $sql = "SELECT `id`, `name` FROM `people` "
         . "WHERE `name` = 'Susan' "
         . "ORDER BY `name` ASC ";

### A.4.3. Tableaux

#### A.4.3.1. Tableaux indexés numériquement

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

Un tableau indexé doit commencer avec n'importe quel nombre positifs, 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é :

    $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 ci-dessous :

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

#### A.4.3.2. 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');

### A.4.4. Classes

#### A.4.4.1. Declaration de classes

Les classes doivent être nommées conformément aux convetions suivantes.

L'accolade est toujours écrite dans la ligne sous le nom de la classe (forme "one true brace").

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

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

Une seule classe par fichier PHP.

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

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
    }

#### A.4.4.2. Variables membres de la classe

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

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

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

### A.4.5. Fonctions et méthodes

#### A.4.5.1. Déclaration de fonction et de méthodes

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

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 (form "one true brace"). 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 :

    /*
     * Bloc de documentation
     */
    function sampleMethod($a)
    {
        // contenu de la fonction
        // qui doit être indenté avec 4 espaces
    }

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

    function sampleMethod(&$a)
    {}

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.

    function foo()
    {
        // INCORRECT
        return($this->bar);

        // CORRECT
        return $this->bar;
    }

#### A.4.5.2. Usage de fonctions et méthodes

Les argument 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 :

    threeArguments(1, 2, 3);

L'appel par référence st interdit. Référez vous à la section sur la déclaration de fonctions pour la méthode correcte de passer 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 :

    threeArguments(array(1, 2, 3), 2, 3);

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

### A.4.6. Structure de contrôle

#### A.4.6.1. If / Else / Elseif

Les structure de contrôles basée sur les construction `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 fermant est toujours écrite sur sa propre ligne. Tout contenu présent à l'intérieur des accolades doit être indenté par 4 espaces.

    if ($a != 2) {
        $a = 2;
    }

Pour les instruction "if" qui incluent "elseif" ou "else", le formattage doit être comme le montre ces exemples :

    if ($a != 2) {
        $a = 2;
    } else {
       $a = 7;
    }

    if ($a != 2) {
        $a = 2;
    } elseif ($a == 3) {
       $a = 4;
    } else {
       $a = 7;
    }

PHP permet que ces instruction soient écrites sans accolades dans certaines circonstances. La convention de codage ne fait pas de différentiation et toute les instructions "if", "elseif" et "else" doivent utiliser des accolades.

L'utilisation de la construction "elseif" est permise mais fortement déconseillée au profit de la combinaison "else if".

#### A.4.6.2. Switch

Les instructions de contrôle avec "switch" ne doivent avoir qu'un seul espace avant ma parenthèse ouvrante de l'instruction conditionnelle, et aussi un seule 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.

    switch ($numPeople) {
        case 1:
            break;

        case 2:
            break;

        default:
            break;
    }

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

NOTE: It is sometimes useful to write a `case` statement which falls through to the next case by not including a `break` or `return` in that case. To distinguish these cases from bugs, any `case` statement where `break` or `return` are omitted must contain the comment "// break intentionally omitted".

### A.4.7. Documentation

#### A.4.7.1. Format de la documentation

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

Tout le fichier de code source écrit pour le Framework Zend ou qui opère avec ce framework doit conteni un docblock du fichier, en haut de chaque fichier, et un docblock de classe immédiatement au dessus de chaque classe. Voici des exemples de tels docblocs :

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

    /**
     * Description courte du fichier
     *
     * Description longue du fichier s'il y en a une
     *
     * LICENSE: Informations sur la licence
     *
     * @copyright  2005 Zend Technologies
     * @license    http://www.zend.com/license/3_0.txt   PHP License 3.0
     * @version    CVS: $Id:$
     * @link       http://dev.zend.com/package/PackageName
     * @since      File available since Release 1.2.0
    */

#### A.4.7.3. Classes

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

    /**
     * Description courte de la classe
     *
     * Description longue de la classe, s'il y en a une
     *
     * @copyright  2005 Zend Technologies
     * @license    http://www.zend.com/license/3_0.txt   PHP License 3.0
     * @version    Release: @package_version@
     * @link       http://dev.zend.com/package/PackageName
     * @since      Class available since Release 1.2.0
     * @deprecated Class deprecated in Release 2.0.0
     */

#### A.4.7.4. 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 constrution "public", "private", "protected" utilisée pour déclarer la fonction.

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

    @throws exceptionclass [description]

Précédent | Niveau supérieur | Suivant
A.3. Conventions de nommage | Sommaire | Annexe B. Informations de copyright