Règles de codage

Un article de OviWiki.

Sommaire

Configuration du serveur APACHE de développement

Le serveur de développement doit être configuré pour reporter les erreurs.

error_reporting = E_ALL
display_errors = On

On peut aussi inclure ces directives dans le fichier index.php du site :

ini_set('error_reporting', E_ALL);
ini_set('display_errors', true);

Les fichiers

Dans la mesure du possible, le nom du fichier doit refléter la fonctionnalité gérée. D'une manière générale:

  • Si le fichier est un fichier destiné à l'administration, il doit commencer par « adm » et doit être placé dans le répertoire « admin » de la distribution.
  • Si le fichier est un fichier destiné à être inclu, le nom doit finir par « incl » et doit être placé dans le sous-répertoire « utilit » de la distribution. Ces fichiers ne doivent contenir que des déclarations (fonctions, classes, ...). Ils ne doivent en aucun cas contenir du code qui sera exécuté par inclusion uniquement.
  • Le nom ne doit pas contenir des lettres majuscules.
  • Le copyright et les références à Ovidentia et à CANTICO doivent apparaître au début de chaque fichier.
  • Pour délimiter le code PHP, l'utilisation des tags <?php .... ?> est obligatoire. L'utilisation des tags <? ...?> est interdite.
  • Le fichier doit inclure le fichier base.php
  • Le code à exécuter doit se situer en fin de fichier.
    Le début ne doit contenir que des déclarations, des fonctions ou des classes.


<?php
//-------------------------------------------------------------------------
// OVIDENTIA http://www.ovidentia.org
// Ovidentia is free software; you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation; either version 2, or (at your option)
// any later version.
// 
// This program is distributed in the hope that it will be useful, but
// WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
// See the GNU General Public License for more details.
// 
// You should have received a copy of the GNU General Public License
// along with this program; if not, write to the Free Software
// Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
// USA.
//-------------------------------------------------------------------------
/**
 * @license http://opensource.org/licenses/gpl-license.php GNU General Public License (GPL)
 * @copyright Copyright (c) 2008 by CANTICO ({@link http://www.cantico.fr})
 */
include_once 'base.php';
 
include ...
// function
...
// function 
...
 
/* main */
// code

Les accolades

Toutes les accolades doivent commencer et finir sur une nouvelle ligne :

function foo( $param1, $param2 )
{
if( $var == true )
  {
  }
}

Les accolades sont obligatoires, comme ceci :

if ( $var == true )
{
// Instructions
}

même s'il s'agit d'une seule instruction. Ceci est incorrect:

if ( $var == true )
// Instruction

Les variables

Les variables doivent, dans la mesure du possible, refléter l'objet manipulé.

$addressEmail;

En configurant PHP pour qu'il reporte toutes les erreurs, on peut détecter les variables non initialisées. D'une manière générale, toujours initialiser une variable :

Code incorrect:

if( .... )
{
$var = 1;
}
// utilisation de $var

Code correct:

$var = 0;
if( .... )
{
$var = 1;
}
// utilisation de $var

Les constantes

Les constantes doivent être définies en lettres majuscules :

define('CONSTANTE', 20);

S'il le faut, utiliser des underscores pour séparer les mots :

define('MA_CONSTANTE', 20);

Les tableaux associatifs

Dans les tableaux associatifs, toujours ajouter des simples quottes à la variable. Code incorrect :

$tab[something];

Code correct:

$tab['something'];

Protection des variables de sorties

  • Vers le navigateur :
    Les variables à destination du navigateur doivent être protégées, utiliser la fonction :
    bab_toHtml($str, $option = BAB_HTML_ENTITIES)
    où $option est une combinaison ( OR ) des valeurs suivantes :
    • BAB_HTML_ALL : BAB_HTML_P & BAB_HTML_BR & BAB_HTML_LINKS & BAB_HTML_ENTITIES
    • BAB_HTML_ENTITIES : special characters will be replaced with html entities
    • BAB_HTML_AUTO : the paragraphs tags will be added only if the text contein some text line-breaks
    • BAB_HTML_P : double line breaks will be replaced by html paragraphs, if there is no double line breaks, all the text will be in one paragraph
    • BAB_HTML_BR : Line-breaks will be replaced by html line breaks
    • BAB_HTML_LINKS : url and email adress will be replaced by links
    • BAB_HTML_JS : ' and " are encoded for javascript strings
    • BAB_HTML_REPLACE : Replace ovidentia macro $XXX() a utiliser uniquement our du texte en provenance de l'éditeur WYSIWYG
  • Vers la base de données :
    • Quel que soit le type, placer toujours les données entre apostrophes.
    Exemple: select * from table where id='2'
    • Toujours utiliser db_escape_string() pour protéger les variables passées dans les requêtes SQL.
    Exemple : select id from table where id_user=\'.$babDB->db_escape_string($var).\';
    • Ou la méthode quote() qui permet de traiter les tableaux
    Exemple : select id from table where id_user=IN(.$babDB->quote($var).);

Base de données

  • Variable global babDB :
    Utiliser toujours la variable global $babDB pour interroger la base de données.
    Ne pas utiliser $GLOBALS['babDB'] mais explicitement déclarer la variable globale, comme ceci :
    global $babDB;
  • Insert:
    Ne pas utiliser :
    INSERT INTO table VALUES( ... )
    Utiliser plutôt:
    INSERT INTO table (colonne1,collonne2,colonne3) VALUES( ... )
    Il faut nommer explicitement les colonnes.
  • Select:
    Dans la mesure du possible, nommer explicitement les champs souhaités :
    Ne pas utiliser :
    select * from table
    Utiliser plutôt:
    select champ1, champ2 from table

Variables externes à PHP ( GET et POST )

Pour récupérer une variable POST ou GET, utiliser les fonctions suivantes :

    • bab_rp( $var, $default=) : pour récupérer une variable de $_GET ou $_POST
    • bab_pp( $var, $default=) : pour récupérer une variable de $_POST
    • bab_gp( $var, $default=) : pour récupérer une variable de $_GET

Ces fonctions renvoient la valeur de la variable $var si celle-ci s'y trouve. Sinon, elles renvoient la valeur de la variable $default.

Ne pas utiliser systématiquement bab_rp(). Il faut s'assurer de l'origine de la variable. Si vous attendez une variable POST, utiliser bab_pp() et non pas bab_rp()!

API des addons

Les fonctions utilisables par les modules ( API addons ) doivent être préfixées par le préfixe « bab_ » et doivent être localisées dans le fichiers addonapi.php qui se trouve dans le sous-répertoire « utilit ».

Fonction de traduction

Toutes les chaînes de langage doivent être en anglais et traduites en utilisant la fonction bab_translate():

bab_translate("Hello world");

Debug

Messages :

Utiliser la fonction bab_debug() pour envoyer des informations de debug :

bab_debug('Oops, something is wrong');

Pour afficher ces informations sur le navigateur, ajouter à l'url &debug=1 :

http://localhost/index.php?tg=version&debug=1

Pour désactiver l'affichage des informations de debug, appeler l'url avec &debug=0


Affichage de la pile d'exécution de PHP :

include_once $GLOBALS['babInstallPath'].'utilit/devtools.php';
bab_debug_print_backtrace();

Par défaut, l'état de la pile est affiché comme un message de debug. Pour l'afficher directement, il faut l'appeler comme ceci : bab_debug_print_backtrace(true);

Afin que l'état de la pile s'affiche, il faut que error_reporting de php.ini contienne E_NOTICE.


Affichage des erreurs SQL :

Pour que les erreurs SQL s'affichent, il faut que error_reporting contienne E_USER_ERROR. Si l'utilisateur est administrateur, l'état de la pile PHP est automatiquement ajouté à l'affichage lors d'une erreur SQL.

HTML / CSS

Liste des classes spécifiques à ovidentia définies dans les skins :

  • BabLoginCadreBackground
  • BabLoginMenuBackground
  • BabSiteAdminTitleFontBackground
  • BabForumBackground1
  • BabSiteAdminFontBackground


Pour utiliser d'autres styles, il faut créer des feuilles de style supplémentaires à l'intérieur du répertoire style du noyau et inclure le fichier par php :

$babBody->addStyleSheet('toto.css');

Uploads

Pour être compatible avec la directive open_basedir, il ne faut jamais ouvrir un fichier dans le répertoire temporaire. Utilisez plutôt ce code à la place :

include_once $babInstallPath."utilit/uploadincl.php";
$cphoto = bab_getUploadedFileContent('photof');

ceci permet de récupérer le contenu du fichier en passant par un fichier temporaire intermédiaire.