28.439 étudiants et anciens de l'X sur le web

Conventions

Organisation des fichiers

Extensions

fichiers PHP : .php
fichiers PHP inclus, ne constituant pas des pages autonomes : .inc.php
fichiers de configuration de smarty : .conf
fichiers de template pour smarty : .tpl

Arborescence

répertoire	contenu
cache	contient le cache de smarty, il doit être apache-writeable.
configs	contient les fichiers de configuration en .conf pour smarty. IL NE FAUT PAS Y METTRE DE .php
include	contient les fichiers .inc.php inclus depuis les pages
install.d	contient les fichiers nécessaires à l'installation du module (dump MySQL, fichier config.lemodule.inc.php)
htdocs	les pages du site directement visibles depuis le net. NE PAS Y METTRE DE FICHIERS D'INCLUDE !
plugins	répertoire de plugins pour smarty
scripts	tous les scripts connexes au site (crons, serveur xml-rpc de mailman, scripts de migration, etc ...)
templates	tous les templates du site
templates_c	contient le cache de compilation des templates pour smarty, il doit être apache-writeable.

Caractères de fin de ligne

Les systèmes Unix et Windows n'utilisent pas les mêmes caractères de fin de ligne. Windows utilise des paires \r\n alors que sous Unix une fin de ligne est repérée par le caractère \n. Fort heureusement, svn connaît cette différence et lorsqu'on effectue un checkout on récupère les fichiers avec les bons caractères de fin de ligne. Ceci impose cependant de commiter uniquement des fichiers dans le format de son système d'exploitation ! En particulier lors de l'import svn depuis une machine Unix de fichiers Windows (typiquement lorsqu'on a récupéré un .zip), penser à utiliser la commande dos2unix sur les fichiers. (TODO : et git ?)

Coding Rules HTML et templates

les tabulations doivent être proscrites, et s'il y en a par malheur, elles doivent être de longueur 8. Ceci correspond à la configuration vim vim:set et ts=8:
les lignes doivent être indentées avec des espaces, 2 par niveau (vim:set sts=2 sw=2:)
les attributs HTML doivent être quotés par des ' ou des " ; et si cet attribut est construit à partir de variables de templates, il faut que " soit utilisé et non '

Notons qu'avec vim, il est très facile de configurer les indentations et tabulations en rajoutant la modeline suivante à la fin de tous les fichiers de templates :

{* vim:set et sw=2 sts=2 ts=8: *}

Coding Rules PHP

Elles sont très largement inspirées des coding rules PEAR qui sont raisonables.

Indentation

Indentation de 4 espaces, sans tabulations, ce qui correspond à la modeline vim suivante, à rajouter à la fin du fichier, avant le dernier ?> :

/* vim:set et sw=4 sts=4 ts=4: */

Déclarations de fonctions et de classes

Il faut utiliser la convention "one true brace" (passer la première accolade à la ligne).
Les arguments avec des valeurs par défaut doivent être en dernier dans la liste des arguments.
Penser à retourner une valeur à chaque fois que ça a du sens, sinon true.

<?php
class fooClass
{
    function fooFunction($arg1, $arg2 = '')
    {
        if (condition) {
            statement;
        }
        return 42;
    }
}
?>

CamelCase vs underscore

CamelCase sur les noms de classe
javaCase sur les méthodes (et membres et variables)
UPER_CASE sur les constantes
function_name sur les fonctions (ie les fonctions qui ne sont pas méthodes de classes)
$my_var pour les variables

Appels de fonctions

Les fonctions doivent être appelées :

sans espace entre le nom de la fonction et la parenthèse ouvrante qui suit,
avec des espaces après chaque virgule séparant deux arguments,
sans espace entre le dernier argument, la parenthèse fermante et le point virgule qui suit,
en cas d'assignation, il faut ajouter au moins un espace de chaque coté du signe =
en cas d'assignations par bloc, il est conseillé d'aligner les symboles =

<?php
// Exemple 1 : assignation simple :
$var = foo($bar, $baz, $quux);

// Exemple 2 : assignation par bloc :
$short         = foo($bar, $baz);
$long_variable = foo($bar, $quux);
?>

Structures de contrôle

Ceci concerne les structures if/then/else, switch, for, while, foreach...

Il faut utiliser des accolades, même lorsqu'elles sont optionnelles.
Il faut ajouter un espace entre le mot clef et la parenthèse ouvrante qui le suit.

<?php
if ((condition1) || (condition2)) {
    action1;
} elseif ((condition3) && (condition4)) {
    action2;
} else {
    defaultaction;
}
?>

<?php
switch (condition) {
    case 1:
        action1;
        break;

    case 2:
        action2;
        break;

    default:
        defaultaction;
        break;
}
?>

Commentaires

Les commentaires par bloc /*...*/ comme les commentaires lignes //... sont OK.
Les commentaires de type shell/perl #... sont en revanche à proscrire, sauf pour mettre un # TODO/XXX/FIXME.

Inclure du code

Ne jamais utiliser require ou include mais les fonctions require_once et include_once.
N'utiliser include_once que dans les cas où tout manque de fichier inclus n'est pas critique. En pratique, ceci n'est actuellement pas utile pour x.org

PHP tags

Toujours utiliser les tags longs <?php ... ?>

Contenu des fichiers

Toujours inclure dans les fichiers l'entete GPL. Toujours ajouter la modeline vim en fin de fichier. Il suffit de reprendre un fichier PHP et un fichier de template existant.

Coding Rules MySQL

Il est très important de pouvoir retrouver où sont appelés et modifiés les champs. Tout champs doit donc être précédé d'un . (au besoin utiliser un ALIAS de table pour aller plus vite) : par exemple SELECT * FROM ... est interdit, on lui préfèrera SELECT u.user_id, u.promo FROM ... AS u. De cette façon on peut faire un grep \.promo pour trouver tous les appels à ce champs.

De même il faut rajouter SET (éventuellement en commentaire) sur toutes les lignes qui font une mise à jour d'un champs. Ex:

"UPDATE auth_user_md5 AS u SET u.nom = 'Mon Nom',
 u.prenom = 'Mon Prénom', " // SET 
 "u.promo = '2001' WHERE " // SET
 "u.user_id = 21123"

ce qui permet de faire un grep \.nom | grep SET pour retrouver tous les endroits où l'on modifie le nom.

Liste1 Liste2