Langages et normes

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  (Doit fonctionner sans aucun module PHP complémentaire hors les modules d'accès base de donnée).
 * 3) Mysql

= Normes Copyright = Quand vous éditer un fichier existant du projet, ajouter une ligne Copyright sous celles existantes.
 * Tout fichier PHP doit avoir un en-tête selon le masque suivant

= Normes PHP =


 * Dolibarr est écrit en PHP et supporte toutes versions PHP supérieures à la . Les fichiers doivent tous comporter l'extension .php

Les autres opérateurs ($HTTP_SERVER_GET, ...) ayant été passés en deprecated au sein de PHP, ne doivent plus être utilisés. 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).
 * L'appel aux variables superglobales PHP doit passer par les opérateurs dédiés $_COOKIES, $_SERVER, $_ENV mais par la fonction dolibarr GETPOST pour récupérer les contenus de $_GET ou $_POST.


 * Pas d'utilisation de la variable PHP_SELF. Utiliser a la place $_SERVER["PHP_SELF"]

plutôt que qui est moins performant.
 * Quand plusieurs variables doivent être initialisées avec la même valeur, il faut utiliser plusieurs lignes


 * Les chaines doivent être encadrées de simple quote et les variables sorties de la chaine.


 * 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 lignes


 * Les fonctions doivent retourner une valeure strictement > à 0 en cas de succès, et un nombre < à 0 en cas d'erreur.


 * Pas de code mort (non utilisé) dans le code principal de Dolibarr (le code utilisé uniquement par un module externe doit être inclus dans le module externe).


 * Utiliser "include_once" pour l'inclusion de tout fichier contenant des définitions de fonction ou de classes (donc fichiers *.class.php et *.lib.php), utiliser "include" pour tout inclusion de fichier de type template ou contenant un mixte de HTML et PHP (donc fichiers *.inc.php et *.tpl.php).

Vous pouvez utiliser le fichier dev/codesniffer/ruleset.xml comme fichier de contrôle pour vérifier votre style de code avec PHPCodeSniffer.
 * Le style de code a utiliser est le PSR-2 (https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md) avec 2 exceptions, cela signifie entre autre:
 * Les fichiers doivent être 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 smart tags PHP ne sont pas utilisés. Les sections de code doivent commencer par <?php
 * Mais il y a l'exception de la longueur des lignes: On accepte plus de 80 caractères par ligne. Dans la plupart des cas, ce ne sera pas le cas, mais parfois (comme lorsqu'on déclare une liste de valeurs de référence dans un tableau dans les fichiers descripteur de module), il est préférable d'avoir de longues lignes de données plutôt que de longues pages car ce code ne contient aucune logique.
 * L'autre exception est qu'on ne remplace pas les tabulation par des espaces. Ceci rend certains editeurs fous et casse certaines fonction d'autoformatage ou de copié-collé.

= Normes SQL =

Structure des tables et champs

 * Toutes les tables sont préfixées pour éviter les conflits de nommage. Aujourd'hui, le préfixe est modifiable au moment de l'installation. Sa valeur par défaut est llx_.

Lorsque vous créez une table, il est recommandé de prendre les même conventions de nommages de tables que les autres tables Dolibarr. Avec, à minima les champs suivant: - rowid integer pour l'id - tms timestamp qui sera un champ contenant la date de chaque mise à jour (la base de donnée le gère tout seul, pas besoin de le gérer par le code) - import_key qui contiendra le code d'import YYYYMMDDHHMMSS si vous faites des imports en masse dans la table. Eventuellement - datec timestamp qui est la date de création de l'enregistrement - fk_user_creat integer qui est l'id du user de création - fk_user_modif integer qui est l'id du user de modif
 * Structure des tables.

Dans la pratique, afin d'etre compatible avec toutes les précisions des pays, syntaxes des bases, on utilisera uniquement les types suivants: - integer pour tout nombre entier, id ou clé étrangère - double(24,8) pour tout montant - double(6,3) pour les taux de tva - real pour une quantité - varchar pour une chaine (y compris de longueur 1, le type char est de plus en plus déprécié) - timestamp pour un champ date+heure devant être mis a jour automatiquement - datetime pour un champ date+heure - date pour un champ date
 * Type des champs

Clé primaire
La clé primaire d'une table s'appelle rowid.

Il y a quelques tables qui échappent à cette règle actuellement (ex Table llx_c_actioncomm), pour des raisons historiques. Une évolution pourra être étudiée pour une prochaine version.

Clés étrangères
Le nom d'une clé étrangère commence par le préfixe fk_ suivi du nom de la table liée (requis pour éviter doublons globales à la base, problématiques sous certains SGBD comme postgresql) puis du champ lié (pour permettre plusieurs clés étrangères différentes sur une même table).

Exemple: fk_facture_fourn_fk_soc

Note: Si vous développez votre propre module externe, il ne doit pas y avoir de clé étrangère depuis vos tables qui pointent sur les tables standards de Dolibarr. Ceci casserait les fonctionnalités de mise à jour, de réparation, de sauvegardes et de restauration.

Clés alternatives
Parfois, il n'y a pas que la clé primaire qui doit être unique. On peut donc ajouter aussi un index clé alternative unique. Un tel index est nommé par un nom qui commence par le préfixe uk_ suivi du nom de la table d'un underscore (requis pour éviter doublons d'index globals à la base, problématiques sous certains SGBD comme postgresql) puis d'un suffixe qui caractérise la clé (pour permettre plusieurs index uniques sur une même table).

Exemple: uk_societe_code_client

Index performance
Certains champs sont souvent utilisés comme critère de recherche, de tri ou de jointure. Il convient dans ce cas, d'y mettre un index de performance. De tels indexes seront nommés avec un préfix idx_ puis le nom de la table et le nom du champ sur lequel porte l'index.

Exemple: idx_societe_user_creat

Format de fichier DDL
Les fichiers qui contiennent la définition de la structure de la base (DDL) doivent être au nombre de 2 par tables: Chaque table est définie dans son propre fichier dont le nom est llx_matable.sql. On mettra un commentaire à côté de chaque champ pour en expliquer la signification. Les clés étrangères et index de performance ou autres contraintes d'unicité sont définies dans un fichier séparé dont le nom est llx_matable.key.sql

Ces fichiers sont placés dans le répertoire install/mysql/tables pour les fichiers standards ou monmodule/tables pour les tables amenées par un module.

Exemple fichier table llx_matable.sql:

Exemple fichier clés/index llx_matable.key.sql:

Règles de codage SQL
Dans le cas des select on pourra utiliser les alias pour simplifier l'écriture des requêtes: Toutefois, il ne faut pas utiliser ces alias sur des requêtes update car non compatible avec mysql 3.1.
 * Utilisation des alias/nommage de champs


 * 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:


 * Dans les requêtes SQL, on quote les champs mais pas les numériques qui contiennent des montants destinés à être stocké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 (suite à des conversions chaines-numériques implicites) 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 problème. 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:

Remarque, le problème des float est général et pas seulement sur les accès base, il est présent dans tous les languages quand on travaille sur des nombres réels, aussi ils doivent être, dès que affectés, nettoyés par la fonction price2num avec le 2eme paramètre renseigné à: 'MU' (si il s'agit d'un prix unitaire), 'MT' (s'il s'agit d'un prix total) ou 'MS' (autres cas) selon le besoin. Voir aussi le chapitre "Les nombres réels, montants et calculs" plus bas.


 * Les fonctions NOW ou SYSDATE sont interdites au sein des ordres SQL. S'il faut saisir la date du moment dans un champ, la valeur doit venir du PHP et non du moteur de base de données. Ceci afin d'avoir une meilleure portabilité du code mais surtout d'avoir une gestion correcte des TimeZone.

Règles de migration de base

 * Les scripts de migration de structure sont les fichiers de type install/mysql/migration/a.b.c-x.y.z.sql. Dans un fichier de migration de n vers n+1, on ne détruit une table (DROP TABLE) qui n'est plus utilisée en n+1 que lors de la migration de la version n+1 vers n+2. Ceci afin de toujours conserver les tables deprecated le temps d'une version pour réparer une situation en cas d'erreur de migration.

Spécificités MySQL
En effet, ce format gère les clés étrangères, les éventuelles restrictions qui y sont attachées et la notion d'intégrité de transactions requise pour avoir des données en base cohérente entre tables.
 * Les tables doivent être au format InnoDB.

Pour l'activer, ajouter la ligne suivante dans le fichier config du serveur Mysql (my.cnf ou my.ini)
 * Dolibarr doit fonctionner même avec les options strict de Mysql active.

Spécificités PostgreSQL
Seuls les fichiers pour Mysql doivent être maintenus. Les fichiers pour les autres bases sont convertis "à la volée" par le driver Dolibarr de la base.

Il existe une exception. Les requêtes "UPDATE FROM" : Syntax MySQL :

Syntax PgSQL:

Il n'en existe pas dans Dolibarr, mais pour vos modules Vous devriez faire tel que :

= Normes HTML =


 * Tous les attributs dans les balises HTML doivent être *en minuscule* et quotés avec des *doubles quote*.

Par example:
 * Les liens href doivent être absolus en se basant sur la fonction dol_buildpath pour obtenir un chemin absolu depuis un chemin relatif au répertoire htdocs. Pour les tags img, il faut faire appel à la fonction img_picto.


 * Les tables HTML doivent avoir des colonnes sans valeures forcées, excepté pour les colonnes qui contiennent une information dont la longueur est non variable. Par exemple, une colonne avec un picto peut etre forcée à with="20px". Dans les autres cas, il faut éviter de forcer la largeur des colonnes. La raison est que, dans la plupart des cas, le navigateur fait un meilleur travail pour définir automatiquement la bonne largeur des colonnes qu'en forçant manuellement les largeurs. Et ceci marche quelque soit la résolution de l'écran.


 * Le javascript/ajax 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_ajax"


 * Les popups windows ne doivent pas être utilisées, sauf pour des tooltips (et restent conditionnées 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.

= Normes Dolibarr et squelettes de code =

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

Servez-vous en comme exemple. Notons que ces squelettes sont aussi utilisés par le générateur de code PHP qui est décrit dans la chapitre de développement de module Dolibarr pour accélérer vos développement.

Les dates et TimeZone
Dolibarr se veut une application multi-utilisateur et multi-localisation. Il convient donc de stocker les dates dans le bon format. Pour éviter les problèmes de conversion, les règles suivantes doivent être appliquées: Ainsi le 1er janvier 1970, 3 heures à Paris (TZ=+1) = 1er janvier 1970, 2 heures à Greenwich (TZ=0) sera stocké en mémoire par 7200 et sera soumis à la base de données avec la chaine '19700101030000' (PHP convertit en heure de son TZ et la base déconvertit avec son TZ qui est le même que celui de PHP).
 * Une date en mémoire doit être au format Timestamp GMT.
 * Une date stockée en base de données contient le Timestamp issue de la date soumise dans la requête en heure locale du serveur PHP. Cela ne concerne pas les dates mises à jour automatiquement par la base (champ tms en base).

Les méthodes select doivent donc traduire les champs dates lus qui sont au format chaine TZ de la base ('19700101030000') par appel de la méthode db->jdate afin de récupérer une information en mémoire au format Timestamp GMT. Et les méthodes insert doivent lors de la génération de la requête convertir la date mémoire connue en variable, par la méthode db->idate (Voir exemples générés par le squelette).


 * Les dates mises à jour automatiquement par la base (champ tms en base) contiennent le Timestamp où la modification est faite selon le timezone de la base de donnée. Les méthodes select récupèrent cette donnée en mémoire au format Timestamp GMT en appliquant également le db->jdate. Si le timezone de la base de donnée diffère de celui du PHP (un des 2 est mal réglé), il peut donc y avoir des écarts entre date de création et modification.


 * La manipulation de dates en PHP doit être faite en utilisant les fonctions dates de Dolibarr: dol_now, dol_mktime, dol_stringtotime, dol_getdate, dol_time_plus_duree. Vous trouverez également d'autres fonctions prêtes à l'emploi dans le fichier date.lib.php.

L'encodage UTF8/ISO
Dolibarr stocke les informations de manière suivante:
 * En base de donnée, les données sont en UTF8 ou ISO. Cela dépend du pagecode de la base, donc des options à la création de cette base. Dans tous les cas le driver d'accès base Dolibarr (dans /lib/database) s'arrange à la lecture et insertion pour convertir vers et depuis de l'UTF8.
 * Les données en mémoires sont donc stockées en UTF8 (instances d'objets PHP).
 * Les pages web affichées à l'écran sont au format UTF8 (avec les versions < 2.5.1, c'est le vieux paramètre $character_set du fichier conf.php qui définissait le format de sortie).

Les nombres réels, montants et calculs
En PHP comme dans d'autres langages (Java par exemple), les données non entières (float, real, double) ne sont pas fiables. Essayer de faire par exemple Vous n'obtiendrez pas zéro mais un nombre très petit en puissance de 10 négative. Si vous obtenez zéro, vous pourrez trouvez d'autres exemples qui ne fonctionnent pas. Le problème des float est général, une variable résultante de calcul de nombre réels doit SYSTEMATIQUEMENT être nettoyée par la fonction price2num avec le 2eme paramètre renseigné à: 'MU', 'MT' ou 'MS' selon le besoin (voir doc fonction). S'il ne s'agit pas d'un prix sur lequel s'adapte les paramètres MU, MT ou MS, il faut utiliser la fonction round.

Création de tables
Ne pas créer de table à l'utilisation, c'est-à-dire à la première utilisation du module. Si vous créez un module qui utilise des tables qui ne sont pas intégrées en standard dans le code de Dolibarr, veillez à suivre le didacticiel Développement module qui explique comment joindre des tables qui se créent à l'activation du module et non à son utilisation (voir plus haut).

Logs
Ajouter des traces dans votre code avec la fonction

Répertoires de travail
Si vous avez besoin de créer un répertoire de travail, dans votre code, faites référence à ce répertoire par DOL_DATA_ROOT.'/monmodule'

Le répertoire peut être créé dans votre code à l'exécution par le code suivant:

Si vous avez besoin d'un répertoire qui contiendra des données temporaires, ce répertoire doit être DOL_DATA_ROOT.'/monmodule/temp'

= Design patterns et programmation objet =

Design patterns de Création (GoF)
Design patterns défini par le Gang Of Four (voir la wikipédia sur les Design patterns). Dans Dolibarr, pas de mise en oeuvre de design patterns de création particulier. On trouve des objets proches des Singletons et Fabriques conforme à 100% dans l'esprit mais pas dans la syntaxe, ceci afin d’être compatible avec le PHP 4 qui n'est pas un langage objet complet.

Design patterns de Structure (GoF)
Design patterns défini par le Gang Of Four (voir la wikipédia sur les Design patterns). Dans Dolibarr, pas de mise en oeuvre de design patterns de structure particulier.

Design patterns de Comportement (GoF)
Design patterns défini par le Gang Of Four (voir la wikipédia sur les Design patterns). Dans Dolibarr, pas de mise en oeuvre de design patterns de comportement particulier.

Mode d'organisation du code
Martin Fowler a identifié 3 méthodes d'organisation du code appelées patterns (motifs): 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 les parties métiers. 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. 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ées.
 * Le Transaction Script (Le code est linéaire en fonction d'une action utilisateur).
 * Le Domain Model
 * Le Table Module

-> 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: C'est le plus simple. On crée une classe par table et chaque classe est un pont avec la table correspondante et propose les méthodes CRUD sur cette table (Create, Read, Update, Delete). 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. Le code métier doit alors être ajouté dans d'autres classes. Les liens entre ces classes tables et les classes métiers devant être connues ou déduite de la connaissance du développeur.
 * Le Table And Row Data Gateway

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

Identique au précédent, mais on se permet d'ajouter quelques fonctions métiers sur la classe, à conditions que ces fonctions soient propres à la table ou à l'enregistrement. C'est le pattern qui offre le meilleur rapport fonctionnalité/complexité.
 * Le Active Record

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.

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. Plus "puriste" sur le papier car plus proche du métier, ce mode a aussi l'inconvénient d'être plus complexe sur le plan pratique.
 * Le Data Mapper

Exemple: C'est le choix si on utilise le Framework d'ORM Propel (http://propel.phpdb.org/trac/). On le trouve donc sur des applications plus lourdes basées sur cet ORM entre autres.

-> 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 semble la plus productive (ceci est toutefois un éternel débat entre les puristes et les pragmatiques, débat dans lequel personne ne peut vraiment avoir raison, car tout dépend des objectifs à atteindre).