Introduction au Zend Framework

 Apprendre Zend Framework

appendix

 Guide de référence Zend Framework


  •  Zend_Gdata
  •  Zend_Http
  •  Zend_InfoCard
  •  Zend_Json
  •  Zend_Layout
  •  Zend_Ldap
  •  Zend_Loader
  •  Zend_Locale
  •  Zend_Log
  •  Zend_Mail
  •  Zend_Markup
  •  Zend_Measure
  •  Zend_Memory
  •  Zend_Mime
  •  Zend_Navigation
  •  Zend_Oauth
  •  Zend_OpenId
  •  Zend_Paginator
  •  Zend_Pdf
  •  Zend_ProgressBar
  •  Zend_Queue
  •  Zend_Reflection
  •  Zend_Registry
  •  Zend_Rest

  •  Zend_Search_Lucene
  •  Zend_Serializer
  •  Zend_Server
  •  Zend_Service
  •  Zend_Session
  •  Zend_Soap
  •  Zend_Tag
  •  Zend_Test
  •  Zend_Text
  •  Zend_TimeSync
  •  Zend_Tool
  •  Zend_Tool_Framework
  •  Zend_Tool_Project
  •  Zend_Translate
  •  Zend_Uri
  •  Zend_Validate
  •  Zend_Version
  •  Zend_View
  •  Zend_Wildfire
  •  Zend_XmlRpc
  • ZendX_Console_Process_Unix
  • ZendX_JQuery
  • Translation 61.2% Update 2010-11-28 - Revision 23149 - Version ZF 1.11.x

    C.4. Style de codage

    C.4.1. Démarcation du code PHP

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

    <?php

    ?>

    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 Section C.2.1, « Général »).

    C.4.2. Chaînes de caractères

    C.4.2.1. 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 :

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

    C.4.2.2. 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 :

    $sql "SELECT `id`, `name` from `people` "
         
    "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.

    C.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 !";

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

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

    C.4.2.4. 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é :

    $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` = 'Caroline' "
         
    "ORDER BY `name` ASC ";

    C.4.3. Tableaux

    C.4.3.1. 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é :

    $sampleArray = array(123'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 :

    $sampleArray = array(123'Zend''Studio',
                         
    $a$b$c,
                         
    56.44$d500);

    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:

    $sampleArray = array(
        
    123'Zend''Studio',
        
    $a$b$c,
        
    56.44$d500,
    );

    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.

    C.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');

    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.

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

    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.

    C.4.4. Classes

    C.4.4.1. 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.

    class SampleClass extends FooAbstract implements BarInterface
    {
    }

    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.

    class SampleClass
        
    extends FooAbstract
        
    implements BarInterface
    {
    }

    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.

    class SampleClass
        
    implements BarInterface,
                   
    BazInterface
    {
    }

    C.4.4.2. 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).

    C.4.5. Fonctions et méthodes

    C.4.5.1. 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 :

    /*
     * Bloc de documentation
     */
    class Foo
    {
        
    /**
         * Bloc de documentation
         */
        
    public function bar()
        {
            
    // contenu de la fonction
            // qui doit être indenté avec 4 espaces
        
    }
    }

    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:

    /**
     * Documentation Block Here
     */
    class Foo
    {
        
    /**
         * Documentation Block Here
         */
        
    public function bar($arg1$arg2$arg3,
            
    $arg4$arg5$arg6
        
    ) {
            
    // all contents of function
            // must be indented four spaces
        
    }
    }

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

    /**
     * Bloc de documentation
     */
    class Foo
    {
        
    /**
         * Bloc de documentation
         */
        
    public function bar(&amp;$baz)
        {}
    }

    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.

    /**
     * Bloc de documentation
     */
    class Foo
    {
        
    /**
         * INCORRECT
         */
        
    public function bar()
        {
            return(
    $this->bar);
        }

        
    /**
         * CORRECT
         */
        
    public function bar()
        {
            return 
    $this->bar;
        }
    }

    C.4.5.2. 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 :

    threeArguments(123);

    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 :

    threeArguments(array(123), 23);

    threeArguments(array(123'Zend''Studio',
                         
    $a$b$c,
                         
    56.44$d500), 23);

    threeArguments(array(
        
    123'Zend''Studio',
        
    $a$b$c,
        
    56.44$d500
    ), 23);

    C.4.6. Structure de contrôle

    C.4.6.1. 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.

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

    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.

    if (($a == $b)
        &
    amp;&amp; ($b == $c)
        || (
    Foo::CONST == $d)
    ) {
        
    $a $d;
    }

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

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

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

    if ((
    $a == $b)
        &
    amp;&amp; ($b == $c)
        || (
    Foo::CONST == $d)
    ) {
        
    $a $d;
    } elseif ((
    $a != $b)
              || (
    $b != $c)
    ) {
        
    $a $c;
    } else {
        
    $a $b;
    }

    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.

    C.4.6.2. 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.

    switch ($numPeople) {
        case 
    1:
            break;

        case 
    2:
            break;

        default:
            break;
    }

    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".

    C.4.7. Documentation intégrée

    C.4.7.1. 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.

    C.4.7.2. 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 :

    /**
     * Description courte du fichier
     *
     * Description longue du fichier s'il y en a une
     *
     * LICENSE: Informations sur la licence
     *
     * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
     * @license    http://framework.zend.com/license   BSD License
     * @version    $Id:$
     * @link       http://framework.zend.com/package/PackageName
     * @since      File available since Release 1.5.0
    */

    C.4.7.3. Classes

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

    /**
     * Description courte de la classe
     *
     * Description longue de la classe, s'il y en a une
     *
     * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
     * @license    http://framework.zend.com/license   BSD License
     * @version    Release: @package_version@
     * @link       http://framework.zend.com/package/PackageName
     * @since      Class available since Release 1.5.0
     * @deprecated Class deprecated in Release 2.0.0
     */

    C.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 constructions "public", "private", "protected" utilisée pour déclarer la fonction.

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

    @throws exceptionclass [description]

    digg delicious meneame google twitter technorati facebook

    Comments

    Loading...