Règles de codage : Différence entre versions

Version actuelle en date du 2 novembre 2009 à 16:49

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.

<source lang="php"> <?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

</source>

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 :

  <source lang="php">global $babDB;</source>

• 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(): <source lang="php"> bab_translate("Hello world"); </source>

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 : <source lang="php"> $babBody->addStyleSheet('toto.css'); </source>

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 :

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

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