Voir la source de Règles de codage

=== Configuration du serveur APACHE de développement ===
Le serveur de développement doit être configuré pour reporter les erreurs.

<pre>
error_reporting = E_ALL
display_errors = On
</pre>

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

<pre>
ini_set('error_reporting', E_ALL);
ini_set('display_errors', true);
</pre>

=== 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 <code>« adm »</code> 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 <code>« incl »</code> 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 <code><?php .... ?></code> est obligatoire. L'utilisation des tags <code><? ...?></code> 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 :
<pre>
function foo( $param1, $param2 )
{
if( $var == true )
  {
  }
}
</pre>

Les accolades sont obligatoires, comme ceci :

<pre>
if ( $var == true )
{
// Instructions
}
</pre>
même s'il s'agit d'une seule instruction. Ceci est incorrect:
<pre>
if ( $var == true )
// Instruction
</pre>

=== Les variables===
Les variables doivent, dans la mesure du possible, refléter l'objet manipulé.
<pre>
$addressEmail;
</pre>
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:

<pre>
if( .... )
{
$var = 1;
}
// utilisation de $var
</pre>
Code correct:
<pre>
$var = 0;
if( .... )
{
$var = 1;
}
// utilisation de $var
</pre>

=== Les constantes===

Les constantes doivent être définies en lettres majuscules :
<pre>
define('CONSTANTE', 20);
</pre>
S'il le faut, utiliser des underscores pour séparer les mots :

<pre>
define('MA_CONSTANTE', 20);
</pre>

===Les tableaux associatifs===
Dans les tableaux associatifs, toujours ajouter des simples quottes à la variable.
Code incorrect :
<pre>
$tab[something];
</pre>
Code correct:
<pre>
$tab['something'];
</pre>

===Protection des variables de sorties ===
* '''Vers le navigateur''' :
*: Les variables à destination du navigateur doivent être protégées, utiliser la fonction :
*: <code>bab_toHtml($str, $option = BAB_HTML_ENTITIES)</code>
*: où $option est une combinaison ( OR ) des valeurs suivantes :
** <code>BAB_HTML_ALL</code>		: BAB_HTML_P & BAB_HTML_BR & BAB_HTML_LINKS & BAB_HTML_ENTITIES
** <code>BAB_HTML_ENTITIES</code>	: special characters will be replaced with html entities
** <code>BAB_HTML_AUTO</code>	: the paragraphs tags will be added only if the text contein some text line-breaks
** <code>BAB_HTML_P</code>		: double line breaks will be replaced by html paragraphs, if there is no double line breaks, all the text will be in one paragraph
** <code>BAB_HTML_BR</code>			: Line-breaks will be replaced by html line breaks
** <code>BAB_HTML_LINKS</code>		: url and email adress will be replaced by links
** <code>BAB_HTML_JS</code>			: ' and " are encoded for javascript strings
** <code>BAB_HTML_REPLACE</code>		: 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: <code>select * from table where id='2'</code>
**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 <code>$babDB</code> pour interroger la base de données.
*: Ne pas utiliser <code>$GLOBALS['babDB']</code> 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 <code>bab_translate()</code>:
<source lang="php">
bab_translate("Hello world");
</source>

===Debug===

'''Messages :'''

Utiliser la fonction bab_debug() pour envoyer des informations de debug :
<pre>
bab_debug('Oops, something is wrong');
</pre>
Pour afficher ces informations sur le navigateur, ajouter à l'url &debug=1 :

<pre>
http://localhost/index.php?tg=version&debug=1
</pre>
Pour désactiver l'affichage des informations de debug, appeler l'url avec &debug=0


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

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

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.