Voici les quelques règles sur le langage, la syntaxe et normes de développement en vigueur pour le projet Dolibarr:


Versions

  • Dolibarr doit fonctionner sur:
  1. Tous OS (Windows, Linux, MACOS...)
  2. PHP 4.3 ou + (Doit fonctionner sans aucun module PHP complémentaire hors les modules d'accès base de donnée).
  3. Mysql 3.1 ou +

Normes PHP

  • Dolibarr est écrit en PHP et supporte toutes versions PHP supérieures à la 4.1. Les fichiers doivent tous comporter l'extension .php
  • L'appel aux variables superglobales PHP doit passer par les opérateurs dédiés $_GET, $_POST, $_COOKIES, $_SERVER, $_ENV.

Les autres opérateurs ($HTTP_SERVER_GET, ...) ayant été passé en deprecated au sein de PHP, ne doivent plus être utilisées. Ainsi le code doit fonctionner y compris quand l'option register_long_arrays est à off. De plus, le code doit fonctionner quand l'option PHP register_globals est à off (recommandé par PHP) aussi bien que quand l'option register_globals à on (par défaut sur de nombreuses installations).

  • Les smart tags PHP ne sont pas utilisés. Les sections de code doivent commencer par <?php
  • Pas d'utilisation de la variable PHP_SELF. Utiliser a la place $_SERVER["PHP_SELF"]
  • Quand plusieurs variables doivent etre initialisées avec la même valeur, il faut utiliser plusieurs lignes
$var1=1;$var2=1;$var3=1;

plutot que

$var1=$var2=$var3=1;

qui est moins performant.

  • Les chaines doivent etre encadrés de simple quote et les variables sorties de la chaine.
print 'Mon texte affiche ma '.$variable.' !';
  • Les commentaires doivent suivre la syntaxe C, ie un double antislash pour un commentaire d'une ligne et utilisation slash-étoile pour ouvrir un bloc de plusieurs ligne

/* Bloc de commentaire
 *
 * Fin du bloc
 */

$monobjet = new MonObjet($db);
$result=$monobjet->fetch($idobject);

for ($i = 1 , $i < 2 ; $i++)
{
  // commentaire sur une ligne
  print $i;
}

  • Les fichiers doivent etre sauvés en format Unix (LF) et non Windows (CR/LF). Le format Unix étant compatible sur les OS Unix like, Windows, Mac, alors que le format fichier texte Windows pose problème sous certains PHP sous Unix.

Les fonctions doivent retourner 0 en cas de succès, et un nombre <0 en cas d'erreur. A ce jour, très peu de fonctions respectent ce standard mais c'est celui vers lequel il faut tendre.

Normes SQL

  • Les SELECT * sont interdits ! Chaque SELECT doit spécifier la liste complète des champs à récupérer. Cela permet d'éviter les confusions. Exemple:
 SELECT field_a, field_b, field_c FROM table_1 WHERE field_d = '$id'
  • Dans les requètes SQL, on quote les champs mais pas les numériques qui contiennent des montantsdestinés a etre stokés dans des champs de type double ou real. Les quotes sur les numériques de type float provoquent parfois un stockage d'une valeur différente. Par exemple 412.62 dans le insert sera en fait stocké avec la valeur 412.61999512 en base si le champ est de type double(24,8). Et seul le PHP voit 412.61999512. Les autres outils verront 412.62 donnant l'impression qu'il n'y a pas de probleme. Et c'est le PHP qui a raison, il y a problème en base. En supprimant les quotes sur les numériques, cela va mieux.

Exemple:

Bon:     INSERT INTO table_1 (field_txt, field_num) VALUES ('txt', 412.62)
Mauvais: INSERT INTO table_1 (field_txt, field_num) VALUES ('txt', '412.62')

Remarque, le pb des float est general et pas seulement sur les acces base, aussi ils doivent être, dès que affectés, nettoyés par la fonction price2num avec le 2eme parametre renseigné à: 'MU', 'MT' ou 'MS' selon le besoin. (voir doc fonction)

  • Dolibarr doit fonctionner même avec l'option strict de Mysql.

Normes HTML

  • Tous les attributs dans les balises HTML doivent être *en minuscule* et quottés avec des *doubles quote* (Norme xhtml)
  • Les liens href doivent etre absolu et se baser pour les pages sur la constante DOL_URL_ROOT qui pointe sur htdocs et pour les images se base sur l'appel de la fonction img_picto.

Par exemple:

print '<a href="'.DOL_URL_ROOT.'/monrep/mapage.php">'.img_picto('Texte alt','nompictopng','').'</a>';
  • Le javascript et l'appel aux scripts java dans les pages php est à proscrire. Si toutefois du code javascript est inclus, il doit être conditionné par le test sur "$conf->use_javascript"
if ($conf->use_javascript)
{
...  // Le code php qui génère du javascript est ici
}
  • Les popups windows ne doivent pas être utilisées, sauf pour des tooltips (et restent condtionner par le point ci-dessus).
  • Les scripts externes sont écrits en Perl s'ils ne peuvent l'être en php, l'utilisation d'un autre langage n'est pas interdit mais doit être discuté au préalable dans la mailing list des développeurs. Le langage devra être maitrisé par au moins 2 développeurs pour en assurer la maintenance.

Squelettes de code

Afin d'uniformiser le code et d'accélérer le développement de nouveaux composants dans Dolibarr, se trouvent dans le répertoire dev/skeletons, 4 squelettes de code tout préparés.

  • 1 qui sert d'exemple de descripteur de module: myModule.class.php
  • 1 qui sert d'exemple de code pour faire une nouvelle classe: skeleton_class.class.php
  • 1 qui sert d'exemple de code pour faire une nouvelle page: skeleton_page.php
  • 1 qui sert d'exemple de code pour faire un script à exécuter en ligne de commande: skeleton_script.php

Programmation Objet

Motifs d'organisation du code:

Martin Fowler a identifié 3 méthodes d'organisation du code appelées motifs:

  • Le Transaction Script (Le code est linéraire en fonction d'une action utilisateur).

C'est le motif à l'ancienne utilisé dans les langages procéduraux. Inconvénient: Redondance du code. Nécessité de connaitre le modèle physique pour développer.

  • Le Domain Model

C'est un concept possible depuis les langages objets. Ce sont les procédures métiers (qui doivent être identifiés avant) qui servent de bases pour les classes objets. Inconvénient: Motif complexe à maintenir.

  • Le Table Module

Un intermédiaire entre les 2 précédents où l'on a une instance unique de classe par table de la base de donnée.

Comme le montre les squelettes de code (voir point précédent), Dolibarr se base sur le principe du Table Module.

Communication Logique métier - Données (ORM):

Il existe 3 modes de liaisons:

  • Le Table And Row Data Gateway

C'est le plus simple. On crée une table par classe et chaque classe est un pont avec la table correspondante, voir une classe par ligne de table. Une instance de classe étant alors un enregistrement de la table. La classe ne contient que du code d'accès aux lignes ou colonnes de tables.

Exemple: C'est le mode mis en oeuvre quand on utilise certains Frameworks d'ORM comme iBatis (http://ibatis.apache.org/).

  • Le Active Record

Identique au précédent, mais on se permet d'ajouter quelques fonctions métiers sur la classe, à conditions que ces fonctions soient propres a la table ou à l'enregistrement.

Exemple: C'est le mode choisi pour les développements Dolibarr et de nombreuses autres applications PHP qui ont leur propre framework et pratiques de développements.

  • Le Data Mapper

Les classes représentent les entités du problème et non les données. Il faut donc doubler, tripler... ces classes avec des classes Mapper pour accéder aux données.

Exemple: C'est le choix si on utilise le Framework d'ORM Propel (http://propel.phpdb.org/trac/).


Pour les développements Dolibarr, il est recommandé d'utiliser le mode de liaison Active Record qui offre les avantages d'un modèle proche du métier sans en avoir la complexité et sans trop masquer non plus la technique. C'est dans ce mode que le développement, la compréhension du code et la maintenance technique et/ou fonctionnelle) est la plus productive.