Langages et normes: Difference between revisions

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

<source lang="php">

<?php

Quand vous éditez un fichier existant du projet, ajouter une ligne Copyright sous celles existantes.

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 aussi bien quand l'option PHP '''register_globals''' est à off (recommandé par PHP)  que quand l'option '''register_globals''' est à on (par défaut sur de nombreuses installations).

<source lang="php">

$var1=1;$var2=1;$var3=1;

qui est moins performant.

<source lang="php">

print 'Mon texte affiche ma '.$variable.' !';

</source>

<source lang="php">

/* Bloc de commentaire

</source>

Certaines propriétés de classes se retrouvent dans de nombreuses classes. Pour homogénéité, on utilisera les noms suivants:

{{TemplatePHPFields}}

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 AUTO_INCREMENT PRIMARY KEY    qui est l'id technique

  - fk_soc integer qui est l'id du tiers (si applicable)

Dans la pratique, afin d'etre compatible avec toutes les précisions des pays, syntaxes des bases, on utilisera uniquement les types suivants:

  - smallint pour tout petit nombre entier

  - date pour un champ date

La clé primaire d'une table s'appelle <tt>rowid</tt>.

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.

Le nom d'une clé étrangère commence par le préfixe <tt>fk_</tt> 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).

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.

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 <tt>uk_</tt> suivi du nom de la table (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).

uk_societe_code_client

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 <tt>idx_</tt> puis le nom de la table et le nom du champ sur lequel porte l'index.

idx_societe_user_creat

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 <tt>llx_''matable''.sql</tt>.  

</source>

Dans le cas des select on pourra utiliser les alias pour simplifier l'écriture des requêtes:

<source lang="sql">

Toutefois, il ne faut pas utiliser ces alias sur des requêtes update car non compatible avec mysql 3.1.

<source lang="sql">

SELECT field_a, field_b, field_c FROM table_1 WHERE field_d = '$id'

</source>

Exemple:

Voir aussi le chapitre "Les nombres réels, montants et calculs" plus bas.

Par exemple, on ne fera pas:

Un autre avantage de cette règle est que la requête peut bénéficier de l'utilisation de l'index puisqu'on compare datefield à une valeur fixe. Dans le cas du datediff, on applique un traitement sur le champ avant comparaison, rendant impossible l'utilisation de l'index de ce champ. Les conséquences sont des performances très dégradées par rapport à la version sans datediff.

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.

Pour l'activer, ajouter la ligne suivante dans le fichier config du serveur Mysql (my.cnf ou my.ini)

<source lang="ini">

</source>

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.

</source>

Par example:

<source lang="php">

</source>

<source lang="php">

if ($conf->use_javascript_ajax) {

</source>

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.

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.

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).

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).

Dolibarr stocke les informations de manière suivante:

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  

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()'''.

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).

Si votre code a besoin de faire des choses différentes selon la version de Dolibarr, vous pouvez utiliser le truc suivant pour comparer les versions

</source>

Ajouter des traces dans votre code avec la fonction

<source lang="php">

</source>

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''''

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 définis par le Gang Of Four (voir la wikipédia sur les [[wikipedia:Patron de conception|Design patterns]]).

Dans Dolibarr, pas de mise en oeuvre de design patterns de comportement 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 la plus large plage possible de versions de PHP.

[[wikipedia:Martin_Fowler|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.

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

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.

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 bien  propres à la table ou à la notion métier porté par l'enregistrement. C'est le pattern qui offre le meilleur rapport fonctionnalité/complexité.

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 très complexe et difficile à maintenir dans la réalité (l'expérience pratique constaté ne rejoignant pas les promesses de la théorie).

-> 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).

Il existe plusieurs design pattern pour les interfaces utilisateurs (MVC, MVP, MVVM).

Beaucoup confonde ce design pattern avec celui consistant à utiliser un framework de templates. C'est sans rapport. Un framework de template (voir point précédent) n'est en lien qu'avec la partie "V" de ces modèles.

Ce mode de séparation a eu un effet neutre sur les nouveaux développement mais a permis de réduire de manière si importante le temps requis pour la maintenance et correction de bugs qu'il n'est pas envisagé de basculer vers un autre type de séparation (oui les constats fait dans la vraie vie ne sont pas toujours ceux attendus par la théorie scolaire). L'important reste qu'il y ait toujours séparation entre le C et le V, peut importe comment est matérialisé cette séparation, du moment qu'elle l'est (Rappel: Ne pas confondre la notion de séparation du C et du V avec la notion de séparation du code pour alimenter la données d'une Vue et du code pour formater la Vue, ceci un principe de séparation relevant du Design Pattern de Vue, voir point suivant).

Il existe des frameworks spécialisés dans le Design Pattern de Vue, la partie qui consiste à formater l'écran vue par l'utilisateur.

Les vieilles versions de Dolibarr utilisaient Smarty. Ce framework est une surcouche à un Framework, déjà très puissant de formatage d'écran nommé PHP. Les bénéfices étant très inférieurs aux inconvénients, il a été abandonné au profit du PHP qui reste le plus simple, le plus universel des frameworks de présentation. Son seul défaut est qu'il ne peut garantir à 100% les écarts d'un développeur qui irait intégrer dans la Vue, une logique sans rapport avec la présentation (donc autre que du code à vocation de génération, de formatage, de sortie HTML, de logique de test ou de boucle). Ce point est toutefois contrôlé par le mécanisme de validation du code des chefs de projets.

La encore, c'est l'experience et le constat d'un meilleur rendement de productivité qui a motivé l'abandon des frameworks de Présentation externes au profit du framework PHP.