Normes de codes¶

Opérateurs ternaires¶

Les opérateurs ternaires sont permis quand l’opération entière rentre sur une ligne. Les opérateurs ternaires plus longs doivent être séparés en expression if else. Les opérateurs ternaires ne doivent pas être imbriqués. Des parenthèses optionnelles peuvent être utilisées autour de la condition vérifiée de l’opération pour rendre le code plus clair:

// Bien, simple et lisible
$variable = isset($options['variable']) ? $options['variable'] : true;

// Imbriquations des ternaires est mauvaise
$variable = isset($options['variable']) ? isset($options['othervar']) ? true : false : false;

Fichiers de Vue¶

Dans les fichiers de vue (fichiers .ctp) les développeurs devront utiliser les structures de contrôle en mot (keyword control structures). Les structures de contrôle en mot sont plus faciles à lire dans des fichiers de vue complexes. Les structures de contrôle peuvent soit être contenues dans un block PHP plus large, soit dans des balises PHP séparés:

<?php
if ($isAdmin):
    echo '<p>You are the admin user.</p>';
endif;
?>
<p>The following is also acceptable:</p>
<?php if ($isAdmin): ?>
    <p>You are the admin user.</p>
<?php endif; ?>

Nous autorisons les balises PHP fermantes (?>) à la fin des fichiers .ctp.

Typehinting¶

Les arguments qui attendent des objets ou des tableaux peuvent être typés:

/**
 * Some method description.
 *
 * @param Model $Model Le model à utiliser.
 * @param array $array Une valeur de tableau.
 * @param bool $boolean Une valeur boléenne.
 */
public function foo(Model $Model, array $array, $boolean) {
}

Ici $Model doit être une instance de Model et $array doit être un array.

Notez que si vous souhaitez autoriser que $array soit aussi une instance de ArrayObject, vous ne devez pas typer puisque array accepte seulement le type primitif:

/**
 * Description de la method.
 *
 * @param array|ArrayObject $array Some array value.
 */
public function foo($array) {
}

Chaînage des Méthodes¶

Le chaînage des méthodes doit avoir plusieurs méthodes réparties sur des lignes distinctes et indentées avec une tabulation:

$email->from('[email protected]')
    ->to('[email protected]')
    ->subject('Un super message')
    ->send();

DocBlock d’Entête de Fichier¶

Tous les fichier PHP doivent contenir un DocBlock d’en-tête, qui doit ressembler à cela:

<?php
/**
* CakePHP(tm) : Rapid Development Framework (https://cakephp.org)
* Copyright (c) Cake Software Foundation, Inc. (https://cakefoundation.org)
*
* Licensed under The MIT License
* For full copyright and license information, please see the LICENSE.txt
* Redistributions of files must retain the above copyright notice.
*
* @copyright     Copyright (c) Cake Software Foundation, Inc. (https://cakefoundation.org)
* @link          https://cakephp.org CakePHP(tm) Project
* @since         X.Y.Z
* @license       https://www.opensource.org/licenses/mit-license.php MIT License
*/

les tags phpDocumentor à inclure sont:

• @copyright

• @link

• @since

• @license

DocBlocks de Classe¶

Les DocBlocks de classe doivent ressembler à ceci:

/**
 * Short description of the class.
 *
 * Long description of class.
 * Can use multiple lines.
 *
 * @deprecated 3.0.0 Deprecated in 2.6.0. Will be removed in 3.0.0. Use Bar instead.
 * @see Bar
 * @link https://book.cakephp.org/2.0/en/foo.html
 */
class Foo {

}

Les classes DocBlocks peuvent contenir les tags de phpDocumentor suivants:

• @deprecated Utiliser le format @version <vector> <description>, où version et description sont obligatoires.

• @internal

• @link

• @property

• @see

• @since

• @uses

DocBlocks des Attributs¶

Les DocBlocks des attributs doivent ressembler à cela:

/**
 * @var string|null Description of property.
 *
 * @deprecated 3.0.0 Deprecated as of 2.5.0. Will be removed in 3.0.0. Use $_bla instead.
 * @see Bar::$_bla
 * @link https://book.cakephp.org/2.0/en/foo.html#properties
 */
protected $_bar = null;

Les DocBlocks des attributs peuvent contenir les tags phpDocumentor suivants:

• @deprecated en utilisant le format @version <vector> <description>, où version et description sont obligatoires.

• @internal

• @link

• @see

• @since

• @var

DocBlocks des Méthodes/Fonctions¶

Les DocBlocks de méthode ou de fonctions doivent ressembler à ceci:

/**
 * Short description of the method.
 *
 * Long description of method.
 * Can use multiple lines.
 *
 * @param string $param2 first parameter.
 * @param array|null $param2 Second parameter.
 * @return array An array of cakes.
 * @throws Exception If something goes wrong.
 *
 * @link https://book.cakephp.org/2.0/en/foo.html#bar
 * @deprecated 3.0.0 Deprecated as of 2.5.0. Will be removed in 3.0.0. Use Bar::baz instead.
 * @see Bar::baz
 */
 public function bar($param1, $param2 = null) {
 }

Les DocBlocks des méthodes/fonctions peuvent contenir les tags phpDocumentor suivants:

• @deprecated en utilisant le format @version <vector> <description>, où version et description sont obligatoires.

• @internal

• @link

• @param

• @return

• @throws

• @see

• @since

• @uses

Types de Variables¶

Les types de variables pour l’utilisation dans DocBlocks:

Type

Description

mixed

Une variable avec un type indéfini (ou multiple).

int

Variable de type Integer (Tout nombre).

float

Type Float (nombres à virgule).

bool

Type Logique (true ou false).

string

Type String (toutes les valeurs en «  «  ou “ “).

null

Type null. Habituellement utilisé avec un autre type.

array

Type Tableau.

object

Type Objet.

resource

Type Ressource (retourné par exemple par mysql_connect()). Rappelez vous que quand vous spécifiez un type en mixed, vous devez indiquer si il est inconnu, ou les types possibles.

callable

Function appelable.

Vous pouvez aussi combiner les types en utilisant le caractère pipe:

int|bool

Pour plus de deux types, il est habituellement mieux d’utiliser seulement mixed.

Quand vous retournez l’objet lui-même, par ex pour chaîner, vous devriez utilisez $this à la place:

/**
 * Foo function.
 *
 * @return $this
 */
public function foo() {
    return $this;
}

Fonctions¶

Ecrivez toutes les fonctions en camelBack:

function nomDeFonctionLongue() {
}

Classes¶

Les noms de classe doivent être écrites en CamelCase, par exemple:

class ClasseExemple {
}

Variables¶

Les noms de variable doivent être aussi descriptifs que possible, mais aussi courts que possible. Tous les noms de variables doivent démarrer avec une lettre minuscule, et doivent être écrites en camelBack si il y a plusieurs mots. Les variables contenant des objets doivent d’une certaine manière être associées à la classe d’où elles proviennent. Exemple:

$user = 'John';
$users = array('John', 'Hans', 'Arne');

$dispatcher = new Dispatcher();

Visibilité des Membres¶

Utilisez les mots-clés private et protected de PHP5 pour les méthodes et variables. De plus les noms des méthodes et variables protégées commencent avec un underscore simple (_). Exemple:

class A {
    protected $_jeSuisUneVariableProtegee;

    protected function _jeSuisUnemethodeProtegee() {
       /*...*/
    }
}

Les noms de méthodes et variables privées commencent avec un underscore double (__). Exemple:

class A {
    private $__iAmAPrivateVariable;

    private function __iAmAPrivateMethod() {
        /*...*/
    }
}

Essayez cependant d’éviter les méthodes et variables privées et privilégiez plutôt les variables protégées. Ainsi elles pourront être accessible ou modifié par les sous-classes, alors que celles privées empêchent l’extension ou leur réutilisation. La visibilité privée rend aussi le test beaucoup plus difficile.

Exemple d’Adresses¶

Pour tous les exemples d’URL et d’adresse email, utilisez « example.com », « example.org » et « example.net », par exemple:

• Email: someone@example.com

• WWW: http://www.example.com

• FTP: ftp://ftp.example.com

Le nom de domaine « example.com » est réservé à cela (voir RFC 2606) et est recommandé pour l’utilisation dans la documentation ou comme exemples.

Fichiers¶

Les noms de fichier qui ne contiennent pas de classes, doivent être écrits en minuscules et soulignés, par exemple:

nom_de_fichier_long.php

Casting¶

Pour le casting, nous utilisons:

Type

Description

(bool)

Cast pour boolean.

(int)

Cast pour integer.

(float)

Cast pour float.

(string)

Cast pour string.

(array)

Cast pour array.

(object)

Cast pour object.

Constantes¶

Les constantes doivent être définies en majuscules:

define('CONSTANTE', 1);

Si un nom de constante a plusieurs mots, ils doivent être séparés par un caractère underscore, par exemple:

define('NOM_LONG_DE_CONSTANTE', 2);