Règles de codage : Différence entre versions

Version du 7 janvier 2008 à 09:47

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.

/************************************************************************
 * OVIDENTIA http://www.ovidentia.org                                   *
 ************************************************************************
 * Copyright (c) 2003 by CANTICO ( 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</li>
  • BAB_HTML_ENTITIES : special characters will be replaced with html entities</li>
  • BAB_HTML_AUTO : the paragraphs tags will be added only if the text contein some text line-breaks</li>
  • 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</li>
  • BAB_HTML_BR : Line-breaks will be replaced by html line breaks</li>
  • BAB_HTML_LINKS : url and email adress will be replaced by links</li>
  • BAB_HTML_JS : ' and " are encoded for javascript strings</li>
  • BAB_HTML_REPLACE : Replace ovidentia macro $XXX() a utiliser uniquement our du texte en provenance de l'éditeur WYSIWYG</li>

• Vers la base de données:
  • Toujours placer les données entre apostrophes quelque soit le type.

  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:

  Toujours utiliser 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.

N'utilisez pas 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, utiliser 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.