Dolibarr ERP CRM Wiki - User contributions [en]

Ce que fait Dolibarr

2021-09-30T09:05:24Z

Quentic: Correction d'erreur de frappe

[[en:What_Dolibarr_Does]]
[[es:Lo_que_hace_Dolibarr]]
[[zh:Dolibarr是什么？]]
[[pt:O_que_o_Dolibarr_faz]]
[[de:Was_macht_Dolibarr]]


{{TemplateDocUtil}}
[[Category:FAQ FR]]

'''Dolibarr ERP & CRM''' est un logiciel modulaire (on n'active que les fonctions que l'on désire) de gestion d'entreprise qui s'adapte à la taille de votre entreprise ('''TPE/PME, Grand groupe, Indépendants ou association'''). C'est un projet OpenSource qui s'exécute au sein d'un serveur Web et peut donc être accessible depuis n'importe quel lieu disposant d'une connexion Internet, ou seulement en local : sur une machine sans connexion.

Notez que Dolibarr est également disponible grâce à des '''auto-installeurs pour les utilisateurs sans connaissances techniques''' afin d''''installer Dolibarr et tous ces pré-requis (Apache, Mysql, PHP)''' par un simple fichier auto-installable.
Ces versions s'appellent:

*[[DoliWamp FR|DoliWamp]], un installeur auto-exe pour les utilisateurs Windows.
*[[Dolibarr pour Ubuntu ou Debian|DoliDeb]], un installeur pour les utilisateurs Linux Debian/Ubuntu.
*[[Dolibarr pour Redhat ou Fedora (package rpm)|DoliRpm]], un installeur pour les utilisateurs Linux RedHat/Fedora/OpenSuse/Mandriva/Mageia.
*une installation séparée (Apache, MySQL, PHP) par exemple : permet d'installer l'environnement nécessaire à Dolibarr sous toute machine : ce format demande plus de connaissances, est généralement réservé à la création de serveur, mais est dans le même temps plus paramétrable.

Dans '''tous les cas''' : le paramétrage d'une box ou d'un routeur permet d’accéder à la partie serveur depuis n'importe quel endroit via internet (référez vous à la section [[Informations sécurité]] pour plus d'information)

Dolibarr se démarque des autres suites de gestion d'entreprise par sa plus grande simplicité (règle des 3 S):

*'''Simple pour l'installation''' (avec au choix des installeurs clé en main pour ceux qui ignorent comment installer un serveur Web, ou une installation manuelle)
*'''Simple pour l'utilisation''' (fonctions modulaires pour ne pas surcharger les menus, informations claires à la saisie)
*'''Simple pour le développement''' (pas de frameworks lourds). Dolibarr intègre en effet sa propre architecture (design patterns) permettant à tout développeur d'être tout de suite opérationnel sans connaissances particulières autre que le PHP.

La version standard est de plus compatible avec tous les systèmes et la plupart des offres Cloud du marché.

Voici une liste des fonctionnalités principales couvertes par Dolibarr...

=[[File:Art.png]] Fonctionnalités / Modules principaux (tous optionnels)=

*Annuaire des prospects et/ou clients et/ou fournisseurs
*Annuaire des contacts/adresses
*Catalogue de produits et services
*Gestion des stocks, inventaires
*Gestion des comptes bancaires
*Gestion des commandes
*Gestion des propositions commerciales
*Gestion des contrats de services
*Gestion des factures clients et fournisseurs
*Gestion des paiements, encaissement en ligne via Paypal, Stripe, ...
*Gestion des virements bancaires
*Gestion des expéditions
*Gestion des adhérents d'association
*Gestion des congés des employés
*Gestion des notes de frais
*Gestion des charges sociales / TVA
*Enregistrement des paiements des salariés
*Comptabilité à double entrée, comptabilité générale et auxiliaire : facilement exportable vers d'autres solutions
*Agenda partagé
*Point de vente/Caisse enregistreuse
*Réalisation de sondages
*EMailing de masses vers les clients, prospect ou utilisateurs Dolibarr
*Suivi des marges
*Récolte de dons
*Rapports et statistiques
*Export PDF de tous les éléments (factures, propositions commerciales, commandes, bons expéditions, etc...)
*Imports et exports (CSV ou Excel).
*Connectivité LDAP
*De nombreuses autres fonctionnalités issues de modules officiels ou non (Gravatar, Google, ...)

NB : des modules dits "externes" sont commercialisés et maintenus par des développeurs indépendants, ils sont disponibles sur la plateforme Dolistore : https://www.dolistore.com

NB2: de part sa nature "open source" Dolibarr est adaptable à tous besoins. Il est fortement recommandé d'apporter ces modifications sous la forme de modules externes et de ne pas toucher au code source original (un risque important de bug en cascade peut arriver, et compliquera les mises à jour futures)

=[[File:Art.png]] Autres caractéristiques diverses=

*Application multi-utilisateurs avec différents niveaux de permissions par module.
*Gestion multi-devises.
*Application simple à utiliser.
*Facilement personnalisable (activation uniquement des modules désirés, champs personnalisés, choix du thème, options diverses...).
*Disponibilité d APIs web service ouvertes (SOAP et REST)

*Compatible avec les réglementations de nombreux pays (Gestion de la TVA Non perçue récupérable des DOM-TOM, TICKETBAI du Pays basque, Double tax fédéral/provinçal du Canada/Québec, Timbre fiscal tunisien, Tax GST Inde, ...)

La page suivante décrit les fonctionnalités non couvertes par Dolibarr:
[[Ce que ne fait pas Dolibarr]]

=[[File:Art.png]] Prérequis=
*Fonctionne avec PHP {{PHPMinVersion}} et MySQL {{MySqlMinVersion}} ou MariaDB {{MariaDBMinVersion}} ou PostgreSql {{PostgresMinVersion}}.
*Programme d'auto-installation pour for Windows, Debian/Ubuntu, Fedora/Redhat/OpenSuse ou package pour installation manuelle sur tout serveur dédié/mutualisé. Egalement compatible avec toute solution Cloud respectant les prérequis PHP, MySql ou PostgreSQL (Par exemple chez les fournisseurs Cloud suivant: https://saas.dolibarr.org).

=[[File:Art.png]] Dolibarr Releases=

*La liste des versions de Dolibarr est définie sur la page [[:Category:RoadMap]]

=[[File:Art.png]] Architecture =
<br />
[[File:Schéma client-serveur.png|none|thumb|927x927px|Présentation client / serveur]]

Langages et normes

2021-09-30T08:48:05Z

Quentic: /* Communication Logique métier - Données (ORM) */Correction d'erreur de frappe

[[en:Language_and_development_rules]]
[[de:Sprachen_und_Programmierregeln]]
[[es:Lenguaje_y_Normas_de_Desarrollo]]
[[zh:语言和开发规则]]


{{TemplateDocDev}}

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:

#Tous OS (Windows, Linux, MACOS...)
#PHP {{PHPMinVersion}} (Doit fonctionner sans aucun module PHP complémentaire hors les modules d'accès base de donnée).
#Mysql {{MySqlMinVersion}}

=Normes Copyright=

*Tout fichier PHP doit avoir un en-tête selon le masque suivant

<syntaxhighlight lang="PHP">
<?php
/* Copyright (C) YYYY John Doe <email@email.com>
*
* Licence information
*/
...
</syntaxhighlight>
Quand vous éditez un fichier existant du projet, ajouter une ligne Copyright sous celles existantes.

=Normes PHP=

==PHP==

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

*L'appel aux variables superglobales PHP doit passer par les opérateurs dédiés $_COOKIES, $_SERVER, $_ENV. Mais pour récupérer les contenus de $_GET ou $_POST, il faut passer par la fonction dolibarr [[Fonctions utiles Dolibarr|GETPOST()]] .

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

*Pas d'utilisation de la variable '''PHP_SELF'''. Utiliser à la place $_SERVER["PHP_SELF"]. Notez aussi que le framework Dolibarr passe une routine pour rendre plus sûr le contenu du $_SERVER["PHP_SELF"] (dans le fichier main.inc.php, donc avant tout traitement métier)

*Quand plusieurs variables doivent être initialisées avec la même valeur, il faut utiliser plusieurs instructions:

<syntaxhighlight lang="PHP">
$var1 = 1; $var2 = 1; $var3 = 1;
</syntaxhighlight>
plutôt que
<syntaxhighlight lang="PHP">
$var1 = $var2 = $var3 = 1;
</syntaxhighlight>
qui est moins performant.

*Les chaines doivent avoir les variables sorties de la chaine.

<syntaxhighlight lang="PHP">
print "Mon texte affiche ma ".$variable." !\n";
</syntaxhighlight>

*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

<syntaxhighlight lang="PHP">
/* 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;
}

</syntaxhighlight>

*Les fonctions doivent retourner une valeur 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).

*Le style de code a utiliser est le PSR-12 (https://www.php-fig.org/psr/psr-12/). Seules les règles "MUST" sont imposées. Notez aussi les points/exceptions suivants:
**La longueur des lignes: PSR-12 indique que la longueur des lignes a une limite "soft" à 120. Il est en effet préférable d'avoir de longues lignes de données de déclaration plutôt que de longues pages car ce code ne contient aucune logique intéressante ou utile, toutefois une limite "hard" a été instauré à '''1000''' caractères. Du code qui ira au delà provoquera des erreurs dans la plateforme d'Intégration Continue.
**Les tabulations sont acceptées : L'autre exception est qu'on ne remplace pas les tabulations systématiquement par des espaces. L'utilisation des tabulations simplifie la vie de certains développeurs. De plus, l'utilisation d'espaces rend certaines fonctions d'autoformatage défectueuses (comme sur certaines versions d'Eclipse, lors de copier-coller).
**Note 1: Les règles suivantes sont particulièrement importantes :
***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'''
**Note 2: Vous pouvez utiliser le fichier '''dev/setup/codesniffer/ruleset.xml''' comme fichier de contrôle pour vérifier votre style de code avec PHPCodeSniffer.
**Note 3: Vous pouvez utiliser le fichier '''dev/setup/eclipse/PSR-12 [built-in].xml''' comme fichier de règles de syntax pour configurer Eclipse.
**Note 4: Vous remarquerez que le code actuel ne suit pas forcément tout cela. La raison est historique. La règle fut instaurée en cours de route, aussi, si vous trouvez du code non respectueux de ce standard, n'hésitez pas à le corriger.

==Structures des classes et champs==

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

=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 <tt>llx_</tt>.

*Structure des tables.

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
- entity INTEGER default 1 that is id for the multicompany feature
- date_creation datetime that is the creation date
- 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 varchar(32) qui contiendra le code d'import YYYYMMDDHHMMSS si vous faites des imports en masse dans la table.
- status smallint pour stocker le status d'un object

Eventuellement
- fk_user_creat integer qui est l'id du user de création (fk_user_author also found)
- fk_user_modif integer qui est l'id du user de modification
- fk_user_valid integer qui est l'id du user de validation
- fk_soc integer qui est l'id du tiers (si applicable)

*Type des champs

Dans la pratique, afin d'être 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 (bigint éventuellement accepté pour les id des très grosses tables)
- smallint pour tout numérique entier de petite taille (comme pour stocker un code de status)
- double(24,8) pour tout montant
- double(6,3) pour les taux de tva
- real pour une quantité
- varchar pour une chaîne (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

==Clé primaire==
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.

==Clés étrangères==
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).

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

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

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

<syntaxhighlight lang="sql">
-- ===========================================================================
-- Copyright (C) 2008 Author <email@author.com>
--
-- This program 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 of the License, 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, see <http://www.gnu.org/licenses/>.
-- ===========================================================================

create table llx_matable
(
rowid integer AUTO_INCREMENT PRIMARY KEY,
field_one integer,
field_two integer NOT NULL,
fk_field integer,
field_date datetime,
tms timestamp
)ENGINE=innodb;
</syntaxhighlight>

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

<syntaxhighlight lang="sql">
-- ===========================================================================
-- Copyright (C) 2008 Author <email@author.com>
--
-- This program 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 of the License, 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, see <http://www.gnu.org/licenses/>.
-- ===========================================================================

ALTER TABLE llx_matable ADD UNIQUE uk_matable_field(field_one, field_two);

ALTER TABLE llx_matable ADD CONSTRAINT fk_matable_fk_field FOREIGN KEY (fk_field) REFERENCES llx_matablepere (rowid);
</syntaxhighlight>

==Règles de codage SQL==

*Utilisation des alias/nommage de champs

Dans le cas des select on pourra utiliser les alias pour simplifier l'écriture des requêtes:
<syntaxhighlight lang="sql">
select chp1, chpxxx2 as chp2 from table2 as t1, table2 as t2 where t1.chpx = t2.chpy
</syntaxhighlight>
Toutefois, il ne faut pas utiliser ces alias sur des requêtes update car non compatible avec mysql 3.1.

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

<syntaxhighlight lang="sql">
SELECT field_a, field_b, field_c FROM table_1 WHERE field_d = '$id'
</syntaxhighlight>

*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:
<syntaxhighlight lang="sql">
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')
</syntaxhighlight>

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, SYSDATE ou DATEDIFF sont interdites au sein des ordres SQL. S'il faut saisir la date du moment dans un champ, la valeur doit venir du PHP, par exemple par la fonction dol_now(), 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 et ne pas dépendre du TimeZone de la base de donnée.

Par exemple, on ne fera pas:
<syntaxhighlight lang="PHP">
$sql="SELECT rowid FROM table where datefield = NOW()";
</syntaxhighlight>
mais:
<syntaxhighlight lang="PHP">
$sql="SELECT rowid FROM table where datefield = '".$this->db->idate(dol_now())."'";
</syntaxhighlight>

Par exemple, on ne fera pas:
<syntaxhighlight lang="PHP">
$sql="SELECT rowid FROM table where DATEDIFF(table.datefield, NOW()) > 7";
</syntaxhighlight>
mais:
<syntaxhighlight lang="PHP">
$sql="SELECT rowid FROM table where datefield < '".$this->db->idate(dol_now() - (7 * 24 * 3600))."'";
</syntaxhighlight>

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.

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

*Les tables doivent être au format InnoDB.

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.

*Dolibarr DOIT fonctionner même avec les options '''strict''' de Mysql active.

Pour l'activer (fortement recommandé en développement), ajouter la ligne suivante dans le fichier config du serveur Mysql (my.cnf ou my.ini)
{{MySqlStrictMode}}

==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 :
<syntaxhighlight lang="sql">
UPDATE table_taget as target, table_source as source SET fieldtarget=source.fieldsource
WHERE source.rowid=target.rowid;
</syntaxhighlight>

Syntax PgSQL:
<syntaxhighlight lang="sql">
UPDATE table_taget as target SET fieldtarget=source.fieldsource
FROM table_source as source WHERE source.rowid=target.rowid;
</syntaxhighlight>

Il n'en existe pas dans Dolibarr, mais pour vos modules Vous devriez faire tel que :
<syntaxhighlight lang="PHP">
if ($this->db->type=='pgsql') {
$sql="UPDATE table_taget as target SET fieldtarget=source.fieldsource
FROM table_source as source WHERE source.rowid=target.rowid";
} else {
$sql= "UPDATE table_taget as target, table_source as source SET fieldtarget=source.fieldsource
WHERE source.rowid=target.rowid";
}
</syntaxhighlight>

=Normes HTML=

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

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

Par example:
<syntaxhighlight lang="PHP">
print '<a href="'.dol_buildpath('/monrep/mapage.php').'">'.img_picto('Texte alt','nompictopng','').'</a>';
</syntaxhighlight>

*Les tables HTML doivent avoir des colonnes sans valeurs forcées, excepté pour les colonnes qui contiennent une information dont la longueur est non variable. Par exemple, une colonne avec un picto peut être 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 quelle que 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"

<syntaxhighlight lang="PHP">
if ($conf->use_javascript_ajax) {
... // Le code php qui génère du javascript est ici
}
</syntaxhighlight>

*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 '''htdocs/modulebuilder/templates'''.

Par exemple:
*1 fichier qui sert d'exemple de descripteur de module: '''myModule.class.php'''
*1 fichier qui sert d'exemple de code pour faire une nouvelle classe: '''skeleton_class.class.php'''
*1 fichier qui sert d'exemple de code pour faire une nouvelle page: '''skeleton_page.php'''
*1 fichier 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 ([[Module ModuleBuilder]]) qui est décrit dans la chapitre de développement de module Dolibarr pour accélérer vos développements.

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

*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 <b>locale du serveur PHP</b>. Cela ne concerne pas les dates mises à jour automatiquement par la base (champ '''tms''' en base).

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

*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

==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
<syntaxhighlight lang="PHP">
print 239.2 - 229.3 - 9.9;
</syntaxhighlight>
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).
<syntaxhighlight lang="PHP">
print price2num(239.2 - 229.3 - 9.9, 'MT');
</syntaxhighlight>
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).

==Comparer la version==

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

<syntaxhighlight lang="PHP">
$version=preg_split('/[\.-]/',DOL_VERSION);
if (versioncompare($version,array(5,0,-4)) >= 0) { //mycode for 5.0 only; } // For dolibarr 5.0.* (the -4 means we include also alpha, beta, rc and rcX)
</syntaxhighlight>

Mais cette solution requiert de faire un include avoir la fonction versioncompare. Une alternative est d'utiliser le test suivant:
<syntaxhighlight lang="PHP">
if ((float) DOL_VERSION >= 5.0) { //mycode for 5.0 only; } // For dolibarr 5.0.*
</syntaxhighlight>

==Logs==
Ajouter des traces dans votre code avec la fonction
<syntaxhighlight lang="PHP">
dol_syslog($yourmessage, LOG_INFO|LOG_DEBUG|LOG_WARNING|LOG_ERR);
</syntaxhighlight>

==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:
<syntaxhighlight lang="PHP">
$mymoduledir=DOL_DATA_ROOT.'/monmodule';
dol_mkdir($mymoduledir);
</syntaxhighlight>

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é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 conformes à 100% dans l'esprit mais pas dans la syntaxe, ceci afin d’être compatible avec la plus large plage possible de versions de PHP.

==Design patterns d'entreprises (Martin Fowler)==

===Mode d'organisation du code===
[[wikipedia:Martin_Fowler|Martin Fowler]] a identifié 3 méthodes d'organisation du code appelées '''patterns''' ('''motifs'''):

*Le '''Transaction Script''' (Le code est linéaire 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 les parties métiers.

*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ées.

-> 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 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éduites 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/).

*Le '''Active Record'''

Identique au précédent, mais on se permet d'ajouter quelques fonctions métiers sur la classe, à condition que ces fonctions soient bien propres à la table ou à la notion métier portée 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éveloppement.

*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.
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ée ne rejoignant pas les promesses de la théorie).

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

==Design Pattern d'Interface Graphique (MVC)==
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.

-> Dolibarr utilise le Design Pattern '''MVC'''. La partie M est matérialisée par une classe DAO contenant les méthode CRUD (Create-Read-Update-Delete) d'accès à la table.
Beaucoup de frameworks ont fait le choix de mettre la partie de code C (Controller) et la partie de code du V (vue) dans des fichiers, voir même répertoires séparés. La maintenance semble plus aisé sur la papier, en pratique, il faut sans arrêt jonglé entre n fichiers, le C étant fortement lié au V. Aussi dans Dolibarr, la séparation est faite par une simple section de commentaire. La partie de code C (Controller) est donc le code qui se trouve sont la balise
<pre>
/*
* Actions
*/
</pre>
Elle est suivi par la partie de code V (Vue), bien séparé du C par la balise
<pre>
/*
* View
*/
</pre>

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

==Design Pattern de Vue - Présentation==
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 de templates PHP (fichier .tpl.php) qui restent le plus simple, le plus universel, le plus évolutif et le plus performant, 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'expérience et le constat "sur le terrain" d'un meilleur rendement de productivité qui a motivé l'abandon des frameworks de Présentation externes au profit du framework PHP.

Langages et normes

2021-09-30T08:45:23Z

Quentic: /* Mode d'organisation du code */

[[en:Language_and_development_rules]]
[[de:Sprachen_und_Programmierregeln]]
[[es:Lenguaje_y_Normas_de_Desarrollo]]
[[zh:语言和开发规则]]


{{TemplateDocDev}}

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:

#Tous OS (Windows, Linux, MACOS...)
#PHP {{PHPMinVersion}} (Doit fonctionner sans aucun module PHP complémentaire hors les modules d'accès base de donnée).
#Mysql {{MySqlMinVersion}}

=Normes Copyright=

*Tout fichier PHP doit avoir un en-tête selon le masque suivant

<syntaxhighlight lang="PHP">
<?php
/* Copyright (C) YYYY John Doe <email@email.com>
*
* Licence information
*/
...
</syntaxhighlight>
Quand vous éditez un fichier existant du projet, ajouter une ligne Copyright sous celles existantes.

=Normes PHP=

==PHP==

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

*L'appel aux variables superglobales PHP doit passer par les opérateurs dédiés $_COOKIES, $_SERVER, $_ENV. Mais pour récupérer les contenus de $_GET ou $_POST, il faut passer par la fonction dolibarr [[Fonctions utiles Dolibarr|GETPOST()]] .

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

*Pas d'utilisation de la variable '''PHP_SELF'''. Utiliser à la place $_SERVER["PHP_SELF"]. Notez aussi que le framework Dolibarr passe une routine pour rendre plus sûr le contenu du $_SERVER["PHP_SELF"] (dans le fichier main.inc.php, donc avant tout traitement métier)

*Quand plusieurs variables doivent être initialisées avec la même valeur, il faut utiliser plusieurs instructions:

<syntaxhighlight lang="PHP">
$var1 = 1; $var2 = 1; $var3 = 1;
</syntaxhighlight>
plutôt que
<syntaxhighlight lang="PHP">
$var1 = $var2 = $var3 = 1;
</syntaxhighlight>
qui est moins performant.

*Les chaines doivent avoir les variables sorties de la chaine.

<syntaxhighlight lang="PHP">
print "Mon texte affiche ma ".$variable." !\n";
</syntaxhighlight>

*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

<syntaxhighlight lang="PHP">
/* 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;
}

</syntaxhighlight>

*Les fonctions doivent retourner une valeur 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).

*Le style de code a utiliser est le PSR-12 (https://www.php-fig.org/psr/psr-12/). Seules les règles "MUST" sont imposées. Notez aussi les points/exceptions suivants:
**La longueur des lignes: PSR-12 indique que la longueur des lignes a une limite "soft" à 120. Il est en effet préférable d'avoir de longues lignes de données de déclaration plutôt que de longues pages car ce code ne contient aucune logique intéressante ou utile, toutefois une limite "hard" a été instauré à '''1000''' caractères. Du code qui ira au delà provoquera des erreurs dans la plateforme d'Intégration Continue.
**Les tabulations sont acceptées : L'autre exception est qu'on ne remplace pas les tabulations systématiquement par des espaces. L'utilisation des tabulations simplifie la vie de certains développeurs. De plus, l'utilisation d'espaces rend certaines fonctions d'autoformatage défectueuses (comme sur certaines versions d'Eclipse, lors de copier-coller).
**Note 1: Les règles suivantes sont particulièrement importantes :
***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'''
**Note 2: Vous pouvez utiliser le fichier '''dev/setup/codesniffer/ruleset.xml''' comme fichier de contrôle pour vérifier votre style de code avec PHPCodeSniffer.
**Note 3: Vous pouvez utiliser le fichier '''dev/setup/eclipse/PSR-12 [built-in].xml''' comme fichier de règles de syntax pour configurer Eclipse.
**Note 4: Vous remarquerez que le code actuel ne suit pas forcément tout cela. La raison est historique. La règle fut instaurée en cours de route, aussi, si vous trouvez du code non respectueux de ce standard, n'hésitez pas à le corriger.

==Structures des classes et champs==

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

=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 <tt>llx_</tt>.

*Structure des tables.

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
- entity INTEGER default 1 that is id for the multicompany feature
- date_creation datetime that is the creation date
- 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 varchar(32) qui contiendra le code d'import YYYYMMDDHHMMSS si vous faites des imports en masse dans la table.
- status smallint pour stocker le status d'un object

Eventuellement
- fk_user_creat integer qui est l'id du user de création (fk_user_author also found)
- fk_user_modif integer qui est l'id du user de modification
- fk_user_valid integer qui est l'id du user de validation
- fk_soc integer qui est l'id du tiers (si applicable)

*Type des champs

Dans la pratique, afin d'être 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 (bigint éventuellement accepté pour les id des très grosses tables)
- smallint pour tout numérique entier de petite taille (comme pour stocker un code de status)
- double(24,8) pour tout montant
- double(6,3) pour les taux de tva
- real pour une quantité
- varchar pour une chaîne (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

==Clé primaire==
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.

==Clés étrangères==
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).

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

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

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

<syntaxhighlight lang="sql">
-- ===========================================================================
-- Copyright (C) 2008 Author <email@author.com>
--
-- This program 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 of the License, 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, see <http://www.gnu.org/licenses/>.
-- ===========================================================================

create table llx_matable
(
rowid integer AUTO_INCREMENT PRIMARY KEY,
field_one integer,
field_two integer NOT NULL,
fk_field integer,
field_date datetime,
tms timestamp
)ENGINE=innodb;
</syntaxhighlight>

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

<syntaxhighlight lang="sql">
-- ===========================================================================
-- Copyright (C) 2008 Author <email@author.com>
--
-- This program 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 of the License, 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, see <http://www.gnu.org/licenses/>.
-- ===========================================================================

ALTER TABLE llx_matable ADD UNIQUE uk_matable_field(field_one, field_two);

ALTER TABLE llx_matable ADD CONSTRAINT fk_matable_fk_field FOREIGN KEY (fk_field) REFERENCES llx_matablepere (rowid);
</syntaxhighlight>

==Règles de codage SQL==

*Utilisation des alias/nommage de champs

Dans le cas des select on pourra utiliser les alias pour simplifier l'écriture des requêtes:
<syntaxhighlight lang="sql">
select chp1, chpxxx2 as chp2 from table2 as t1, table2 as t2 where t1.chpx = t2.chpy
</syntaxhighlight>
Toutefois, il ne faut pas utiliser ces alias sur des requêtes update car non compatible avec mysql 3.1.

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

<syntaxhighlight lang="sql">
SELECT field_a, field_b, field_c FROM table_1 WHERE field_d = '$id'
</syntaxhighlight>

*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:
<syntaxhighlight lang="sql">
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')
</syntaxhighlight>

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, SYSDATE ou DATEDIFF sont interdites au sein des ordres SQL. S'il faut saisir la date du moment dans un champ, la valeur doit venir du PHP, par exemple par la fonction dol_now(), 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 et ne pas dépendre du TimeZone de la base de donnée.

Par exemple, on ne fera pas:
<syntaxhighlight lang="PHP">
$sql="SELECT rowid FROM table where datefield = NOW()";
</syntaxhighlight>
mais:
<syntaxhighlight lang="PHP">
$sql="SELECT rowid FROM table where datefield = '".$this->db->idate(dol_now())."'";
</syntaxhighlight>

Par exemple, on ne fera pas:
<syntaxhighlight lang="PHP">
$sql="SELECT rowid FROM table where DATEDIFF(table.datefield, NOW()) > 7";
</syntaxhighlight>
mais:
<syntaxhighlight lang="PHP">
$sql="SELECT rowid FROM table where datefield < '".$this->db->idate(dol_now() - (7 * 24 * 3600))."'";
</syntaxhighlight>

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.

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

*Les tables doivent être au format InnoDB.

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.

*Dolibarr DOIT fonctionner même avec les options '''strict''' de Mysql active.

Pour l'activer (fortement recommandé en développement), ajouter la ligne suivante dans le fichier config du serveur Mysql (my.cnf ou my.ini)
{{MySqlStrictMode}}

==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 :
<syntaxhighlight lang="sql">
UPDATE table_taget as target, table_source as source SET fieldtarget=source.fieldsource
WHERE source.rowid=target.rowid;
</syntaxhighlight>

Syntax PgSQL:
<syntaxhighlight lang="sql">
UPDATE table_taget as target SET fieldtarget=source.fieldsource
FROM table_source as source WHERE source.rowid=target.rowid;
</syntaxhighlight>

Il n'en existe pas dans Dolibarr, mais pour vos modules Vous devriez faire tel que :
<syntaxhighlight lang="PHP">
if ($this->db->type=='pgsql') {
$sql="UPDATE table_taget as target SET fieldtarget=source.fieldsource
FROM table_source as source WHERE source.rowid=target.rowid";
} else {
$sql= "UPDATE table_taget as target, table_source as source SET fieldtarget=source.fieldsource
WHERE source.rowid=target.rowid";
}
</syntaxhighlight>

=Normes HTML=

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

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

Par example:
<syntaxhighlight lang="PHP">
print '<a href="'.dol_buildpath('/monrep/mapage.php').'">'.img_picto('Texte alt','nompictopng','').'</a>';
</syntaxhighlight>

*Les tables HTML doivent avoir des colonnes sans valeurs forcées, excepté pour les colonnes qui contiennent une information dont la longueur est non variable. Par exemple, une colonne avec un picto peut être 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 quelle que 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"

<syntaxhighlight lang="PHP">
if ($conf->use_javascript_ajax) {
... // Le code php qui génère du javascript est ici
}
</syntaxhighlight>

*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 '''htdocs/modulebuilder/templates'''.

Par exemple:
*1 fichier qui sert d'exemple de descripteur de module: '''myModule.class.php'''
*1 fichier qui sert d'exemple de code pour faire une nouvelle classe: '''skeleton_class.class.php'''
*1 fichier qui sert d'exemple de code pour faire une nouvelle page: '''skeleton_page.php'''
*1 fichier 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 ([[Module ModuleBuilder]]) qui est décrit dans la chapitre de développement de module Dolibarr pour accélérer vos développements.

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

*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 <b>locale du serveur PHP</b>. Cela ne concerne pas les dates mises à jour automatiquement par la base (champ '''tms''' en base).

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

*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

==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
<syntaxhighlight lang="PHP">
print 239.2 - 229.3 - 9.9;
</syntaxhighlight>
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).
<syntaxhighlight lang="PHP">
print price2num(239.2 - 229.3 - 9.9, 'MT');
</syntaxhighlight>
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).

==Comparer la version==

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

<syntaxhighlight lang="PHP">
$version=preg_split('/[\.-]/',DOL_VERSION);
if (versioncompare($version,array(5,0,-4)) >= 0) { //mycode for 5.0 only; } // For dolibarr 5.0.* (the -4 means we include also alpha, beta, rc and rcX)
</syntaxhighlight>

Mais cette solution requiert de faire un include avoir la fonction versioncompare. Une alternative est d'utiliser le test suivant:
<syntaxhighlight lang="PHP">
if ((float) DOL_VERSION >= 5.0) { //mycode for 5.0 only; } // For dolibarr 5.0.*
</syntaxhighlight>

==Logs==
Ajouter des traces dans votre code avec la fonction
<syntaxhighlight lang="PHP">
dol_syslog($yourmessage, LOG_INFO|LOG_DEBUG|LOG_WARNING|LOG_ERR);
</syntaxhighlight>

==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:
<syntaxhighlight lang="PHP">
$mymoduledir=DOL_DATA_ROOT.'/monmodule';
dol_mkdir($mymoduledir);
</syntaxhighlight>

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é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 conformes à 100% dans l'esprit mais pas dans la syntaxe, ceci afin d’être compatible avec la plus large plage possible de versions de PHP.

==Design patterns d'entreprises (Martin Fowler)==

===Mode d'organisation du code===
[[wikipedia:Martin_Fowler|Martin Fowler]] a identifié 3 méthodes d'organisation du code appelées '''patterns''' ('''motifs'''):

*Le '''Transaction Script''' (Le code est linéaire 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 les parties métiers.

*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ées.

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

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

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

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

==Design Pattern d'Interface Graphique (MVC)==
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.

-> Dolibarr utilise le Design Pattern '''MVC'''. La partie M est matérialisée par une classe DAO contenant les méthode CRUD (Create-Read-Update-Delete) d'accès à la table.
Beaucoup de frameworks ont fait le choix de mettre la partie de code C (Controller) et la partie de code du V (vue) dans des fichiers, voir même répertoires séparés. La maintenance semble plus aisé sur la papier, en pratique, il faut sans arrêt jonglé entre n fichiers, le C étant fortement lié au V. Aussi dans Dolibarr, la séparation est faite par une simple section de commentaire. La partie de code C (Controller) est donc le code qui se trouve sont la balise
<pre>
/*
* Actions
*/
</pre>
Elle est suivi par la partie de code V (Vue), bien séparé du C par la balise
<pre>
/*
* View
*/
</pre>

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

==Design Pattern de Vue - Présentation==
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 de templates PHP (fichier .tpl.php) qui restent le plus simple, le plus universel, le plus évolutif et le plus performant, 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'expérience et le constat "sur le terrain" d'un meilleur rendement de productivité qui a motivé l'abandon des frameworks de Présentation externes au profit du framework PHP.

Langages et normes

2021-09-30T08:44:10Z

Quentic: /* Design patterns de Création (GoF) */Correction d'erreur de frappe

[[en:Language_and_development_rules]]
[[de:Sprachen_und_Programmierregeln]]
[[es:Lenguaje_y_Normas_de_Desarrollo]]
[[zh:语言和开发规则]]


{{TemplateDocDev}}

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:

#Tous OS (Windows, Linux, MACOS...)
#PHP {{PHPMinVersion}} (Doit fonctionner sans aucun module PHP complémentaire hors les modules d'accès base de donnée).
#Mysql {{MySqlMinVersion}}

=Normes Copyright=

*Tout fichier PHP doit avoir un en-tête selon le masque suivant

<syntaxhighlight lang="PHP">
<?php
/* Copyright (C) YYYY John Doe <email@email.com>
*
* Licence information
*/
...
</syntaxhighlight>
Quand vous éditez un fichier existant du projet, ajouter une ligne Copyright sous celles existantes.

=Normes PHP=

==PHP==

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

*L'appel aux variables superglobales PHP doit passer par les opérateurs dédiés $_COOKIES, $_SERVER, $_ENV. Mais pour récupérer les contenus de $_GET ou $_POST, il faut passer par la fonction dolibarr [[Fonctions utiles Dolibarr|GETPOST()]] .

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

*Pas d'utilisation de la variable '''PHP_SELF'''. Utiliser à la place $_SERVER["PHP_SELF"]. Notez aussi que le framework Dolibarr passe une routine pour rendre plus sûr le contenu du $_SERVER["PHP_SELF"] (dans le fichier main.inc.php, donc avant tout traitement métier)

*Quand plusieurs variables doivent être initialisées avec la même valeur, il faut utiliser plusieurs instructions:

<syntaxhighlight lang="PHP">
$var1 = 1; $var2 = 1; $var3 = 1;
</syntaxhighlight>
plutôt que
<syntaxhighlight lang="PHP">
$var1 = $var2 = $var3 = 1;
</syntaxhighlight>
qui est moins performant.

*Les chaines doivent avoir les variables sorties de la chaine.

<syntaxhighlight lang="PHP">
print "Mon texte affiche ma ".$variable." !\n";
</syntaxhighlight>

*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

<syntaxhighlight lang="PHP">
/* 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;
}

</syntaxhighlight>

*Les fonctions doivent retourner une valeur 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).

*Le style de code a utiliser est le PSR-12 (https://www.php-fig.org/psr/psr-12/). Seules les règles "MUST" sont imposées. Notez aussi les points/exceptions suivants:
**La longueur des lignes: PSR-12 indique que la longueur des lignes a une limite "soft" à 120. Il est en effet préférable d'avoir de longues lignes de données de déclaration plutôt que de longues pages car ce code ne contient aucune logique intéressante ou utile, toutefois une limite "hard" a été instauré à '''1000''' caractères. Du code qui ira au delà provoquera des erreurs dans la plateforme d'Intégration Continue.
**Les tabulations sont acceptées : L'autre exception est qu'on ne remplace pas les tabulations systématiquement par des espaces. L'utilisation des tabulations simplifie la vie de certains développeurs. De plus, l'utilisation d'espaces rend certaines fonctions d'autoformatage défectueuses (comme sur certaines versions d'Eclipse, lors de copier-coller).
**Note 1: Les règles suivantes sont particulièrement importantes :
***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'''
**Note 2: Vous pouvez utiliser le fichier '''dev/setup/codesniffer/ruleset.xml''' comme fichier de contrôle pour vérifier votre style de code avec PHPCodeSniffer.
**Note 3: Vous pouvez utiliser le fichier '''dev/setup/eclipse/PSR-12 [built-in].xml''' comme fichier de règles de syntax pour configurer Eclipse.
**Note 4: Vous remarquerez que le code actuel ne suit pas forcément tout cela. La raison est historique. La règle fut instaurée en cours de route, aussi, si vous trouvez du code non respectueux de ce standard, n'hésitez pas à le corriger.

==Structures des classes et champs==

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

=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 <tt>llx_</tt>.

*Structure des tables.

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
- entity INTEGER default 1 that is id for the multicompany feature
- date_creation datetime that is the creation date
- 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 varchar(32) qui contiendra le code d'import YYYYMMDDHHMMSS si vous faites des imports en masse dans la table.
- status smallint pour stocker le status d'un object

Eventuellement
- fk_user_creat integer qui est l'id du user de création (fk_user_author also found)
- fk_user_modif integer qui est l'id du user de modification
- fk_user_valid integer qui est l'id du user de validation
- fk_soc integer qui est l'id du tiers (si applicable)

*Type des champs

Dans la pratique, afin d'être 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 (bigint éventuellement accepté pour les id des très grosses tables)
- smallint pour tout numérique entier de petite taille (comme pour stocker un code de status)
- double(24,8) pour tout montant
- double(6,3) pour les taux de tva
- real pour une quantité
- varchar pour une chaîne (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

==Clé primaire==
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.

==Clés étrangères==
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).

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

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

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

<syntaxhighlight lang="sql">
-- ===========================================================================
-- Copyright (C) 2008 Author <email@author.com>
--
-- This program 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 of the License, 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, see <http://www.gnu.org/licenses/>.
-- ===========================================================================

create table llx_matable
(
rowid integer AUTO_INCREMENT PRIMARY KEY,
field_one integer,
field_two integer NOT NULL,
fk_field integer,
field_date datetime,
tms timestamp
)ENGINE=innodb;
</syntaxhighlight>

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

<syntaxhighlight lang="sql">
-- ===========================================================================
-- Copyright (C) 2008 Author <email@author.com>
--
-- This program 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 of the License, 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, see <http://www.gnu.org/licenses/>.
-- ===========================================================================

ALTER TABLE llx_matable ADD UNIQUE uk_matable_field(field_one, field_two);

ALTER TABLE llx_matable ADD CONSTRAINT fk_matable_fk_field FOREIGN KEY (fk_field) REFERENCES llx_matablepere (rowid);
</syntaxhighlight>

==Règles de codage SQL==

*Utilisation des alias/nommage de champs

Dans le cas des select on pourra utiliser les alias pour simplifier l'écriture des requêtes:
<syntaxhighlight lang="sql">
select chp1, chpxxx2 as chp2 from table2 as t1, table2 as t2 where t1.chpx = t2.chpy
</syntaxhighlight>
Toutefois, il ne faut pas utiliser ces alias sur des requêtes update car non compatible avec mysql 3.1.

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

<syntaxhighlight lang="sql">
SELECT field_a, field_b, field_c FROM table_1 WHERE field_d = '$id'
</syntaxhighlight>

*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:
<syntaxhighlight lang="sql">
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')
</syntaxhighlight>

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, SYSDATE ou DATEDIFF sont interdites au sein des ordres SQL. S'il faut saisir la date du moment dans un champ, la valeur doit venir du PHP, par exemple par la fonction dol_now(), 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 et ne pas dépendre du TimeZone de la base de donnée.

Par exemple, on ne fera pas:
<syntaxhighlight lang="PHP">
$sql="SELECT rowid FROM table where datefield = NOW()";
</syntaxhighlight>
mais:
<syntaxhighlight lang="PHP">
$sql="SELECT rowid FROM table where datefield = '".$this->db->idate(dol_now())."'";
</syntaxhighlight>

Par exemple, on ne fera pas:
<syntaxhighlight lang="PHP">
$sql="SELECT rowid FROM table where DATEDIFF(table.datefield, NOW()) > 7";
</syntaxhighlight>
mais:
<syntaxhighlight lang="PHP">
$sql="SELECT rowid FROM table where datefield < '".$this->db->idate(dol_now() - (7 * 24 * 3600))."'";
</syntaxhighlight>

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.

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

*Les tables doivent être au format InnoDB.

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.

*Dolibarr DOIT fonctionner même avec les options '''strict''' de Mysql active.

Pour l'activer (fortement recommandé en développement), ajouter la ligne suivante dans le fichier config du serveur Mysql (my.cnf ou my.ini)
{{MySqlStrictMode}}

==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 :
<syntaxhighlight lang="sql">
UPDATE table_taget as target, table_source as source SET fieldtarget=source.fieldsource
WHERE source.rowid=target.rowid;
</syntaxhighlight>

Syntax PgSQL:
<syntaxhighlight lang="sql">
UPDATE table_taget as target SET fieldtarget=source.fieldsource
FROM table_source as source WHERE source.rowid=target.rowid;
</syntaxhighlight>

Il n'en existe pas dans Dolibarr, mais pour vos modules Vous devriez faire tel que :
<syntaxhighlight lang="PHP">
if ($this->db->type=='pgsql') {
$sql="UPDATE table_taget as target SET fieldtarget=source.fieldsource
FROM table_source as source WHERE source.rowid=target.rowid";
} else {
$sql= "UPDATE table_taget as target, table_source as source SET fieldtarget=source.fieldsource
WHERE source.rowid=target.rowid";
}
</syntaxhighlight>

=Normes HTML=

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

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

Par example:
<syntaxhighlight lang="PHP">
print '<a href="'.dol_buildpath('/monrep/mapage.php').'">'.img_picto('Texte alt','nompictopng','').'</a>';
</syntaxhighlight>

*Les tables HTML doivent avoir des colonnes sans valeurs forcées, excepté pour les colonnes qui contiennent une information dont la longueur est non variable. Par exemple, une colonne avec un picto peut être 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 quelle que 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"

<syntaxhighlight lang="PHP">
if ($conf->use_javascript_ajax) {
... // Le code php qui génère du javascript est ici
}
</syntaxhighlight>

*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 '''htdocs/modulebuilder/templates'''.

Par exemple:
*1 fichier qui sert d'exemple de descripteur de module: '''myModule.class.php'''
*1 fichier qui sert d'exemple de code pour faire une nouvelle classe: '''skeleton_class.class.php'''
*1 fichier qui sert d'exemple de code pour faire une nouvelle page: '''skeleton_page.php'''
*1 fichier 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 ([[Module ModuleBuilder]]) qui est décrit dans la chapitre de développement de module Dolibarr pour accélérer vos développements.

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

*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 <b>locale du serveur PHP</b>. Cela ne concerne pas les dates mises à jour automatiquement par la base (champ '''tms''' en base).

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

*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

==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
<syntaxhighlight lang="PHP">
print 239.2 - 229.3 - 9.9;
</syntaxhighlight>
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).
<syntaxhighlight lang="PHP">
print price2num(239.2 - 229.3 - 9.9, 'MT');
</syntaxhighlight>
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).

==Comparer la version==

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

<syntaxhighlight lang="PHP">
$version=preg_split('/[\.-]/',DOL_VERSION);
if (versioncompare($version,array(5,0,-4)) >= 0) { //mycode for 5.0 only; } // For dolibarr 5.0.* (the -4 means we include also alpha, beta, rc and rcX)
</syntaxhighlight>

Mais cette solution requiert de faire un include avoir la fonction versioncompare. Une alternative est d'utiliser le test suivant:
<syntaxhighlight lang="PHP">
if ((float) DOL_VERSION >= 5.0) { //mycode for 5.0 only; } // For dolibarr 5.0.*
</syntaxhighlight>

==Logs==
Ajouter des traces dans votre code avec la fonction
<syntaxhighlight lang="PHP">
dol_syslog($yourmessage, LOG_INFO|LOG_DEBUG|LOG_WARNING|LOG_ERR);
</syntaxhighlight>

==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:
<syntaxhighlight lang="PHP">
$mymoduledir=DOL_DATA_ROOT.'/monmodule';
dol_mkdir($mymoduledir);
</syntaxhighlight>

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é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 conformes à 100% dans l'esprit mais pas dans la syntaxe, ceci afin d’être compatible avec la plus large plage possible de versions de PHP.

==Design patterns d'entreprises (Martin Fowler)==

===Mode d'organisation du code===
[[wikipedia:Martin_Fowler|Martin Fowler]] a identifié 3 méthodes d'organisation du code appelées '''patterns''' ('''motifs'''):

*Le '''Transaction Script''' (Le code est linéaire 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 les parties métiers.

*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ées.

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

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

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

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

==Design Pattern d'Interface Graphique (MVC)==
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.

-> Dolibarr utilise le Design Pattern '''MVC'''. La partie M est matérialisée par une classe DAO contenant les méthode CRUD (Create-Read-Update-Delete) d'accès à la table.
Beaucoup de frameworks ont fait le choix de mettre la partie de code C (Controller) et la partie de code du V (vue) dans des fichiers, voir même répertoires séparés. La maintenance semble plus aisé sur la papier, en pratique, il faut sans arrêt jonglé entre n fichiers, le C étant fortement lié au V. Aussi dans Dolibarr, la séparation est faite par une simple section de commentaire. La partie de code C (Controller) est donc le code qui se trouve sont la balise
<pre>
/*
* Actions
*/
</pre>
Elle est suivi par la partie de code V (Vue), bien séparé du C par la balise
<pre>
/*
* View
*/
</pre>

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

==Design Pattern de Vue - Présentation==
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 de templates PHP (fichier .tpl.php) qui restent le plus simple, le plus universel, le plus évolutif et le plus performant, 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'expérience et le constat "sur le terrain" d'un meilleur rendement de productivité qui a motivé l'abandon des frameworks de Présentation externes au profit du framework PHP.

Langages et normes

2021-09-30T08:40:23Z

Quentic: Correction d'erreur de frappe

[[en:Language_and_development_rules]]
[[de:Sprachen_und_Programmierregeln]]
[[es:Lenguaje_y_Normas_de_Desarrollo]]
[[zh:语言和开发规则]]


{{TemplateDocDev}}

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:

#Tous OS (Windows, Linux, MACOS...)
#PHP {{PHPMinVersion}} (Doit fonctionner sans aucun module PHP complémentaire hors les modules d'accès base de donnée).
#Mysql {{MySqlMinVersion}}

=Normes Copyright=

*Tout fichier PHP doit avoir un en-tête selon le masque suivant

<syntaxhighlight lang="PHP">
<?php
/* Copyright (C) YYYY John Doe <email@email.com>
*
* Licence information
*/
...
</syntaxhighlight>
Quand vous éditez un fichier existant du projet, ajouter une ligne Copyright sous celles existantes.

=Normes PHP=

==PHP==

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

*L'appel aux variables superglobales PHP doit passer par les opérateurs dédiés $_COOKIES, $_SERVER, $_ENV. Mais pour récupérer les contenus de $_GET ou $_POST, il faut passer par la fonction dolibarr [[Fonctions utiles Dolibarr|GETPOST()]] .

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

*Pas d'utilisation de la variable '''PHP_SELF'''. Utiliser à la place $_SERVER["PHP_SELF"]. Notez aussi que le framework Dolibarr passe une routine pour rendre plus sûr le contenu du $_SERVER["PHP_SELF"] (dans le fichier main.inc.php, donc avant tout traitement métier)

*Quand plusieurs variables doivent être initialisées avec la même valeur, il faut utiliser plusieurs instructions:

<syntaxhighlight lang="PHP">
$var1 = 1; $var2 = 1; $var3 = 1;
</syntaxhighlight>
plutôt que
<syntaxhighlight lang="PHP">
$var1 = $var2 = $var3 = 1;
</syntaxhighlight>
qui est moins performant.

*Les chaines doivent avoir les variables sorties de la chaine.

<syntaxhighlight lang="PHP">
print "Mon texte affiche ma ".$variable." !\n";
</syntaxhighlight>

*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

<syntaxhighlight lang="PHP">
/* 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;
}

</syntaxhighlight>

*Les fonctions doivent retourner une valeur 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).

*Le style de code a utiliser est le PSR-12 (https://www.php-fig.org/psr/psr-12/). Seules les règles "MUST" sont imposées. Notez aussi les points/exceptions suivants:
**La longueur des lignes: PSR-12 indique que la longueur des lignes a une limite "soft" à 120. Il est en effet préférable d'avoir de longues lignes de données de déclaration plutôt que de longues pages car ce code ne contient aucune logique intéressante ou utile, toutefois une limite "hard" a été instauré à '''1000''' caractères. Du code qui ira au delà provoquera des erreurs dans la plateforme d'Intégration Continue.
**Les tabulations sont acceptées : L'autre exception est qu'on ne remplace pas les tabulations systématiquement par des espaces. L'utilisation des tabulations simplifie la vie de certains développeurs. De plus, l'utilisation d'espaces rend certaines fonctions d'autoformatage défectueuses (comme sur certaines versions d'Eclipse, lors de copier-coller).
**Note 1: Les règles suivantes sont particulièrement importantes :
***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'''
**Note 2: Vous pouvez utiliser le fichier '''dev/setup/codesniffer/ruleset.xml''' comme fichier de contrôle pour vérifier votre style de code avec PHPCodeSniffer.
**Note 3: Vous pouvez utiliser le fichier '''dev/setup/eclipse/PSR-12 [built-in].xml''' comme fichier de règles de syntax pour configurer Eclipse.
**Note 4: Vous remarquerez que le code actuel ne suit pas forcément tout cela. La raison est historique. La règle fut instaurée en cours de route, aussi, si vous trouvez du code non respectueux de ce standard, n'hésitez pas à le corriger.

==Structures des classes et champs==

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

=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 <tt>llx_</tt>.

*Structure des tables.

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
- entity INTEGER default 1 that is id for the multicompany feature
- date_creation datetime that is the creation date
- 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 varchar(32) qui contiendra le code d'import YYYYMMDDHHMMSS si vous faites des imports en masse dans la table.
- status smallint pour stocker le status d'un object

Eventuellement
- fk_user_creat integer qui est l'id du user de création (fk_user_author also found)
- fk_user_modif integer qui est l'id du user de modification
- fk_user_valid integer qui est l'id du user de validation
- fk_soc integer qui est l'id du tiers (si applicable)

*Type des champs

Dans la pratique, afin d'être 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 (bigint éventuellement accepté pour les id des très grosses tables)
- smallint pour tout numérique entier de petite taille (comme pour stocker un code de status)
- double(24,8) pour tout montant
- double(6,3) pour les taux de tva
- real pour une quantité
- varchar pour une chaîne (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

==Clé primaire==
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.

==Clés étrangères==
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).

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

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

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

<syntaxhighlight lang="sql">
-- ===========================================================================
-- Copyright (C) 2008 Author <email@author.com>
--
-- This program 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 of the License, 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, see <http://www.gnu.org/licenses/>.
-- ===========================================================================

create table llx_matable
(
rowid integer AUTO_INCREMENT PRIMARY KEY,
field_one integer,
field_two integer NOT NULL,
fk_field integer,
field_date datetime,
tms timestamp
)ENGINE=innodb;
</syntaxhighlight>

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

<syntaxhighlight lang="sql">
-- ===========================================================================
-- Copyright (C) 2008 Author <email@author.com>
--
-- This program 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 of the License, 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, see <http://www.gnu.org/licenses/>.
-- ===========================================================================

ALTER TABLE llx_matable ADD UNIQUE uk_matable_field(field_one, field_two);

ALTER TABLE llx_matable ADD CONSTRAINT fk_matable_fk_field FOREIGN KEY (fk_field) REFERENCES llx_matablepere (rowid);
</syntaxhighlight>

==Règles de codage SQL==

*Utilisation des alias/nommage de champs

Dans le cas des select on pourra utiliser les alias pour simplifier l'écriture des requêtes:
<syntaxhighlight lang="sql">
select chp1, chpxxx2 as chp2 from table2 as t1, table2 as t2 where t1.chpx = t2.chpy
</syntaxhighlight>
Toutefois, il ne faut pas utiliser ces alias sur des requêtes update car non compatible avec mysql 3.1.

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

<syntaxhighlight lang="sql">
SELECT field_a, field_b, field_c FROM table_1 WHERE field_d = '$id'
</syntaxhighlight>

*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:
<syntaxhighlight lang="sql">
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')
</syntaxhighlight>

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, SYSDATE ou DATEDIFF sont interdites au sein des ordres SQL. S'il faut saisir la date du moment dans un champ, la valeur doit venir du PHP, par exemple par la fonction dol_now(), 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 et ne pas dépendre du TimeZone de la base de donnée.

Par exemple, on ne fera pas:
<syntaxhighlight lang="PHP">
$sql="SELECT rowid FROM table where datefield = NOW()";
</syntaxhighlight>
mais:
<syntaxhighlight lang="PHP">
$sql="SELECT rowid FROM table where datefield = '".$this->db->idate(dol_now())."'";
</syntaxhighlight>

Par exemple, on ne fera pas:
<syntaxhighlight lang="PHP">
$sql="SELECT rowid FROM table where DATEDIFF(table.datefield, NOW()) > 7";
</syntaxhighlight>
mais:
<syntaxhighlight lang="PHP">
$sql="SELECT rowid FROM table where datefield < '".$this->db->idate(dol_now() - (7 * 24 * 3600))."'";
</syntaxhighlight>

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.

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

*Les tables doivent être au format InnoDB.

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.

*Dolibarr DOIT fonctionner même avec les options '''strict''' de Mysql active.

Pour l'activer (fortement recommandé en développement), ajouter la ligne suivante dans le fichier config du serveur Mysql (my.cnf ou my.ini)
{{MySqlStrictMode}}

==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 :
<syntaxhighlight lang="sql">
UPDATE table_taget as target, table_source as source SET fieldtarget=source.fieldsource
WHERE source.rowid=target.rowid;
</syntaxhighlight>

Syntax PgSQL:
<syntaxhighlight lang="sql">
UPDATE table_taget as target SET fieldtarget=source.fieldsource
FROM table_source as source WHERE source.rowid=target.rowid;
</syntaxhighlight>

Il n'en existe pas dans Dolibarr, mais pour vos modules Vous devriez faire tel que :
<syntaxhighlight lang="PHP">
if ($this->db->type=='pgsql') {
$sql="UPDATE table_taget as target SET fieldtarget=source.fieldsource
FROM table_source as source WHERE source.rowid=target.rowid";
} else {
$sql= "UPDATE table_taget as target, table_source as source SET fieldtarget=source.fieldsource
WHERE source.rowid=target.rowid";
}
</syntaxhighlight>

=Normes HTML=

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

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

Par example:
<syntaxhighlight lang="PHP">
print '<a href="'.dol_buildpath('/monrep/mapage.php').'">'.img_picto('Texte alt','nompictopng','').'</a>';
</syntaxhighlight>

*Les tables HTML doivent avoir des colonnes sans valeurs forcées, excepté pour les colonnes qui contiennent une information dont la longueur est non variable. Par exemple, une colonne avec un picto peut être 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 quelle que 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"

<syntaxhighlight lang="PHP">
if ($conf->use_javascript_ajax) {
... // Le code php qui génère du javascript est ici
}
</syntaxhighlight>

*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 '''htdocs/modulebuilder/templates'''.

Par exemple:
*1 fichier qui sert d'exemple de descripteur de module: '''myModule.class.php'''
*1 fichier qui sert d'exemple de code pour faire une nouvelle classe: '''skeleton_class.class.php'''
*1 fichier qui sert d'exemple de code pour faire une nouvelle page: '''skeleton_page.php'''
*1 fichier 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 ([[Module ModuleBuilder]]) qui est décrit dans la chapitre de développement de module Dolibarr pour accélérer vos développements.

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

*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 <b>locale du serveur PHP</b>. Cela ne concerne pas les dates mises à jour automatiquement par la base (champ '''tms''' en base).

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

*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

==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
<syntaxhighlight lang="PHP">
print 239.2 - 229.3 - 9.9;
</syntaxhighlight>
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).
<syntaxhighlight lang="PHP">
print price2num(239.2 - 229.3 - 9.9, 'MT');
</syntaxhighlight>
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).

==Comparer la version==

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

<syntaxhighlight lang="PHP">
$version=preg_split('/[\.-]/',DOL_VERSION);
if (versioncompare($version,array(5,0,-4)) >= 0) { //mycode for 5.0 only; } // For dolibarr 5.0.* (the -4 means we include also alpha, beta, rc and rcX)
</syntaxhighlight>

Mais cette solution requiert de faire un include avoir la fonction versioncompare. Une alternative est d'utiliser le test suivant:
<syntaxhighlight lang="PHP">
if ((float) DOL_VERSION >= 5.0) { //mycode for 5.0 only; } // For dolibarr 5.0.*
</syntaxhighlight>

==Logs==
Ajouter des traces dans votre code avec la fonction
<syntaxhighlight lang="PHP">
dol_syslog($yourmessage, LOG_INFO|LOG_DEBUG|LOG_WARNING|LOG_ERR);
</syntaxhighlight>

==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:
<syntaxhighlight lang="PHP">
$mymoduledir=DOL_DATA_ROOT.'/monmodule';
dol_mkdir($mymoduledir);
</syntaxhighlight>

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

==Design patterns d'entreprises (Martin Fowler)==

===Mode d'organisation du code===
[[wikipedia:Martin_Fowler|Martin Fowler]] a identifié 3 méthodes d'organisation du code appelées '''patterns''' ('''motifs'''):

*Le '''Transaction Script''' (Le code est linéaire 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 les parties métiers.

*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ées.

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

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

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

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

==Design Pattern d'Interface Graphique (MVC)==
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.

-> Dolibarr utilise le Design Pattern '''MVC'''. La partie M est matérialisée par une classe DAO contenant les méthode CRUD (Create-Read-Update-Delete) d'accès à la table.
Beaucoup de frameworks ont fait le choix de mettre la partie de code C (Controller) et la partie de code du V (vue) dans des fichiers, voir même répertoires séparés. La maintenance semble plus aisé sur la papier, en pratique, il faut sans arrêt jonglé entre n fichiers, le C étant fortement lié au V. Aussi dans Dolibarr, la séparation est faite par une simple section de commentaire. La partie de code C (Controller) est donc le code qui se trouve sont la balise
<pre>
/*
* Actions
*/
</pre>
Elle est suivi par la partie de code V (Vue), bien séparé du C par la balise
<pre>
/*
* View
*/
</pre>

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

==Design Pattern de Vue - Présentation==
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 de templates PHP (fichier .tpl.php) qui restent le plus simple, le plus universel, le plus évolutif et le plus performant, 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'expérience et le constat "sur le terrain" d'un meilleur rendement de productivité qui a motivé l'abandon des frameworks de Présentation externes au profit du framework PHP.

Langages et normes

2021-09-30T08:36:05Z

Quentic: /* Normes HTML */Orthographe

[[en:Language_and_development_rules]]
[[de:Sprachen_und_Programmierregeln]]
[[es:Lenguaje_y_Normas_de_Desarrollo]]
[[zh:语言和开发规则]]


{{TemplateDocDev}}

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:

#Tous OS (Windows, Linux, MACOS...)
#PHP {{PHPMinVersion}} (Doit fonctionner sans aucun module PHP complémentaire hors les modules d'accès base de donnée).
#Mysql {{MySqlMinVersion}}

=Normes Copyright=

*Tout fichier PHP doit avoir un en-tête selon le masque suivant

<syntaxhighlight lang="PHP">
<?php
/* Copyright (C) YYYY John Doe <email@email.com>
*
* Licence information
*/
...
</syntaxhighlight>
Quand vous éditez un fichier existant du projet, ajouter une ligne Copyright sous celles existantes.

=Normes PHP=

==PHP==

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

*L'appel aux variables superglobales PHP doit passer par les opérateurs dédiés $_COOKIES, $_SERVER, $_ENV. Mais pour récupérer les contenus de $_GET ou $_POST, il faut passer par la fonction dolibarr [[Fonctions utiles Dolibarr|GETPOST()]] .

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

*Pas d'utilisation de la variable '''PHP_SELF'''. Utiliser à la place $_SERVER["PHP_SELF"]. Notez aussi que le framework Dolibarr passe une routine pour rendre plus sûr le contenu du $_SERVER["PHP_SELF"] (dans le fichier main.inc.php, donc avant tout traitement métier)

*Quand plusieurs variables doivent être initialisées avec la même valeur, il faut utiliser plusieurs instructions:

<syntaxhighlight lang="PHP">
$var1 = 1; $var2 = 1; $var3 = 1;
</syntaxhighlight>
plutôt que
<syntaxhighlight lang="PHP">
$var1 = $var2 = $var3 = 1;
</syntaxhighlight>
qui est moins performant.

*Les chaines doivent avoir les variables sorties de la chaine.

<syntaxhighlight lang="PHP">
print "Mon texte affiche ma ".$variable." !\n";
</syntaxhighlight>

*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

<syntaxhighlight lang="PHP">
/* 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;
}

</syntaxhighlight>

*Les fonctions doivent retourner une valeur 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).

*Le style de code a utiliser est le PSR-12 (https://www.php-fig.org/psr/psr-12/). Seules les règles "MUST" sont imposées. Notez aussi les points/exceptions suivants:
**La longueur des lignes: PSR-12 indique que la longueur des lignes a une limite "soft" à 120. Il est en effet préférable d'avoir de longues lignes de données de déclaration plutôt que de longues pages car ce code ne contient aucune logique intéressante ou utile, toutefois une limite "hard" a été instauré à '''1000''' caractères. Du code qui ira au delà provoquera des erreurs dans la plateforme d'Intégration Continue.
**Les tabulations sont acceptées : L'autre exception est qu'on ne remplace pas les tabulations systématiquement par des espaces. L'utilisation des tabulations simplifie la vie de certains développeurs. De plus, l'utilisation d'espaces rend certaines fonctions d'autoformatage défectueuses (comme sur certaines versions d'Eclipse, lors de copier-coller).
**Note 1: Les règles suivantes sont particulièrement importantes :
***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'''
**Note 2: Vous pouvez utiliser le fichier '''dev/setup/codesniffer/ruleset.xml''' comme fichier de contrôle pour vérifier votre style de code avec PHPCodeSniffer.
**Note 3: Vous pouvez utiliser le fichier '''dev/setup/eclipse/PSR-12 [built-in].xml''' comme fichier de règles de syntax pour configurer Eclipse.
**Note 4: Vous remarquerez que le code actuel ne suit pas forcément tout cela. La raison est historique. La règle fut instaurée en cours de route, aussi, si vous trouvez du code non respectueux de ce standard, n'hésitez pas à le corriger.

==Structures des classes et champs==

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

=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 <tt>llx_</tt>.

*Structure des tables.

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
- entity INTEGER default 1 that is id for the multicompany feature
- date_creation datetime that is the creation date
- 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 varchar(32) qui contiendra le code d'import YYYYMMDDHHMMSS si vous faites des imports en masse dans la table.
- status smallint pour stocker le status d'un object

Eventuellement
- fk_user_creat integer qui est l'id du user de création (fk_user_author also found)
- fk_user_modif integer qui est l'id du user de modification
- fk_user_valid integer qui est l'id du user de validation
- fk_soc integer qui est l'id du tiers (si applicable)

*Type des champs

Dans la pratique, afin d'être 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 (bigint éventuellement accepté pour les id des très grosses tables)
- smallint pour tout numérique entier de petite taille (comme pour stocker un code de status)
- double(24,8) pour tout montant
- double(6,3) pour les taux de tva
- real pour une quantité
- varchar pour une chaîne (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

==Clé primaire==
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.

==Clés étrangères==
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).

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

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

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

<syntaxhighlight lang="sql">
-- ===========================================================================
-- Copyright (C) 2008 Author <email@author.com>
--
-- This program 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 of the License, 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, see <http://www.gnu.org/licenses/>.
-- ===========================================================================

create table llx_matable
(
rowid integer AUTO_INCREMENT PRIMARY KEY,
field_one integer,
field_two integer NOT NULL,
fk_field integer,
field_date datetime,
tms timestamp
)ENGINE=innodb;
</syntaxhighlight>

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

<syntaxhighlight lang="sql">
-- ===========================================================================
-- Copyright (C) 2008 Author <email@author.com>
--
-- This program 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 of the License, 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, see <http://www.gnu.org/licenses/>.
-- ===========================================================================

ALTER TABLE llx_matable ADD UNIQUE uk_matable_field(field_one, field_two);

ALTER TABLE llx_matable ADD CONSTRAINT fk_matable_fk_field FOREIGN KEY (fk_field) REFERENCES llx_matablepere (rowid);
</syntaxhighlight>

==Règles de codage SQL==

*Utilisation des alias/nommage de champs

Dans le cas des select on pourra utiliser les alias pour simplifier l'écriture des requêtes:
<syntaxhighlight lang="sql">
select chp1, chpxxx2 as chp2 from table2 as t1, table2 as t2 where t1.chpx = t2.chpy
</syntaxhighlight>
Toutefois, il ne faut pas utiliser ces alias sur des requêtes update car non compatible avec mysql 3.1.

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

<syntaxhighlight lang="sql">
SELECT field_a, field_b, field_c FROM table_1 WHERE field_d = '$id'
</syntaxhighlight>

*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:
<syntaxhighlight lang="sql">
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')
</syntaxhighlight>

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, SYSDATE ou DATEDIFF sont interdites au sein des ordres SQL. S'il faut saisir la date du moment dans un champ, la valeur doit venir du PHP, par exemple par la fonction dol_now(), 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 et ne pas dépendre du TimeZone de la base de donnée.

Par exemple, on ne fera pas:
<syntaxhighlight lang="PHP">
$sql="SELECT rowid FROM table where datefield = NOW()";
</syntaxhighlight>
mais:
<syntaxhighlight lang="PHP">
$sql="SELECT rowid FROM table where datefield = '".$this->db->idate(dol_now())."'";
</syntaxhighlight>

Par exemple, on ne fera pas:
<syntaxhighlight lang="PHP">
$sql="SELECT rowid FROM table where DATEDIFF(table.datefield, NOW()) > 7";
</syntaxhighlight>
mais:
<syntaxhighlight lang="PHP">
$sql="SELECT rowid FROM table where datefield < '".$this->db->idate(dol_now() - (7 * 24 * 3600))."'";
</syntaxhighlight>

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.

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

*Les tables doivent être au format InnoDB.

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.

*Dolibarr DOIT fonctionner même avec les options '''strict''' de Mysql active.

Pour l'activer (fortement recommandé en développement), ajouter la ligne suivante dans le fichier config du serveur Mysql (my.cnf ou my.ini)
{{MySqlStrictMode}}

==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 :
<syntaxhighlight lang="sql">
UPDATE table_taget as target, table_source as source SET fieldtarget=source.fieldsource
WHERE source.rowid=target.rowid;
</syntaxhighlight>

Syntax PgSQL:
<syntaxhighlight lang="sql">
UPDATE table_taget as target SET fieldtarget=source.fieldsource
FROM table_source as source WHERE source.rowid=target.rowid;
</syntaxhighlight>

Il n'en existe pas dans Dolibarr, mais pour vos modules Vous devriez faire tel que :
<syntaxhighlight lang="PHP">
if ($this->db->type=='pgsql') {
$sql="UPDATE table_taget as target SET fieldtarget=source.fieldsource
FROM table_source as source WHERE source.rowid=target.rowid";
} else {
$sql= "UPDATE table_taget as target, table_source as source SET fieldtarget=source.fieldsource
WHERE source.rowid=target.rowid";
}
</syntaxhighlight>

=Normes HTML=

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

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

Par example:
<syntaxhighlight lang="PHP">
print '<a href="'.dol_buildpath('/monrep/mapage.php').'">'.img_picto('Texte alt','nompictopng','').'</a>';
</syntaxhighlight>

*Les tables HTML doivent avoir des colonnes sans valeurs forcées, excepté pour les colonnes qui contiennent une information dont la longueur est non variable. Par exemple, une colonne avec un picto peut être 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 quelle que 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"

<syntaxhighlight lang="PHP">
if ($conf->use_javascript_ajax) {
... // Le code php qui génère du javascript est ici
}
</syntaxhighlight>

*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 '''htdocs/modulebuilder/templates'''.

Pr exemple:
*1 fichier qui sert d'exemple de descripteur de module: '''myModule.class.php'''
*1 fichier qui sert d'exemple de code pour faire une nouvelle classe: '''skeleton_class.class.php'''
*1 fichier qui sert d'exemple de code pour faire une nouvelle page: '''skeleton_page.php'''
*1 fichier 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 ([[Module ModuleBuilder]]) 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:

*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 <b>locale du serveur PHP</b>. Cela ne concerne pas les dates mises à jour automatiquement par la base (champ '''tms''' en base).

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

*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

==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
<syntaxhighlight lang="PHP">
print 239.2 - 229.3 - 9.9;
</syntaxhighlight>
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).
<syntaxhighlight lang="PHP">
print price2num(239.2 - 229.3 - 9.9, 'MT');
</syntaxhighlight>
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).

==Comparer la version==

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

<syntaxhighlight lang="PHP">
$version=preg_split('/[\.-]/',DOL_VERSION);
if (versioncompare($version,array(5,0,-4)) >= 0) { //mycode for 5.0 only; } // For dolibarr 5.0.* (the -4 means we include also alpha, beta, rc and rcX)
</syntaxhighlight>

Mais cette solution requiert de faire un include avoir la fonction versioncompare. Une alternative est d'utiliser le test suivant:
<syntaxhighlight lang="PHP">
if ((float) DOL_VERSION >= 5.0) { //mycode for 5.0 only; } // For dolibarr 5.0.*
</syntaxhighlight>

==Logs==
Ajouter des traces dans votre code avec la fonction
<syntaxhighlight lang="PHP">
dol_syslog($yourmessage, LOG_INFO|LOG_DEBUG|LOG_WARNING|LOG_ERR);
</syntaxhighlight>

==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:
<syntaxhighlight lang="PHP">
$mymoduledir=DOL_DATA_ROOT.'/monmodule';
dol_mkdir($mymoduledir);
</syntaxhighlight>

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

==Design patterns d'entreprises (Martin Fowler)==

===Mode d'organisation du code===
[[wikipedia:Martin_Fowler|Martin Fowler]] a identifié 3 méthodes d'organisation du code appelées '''patterns''' ('''motifs'''):

*Le '''Transaction Script''' (Le code est linéaire 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 les parties métiers.

*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ées.

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

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

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

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

==Design Pattern d'Interface Graphique (MVC)==
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.

-> Dolibarr utilise le Design Pattern '''MVC'''. La partie M est matérialisée par une classe DAO contenant les méthode CRUD (Create-Read-Update-Delete) d'accès à la table.
Beaucoup de frameworks ont fait le choix de mettre la partie de code C (Controller) et la partie de code du V (vue) dans des fichiers, voir même répertoires séparés. La maintenance semble plus aisé sur la papier, en pratique, il faut sans arrêt jonglé entre n fichiers, le C étant fortement lié au V. Aussi dans Dolibarr, la séparation est faite par une simple section de commentaire. La partie de code C (Controller) est donc le code qui se trouve sont la balise
<pre>
/*
* Actions
*/
</pre>
Elle est suivi par la partie de code V (Vue), bien séparé du C par la balise
<pre>
/*
* View
*/
</pre>

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

==Design Pattern de Vue - Présentation==
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 de templates PHP (fichier .tpl.php) qui restent le plus simple, le plus universel, le plus évolutif et le plus performant, 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'expérience et le constat "sur le terrain" d'un meilleur rendement de productivité qui a motivé l'abandon des frameworks de Présentation externes au profit du framework PHP.

Langages et normes

2021-09-30T08:33:58Z

Quentic: /* Structure des tables et champs */Correction d'erreur de frappe

[[en:Language_and_development_rules]]
[[de:Sprachen_und_Programmierregeln]]
[[es:Lenguaje_y_Normas_de_Desarrollo]]
[[zh:语言和开发规则]]


{{TemplateDocDev}}

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:

#Tous OS (Windows, Linux, MACOS...)
#PHP {{PHPMinVersion}} (Doit fonctionner sans aucun module PHP complémentaire hors les modules d'accès base de donnée).
#Mysql {{MySqlMinVersion}}

=Normes Copyright=

*Tout fichier PHP doit avoir un en-tête selon le masque suivant

<syntaxhighlight lang="PHP">
<?php
/* Copyright (C) YYYY John Doe <email@email.com>
*
* Licence information
*/
...
</syntaxhighlight>
Quand vous éditez un fichier existant du projet, ajouter une ligne Copyright sous celles existantes.

=Normes PHP=

==PHP==

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

*L'appel aux variables superglobales PHP doit passer par les opérateurs dédiés $_COOKIES, $_SERVER, $_ENV. Mais pour récupérer les contenus de $_GET ou $_POST, il faut passer par la fonction dolibarr [[Fonctions utiles Dolibarr|GETPOST()]] .

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

*Pas d'utilisation de la variable '''PHP_SELF'''. Utiliser à la place $_SERVER["PHP_SELF"]. Notez aussi que le framework Dolibarr passe une routine pour rendre plus sûr le contenu du $_SERVER["PHP_SELF"] (dans le fichier main.inc.php, donc avant tout traitement métier)

*Quand plusieurs variables doivent être initialisées avec la même valeur, il faut utiliser plusieurs instructions:

<syntaxhighlight lang="PHP">
$var1 = 1; $var2 = 1; $var3 = 1;
</syntaxhighlight>
plutôt que
<syntaxhighlight lang="PHP">
$var1 = $var2 = $var3 = 1;
</syntaxhighlight>
qui est moins performant.

*Les chaines doivent avoir les variables sorties de la chaine.

<syntaxhighlight lang="PHP">
print "Mon texte affiche ma ".$variable." !\n";
</syntaxhighlight>

*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

<syntaxhighlight lang="PHP">
/* 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;
}

</syntaxhighlight>

*Les fonctions doivent retourner une valeur 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).

*Le style de code a utiliser est le PSR-12 (https://www.php-fig.org/psr/psr-12/). Seules les règles "MUST" sont imposées. Notez aussi les points/exceptions suivants:
**La longueur des lignes: PSR-12 indique que la longueur des lignes a une limite "soft" à 120. Il est en effet préférable d'avoir de longues lignes de données de déclaration plutôt que de longues pages car ce code ne contient aucune logique intéressante ou utile, toutefois une limite "hard" a été instauré à '''1000''' caractères. Du code qui ira au delà provoquera des erreurs dans la plateforme d'Intégration Continue.
**Les tabulations sont acceptées : L'autre exception est qu'on ne remplace pas les tabulations systématiquement par des espaces. L'utilisation des tabulations simplifie la vie de certains développeurs. De plus, l'utilisation d'espaces rend certaines fonctions d'autoformatage défectueuses (comme sur certaines versions d'Eclipse, lors de copier-coller).
**Note 1: Les règles suivantes sont particulièrement importantes :
***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'''
**Note 2: Vous pouvez utiliser le fichier '''dev/setup/codesniffer/ruleset.xml''' comme fichier de contrôle pour vérifier votre style de code avec PHPCodeSniffer.
**Note 3: Vous pouvez utiliser le fichier '''dev/setup/eclipse/PSR-12 [built-in].xml''' comme fichier de règles de syntax pour configurer Eclipse.
**Note 4: Vous remarquerez que le code actuel ne suit pas forcément tout cela. La raison est historique. La règle fut instaurée en cours de route, aussi, si vous trouvez du code non respectueux de ce standard, n'hésitez pas à le corriger.

==Structures des classes et champs==

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

=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 <tt>llx_</tt>.

*Structure des tables.

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
- entity INTEGER default 1 that is id for the multicompany feature
- date_creation datetime that is the creation date
- 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 varchar(32) qui contiendra le code d'import YYYYMMDDHHMMSS si vous faites des imports en masse dans la table.
- status smallint pour stocker le status d'un object

Eventuellement
- fk_user_creat integer qui est l'id du user de création (fk_user_author also found)
- fk_user_modif integer qui est l'id du user de modification
- fk_user_valid integer qui est l'id du user de validation
- fk_soc integer qui est l'id du tiers (si applicable)

*Type des champs

Dans la pratique, afin d'être 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 (bigint éventuellement accepté pour les id des très grosses tables)
- smallint pour tout numérique entier de petite taille (comme pour stocker un code de status)
- double(24,8) pour tout montant
- double(6,3) pour les taux de tva
- real pour une quantité
- varchar pour une chaîne (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

==Clé primaire==
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.

==Clés étrangères==
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).

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

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

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

<syntaxhighlight lang="sql">
-- ===========================================================================
-- Copyright (C) 2008 Author <email@author.com>
--
-- This program 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 of the License, 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, see <http://www.gnu.org/licenses/>.
-- ===========================================================================

create table llx_matable
(
rowid integer AUTO_INCREMENT PRIMARY KEY,
field_one integer,
field_two integer NOT NULL,
fk_field integer,
field_date datetime,
tms timestamp
)ENGINE=innodb;
</syntaxhighlight>

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

<syntaxhighlight lang="sql">
-- ===========================================================================
-- Copyright (C) 2008 Author <email@author.com>
--
-- This program 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 of the License, 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, see <http://www.gnu.org/licenses/>.
-- ===========================================================================

ALTER TABLE llx_matable ADD UNIQUE uk_matable_field(field_one, field_two);

ALTER TABLE llx_matable ADD CONSTRAINT fk_matable_fk_field FOREIGN KEY (fk_field) REFERENCES llx_matablepere (rowid);
</syntaxhighlight>

==Règles de codage SQL==

*Utilisation des alias/nommage de champs

Dans le cas des select on pourra utiliser les alias pour simplifier l'écriture des requêtes:
<syntaxhighlight lang="sql">
select chp1, chpxxx2 as chp2 from table2 as t1, table2 as t2 where t1.chpx = t2.chpy
</syntaxhighlight>
Toutefois, il ne faut pas utiliser ces alias sur des requêtes update car non compatible avec mysql 3.1.

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

<syntaxhighlight lang="sql">
SELECT field_a, field_b, field_c FROM table_1 WHERE field_d = '$id'
</syntaxhighlight>

*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:
<syntaxhighlight lang="sql">
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')
</syntaxhighlight>

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, SYSDATE ou DATEDIFF sont interdites au sein des ordres SQL. S'il faut saisir la date du moment dans un champ, la valeur doit venir du PHP, par exemple par la fonction dol_now(), 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 et ne pas dépendre du TimeZone de la base de donnée.

Par exemple, on ne fera pas:
<syntaxhighlight lang="PHP">
$sql="SELECT rowid FROM table where datefield = NOW()";
</syntaxhighlight>
mais:
<syntaxhighlight lang="PHP">
$sql="SELECT rowid FROM table where datefield = '".$this->db->idate(dol_now())."'";
</syntaxhighlight>

Par exemple, on ne fera pas:
<syntaxhighlight lang="PHP">
$sql="SELECT rowid FROM table where DATEDIFF(table.datefield, NOW()) > 7";
</syntaxhighlight>
mais:
<syntaxhighlight lang="PHP">
$sql="SELECT rowid FROM table where datefield < '".$this->db->idate(dol_now() - (7 * 24 * 3600))."'";
</syntaxhighlight>

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.

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

*Les tables doivent être au format InnoDB.

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.

*Dolibarr DOIT fonctionner même avec les options '''strict''' de Mysql active.

Pour l'activer (fortement recommandé en développement), ajouter la ligne suivante dans le fichier config du serveur Mysql (my.cnf ou my.ini)
{{MySqlStrictMode}}

==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 :
<syntaxhighlight lang="sql">
UPDATE table_taget as target, table_source as source SET fieldtarget=source.fieldsource
WHERE source.rowid=target.rowid;
</syntaxhighlight>

Syntax PgSQL:
<syntaxhighlight lang="sql">
UPDATE table_taget as target SET fieldtarget=source.fieldsource
FROM table_source as source WHERE source.rowid=target.rowid;
</syntaxhighlight>

Il n'en existe pas dans Dolibarr, mais pour vos modules Vous devriez faire tel que :
<syntaxhighlight lang="PHP">
if ($this->db->type=='pgsql') {
$sql="UPDATE table_taget as target SET fieldtarget=source.fieldsource
FROM table_source as source WHERE source.rowid=target.rowid";
} else {
$sql= "UPDATE table_taget as target, table_source as source SET fieldtarget=source.fieldsource
WHERE source.rowid=target.rowid";
}
</syntaxhighlight>

=Normes HTML=

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

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

Par example:
<syntaxhighlight lang="PHP">
print '<a href="'.dol_buildpath('/monrep/mapage.php').'">'.img_picto('Texte alt','nompictopng','').'</a>';
</syntaxhighlight>

*Les tables HTML doivent avoir des colonnes sans valeurs forcées, excepté pour les colonnes qui contiennent une information dont la longueur est non variable. Par exemple, une colonne avec un picto peut être 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"

<syntaxhighlight lang="PHP">
if ($conf->use_javascript_ajax) {
... // Le code php qui génère du javascript est ici
}
</syntaxhighlight>

*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 '''htdocs/modulebuilder/templates'''.

Pr exemple:
*1 fichier qui sert d'exemple de descripteur de module: '''myModule.class.php'''
*1 fichier qui sert d'exemple de code pour faire une nouvelle classe: '''skeleton_class.class.php'''
*1 fichier qui sert d'exemple de code pour faire une nouvelle page: '''skeleton_page.php'''
*1 fichier 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 ([[Module ModuleBuilder]]) 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:

*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 <b>locale du serveur PHP</b>. Cela ne concerne pas les dates mises à jour automatiquement par la base (champ '''tms''' en base).

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

*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

==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
<syntaxhighlight lang="PHP">
print 239.2 - 229.3 - 9.9;
</syntaxhighlight>
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).
<syntaxhighlight lang="PHP">
print price2num(239.2 - 229.3 - 9.9, 'MT');
</syntaxhighlight>
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).

==Comparer la version==

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

<syntaxhighlight lang="PHP">
$version=preg_split('/[\.-]/',DOL_VERSION);
if (versioncompare($version,array(5,0,-4)) >= 0) { //mycode for 5.0 only; } // For dolibarr 5.0.* (the -4 means we include also alpha, beta, rc and rcX)
</syntaxhighlight>

Mais cette solution requiert de faire un include avoir la fonction versioncompare. Une alternative est d'utiliser le test suivant:
<syntaxhighlight lang="PHP">
if ((float) DOL_VERSION >= 5.0) { //mycode for 5.0 only; } // For dolibarr 5.0.*
</syntaxhighlight>

==Logs==
Ajouter des traces dans votre code avec la fonction
<syntaxhighlight lang="PHP">
dol_syslog($yourmessage, LOG_INFO|LOG_DEBUG|LOG_WARNING|LOG_ERR);
</syntaxhighlight>

==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:
<syntaxhighlight lang="PHP">
$mymoduledir=DOL_DATA_ROOT.'/monmodule';
dol_mkdir($mymoduledir);
</syntaxhighlight>

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

==Design patterns d'entreprises (Martin Fowler)==

===Mode d'organisation du code===
[[wikipedia:Martin_Fowler|Martin Fowler]] a identifié 3 méthodes d'organisation du code appelées '''patterns''' ('''motifs'''):

*Le '''Transaction Script''' (Le code est linéaire 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 les parties métiers.

*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ées.

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

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

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

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

==Design Pattern d'Interface Graphique (MVC)==
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.

-> Dolibarr utilise le Design Pattern '''MVC'''. La partie M est matérialisée par une classe DAO contenant les méthode CRUD (Create-Read-Update-Delete) d'accès à la table.
Beaucoup de frameworks ont fait le choix de mettre la partie de code C (Controller) et la partie de code du V (vue) dans des fichiers, voir même répertoires séparés. La maintenance semble plus aisé sur la papier, en pratique, il faut sans arrêt jonglé entre n fichiers, le C étant fortement lié au V. Aussi dans Dolibarr, la séparation est faite par une simple section de commentaire. La partie de code C (Controller) est donc le code qui se trouve sont la balise
<pre>
/*
* Actions
*/
</pre>
Elle est suivi par la partie de code V (Vue), bien séparé du C par la balise
<pre>
/*
* View
*/
</pre>

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

==Design Pattern de Vue - Présentation==
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 de templates PHP (fichier .tpl.php) qui restent le plus simple, le plus universel, le plus évolutif et le plus performant, 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'expérience et le constat "sur le terrain" d'un meilleur rendement de productivité qui a motivé l'abandon des frameworks de Présentation externes au profit du framework PHP.

Langages et normes

2021-09-30T08:32:30Z

Quentic: /* PHP */Correction d'erreur de frappe

[[en:Language_and_development_rules]]
[[de:Sprachen_und_Programmierregeln]]
[[es:Lenguaje_y_Normas_de_Desarrollo]]
[[zh:语言和开发规则]]


{{TemplateDocDev}}

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:

#Tous OS (Windows, Linux, MACOS...)
#PHP {{PHPMinVersion}} (Doit fonctionner sans aucun module PHP complémentaire hors les modules d'accès base de donnée).
#Mysql {{MySqlMinVersion}}

=Normes Copyright=

*Tout fichier PHP doit avoir un en-tête selon le masque suivant

<syntaxhighlight lang="PHP">
<?php
/* Copyright (C) YYYY John Doe <email@email.com>
*
* Licence information
*/
...
</syntaxhighlight>
Quand vous éditez un fichier existant du projet, ajouter une ligne Copyright sous celles existantes.

=Normes PHP=

==PHP==

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

*L'appel aux variables superglobales PHP doit passer par les opérateurs dédiés $_COOKIES, $_SERVER, $_ENV. Mais pour récupérer les contenus de $_GET ou $_POST, il faut passer par la fonction dolibarr [[Fonctions utiles Dolibarr|GETPOST()]] .

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

*Pas d'utilisation de la variable '''PHP_SELF'''. Utiliser à la place $_SERVER["PHP_SELF"]. Notez aussi que le framework Dolibarr passe une routine pour rendre plus sûr le contenu du $_SERVER["PHP_SELF"] (dans le fichier main.inc.php, donc avant tout traitement métier)

*Quand plusieurs variables doivent être initialisées avec la même valeur, il faut utiliser plusieurs instructions:

<syntaxhighlight lang="PHP">
$var1 = 1; $var2 = 1; $var3 = 1;
</syntaxhighlight>
plutôt que
<syntaxhighlight lang="PHP">
$var1 = $var2 = $var3 = 1;
</syntaxhighlight>
qui est moins performant.

*Les chaines doivent avoir les variables sorties de la chaine.

<syntaxhighlight lang="PHP">
print "Mon texte affiche ma ".$variable." !\n";
</syntaxhighlight>

*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

<syntaxhighlight lang="PHP">
/* 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;
}

</syntaxhighlight>

*Les fonctions doivent retourner une valeur 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).

*Le style de code a utiliser est le PSR-12 (https://www.php-fig.org/psr/psr-12/). Seules les règles "MUST" sont imposées. Notez aussi les points/exceptions suivants:
**La longueur des lignes: PSR-12 indique que la longueur des lignes a une limite "soft" à 120. Il est en effet préférable d'avoir de longues lignes de données de déclaration plutôt que de longues pages car ce code ne contient aucune logique intéressante ou utile, toutefois une limite "hard" a été instauré à '''1000''' caractères. Du code qui ira au delà provoquera des erreurs dans la plateforme d'Intégration Continue.
**Les tabulations sont acceptées : L'autre exception est qu'on ne remplace pas les tabulations systématiquement par des espaces. L'utilisation des tabulations simplifie la vie de certains développeurs. De plus, l'utilisation d'espaces rend certaines fonctions d'autoformatage défectueuses (comme sur certaines versions d'Eclipse, lors de copier-coller).
**Note 1: Les règles suivantes sont particulièrement importantes :
***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'''
**Note 2: Vous pouvez utiliser le fichier '''dev/setup/codesniffer/ruleset.xml''' comme fichier de contrôle pour vérifier votre style de code avec PHPCodeSniffer.
**Note 3: Vous pouvez utiliser le fichier '''dev/setup/eclipse/PSR-12 [built-in].xml''' comme fichier de règles de syntax pour configurer Eclipse.
**Note 4: Vous remarquerez que le code actuel ne suit pas forcément tout cela. La raison est historique. La règle fut instaurée en cours de route, aussi, si vous trouvez du code non respectueux de ce standard, n'hésitez pas à le corriger.

==Structures des classes et champs==

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

=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 <tt>llx_</tt>.

*Structure des tables.

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
- entity INTEGER default 1 that is id for the multicompany feature
- date_creation datetime that is the creation date
- 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 varchar(32) qui contiendra le code d'import YYYYMMDDHHMMSS si vous faites des imports en masse dans la table.
- status smallint pour stocker le status d'un object

Eventuellement
- fk_user_creat integer qui est l'id du user de création (fk_user_author also found)
- fk_user_modif integer qui est l'id du user de modification
- fk_user_valid integer qui est l'id du user de validation
- fk_soc integer qui est l'id du tiers (si applicable)

*Type des champs

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 (bigint éventuellement accepté pour les id des très grosses tables)
- smallint pour tout numérique entier de petite taille (comme pour stocker un code de status)
- 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

==Clé primaire==
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.

==Clés étrangères==
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).

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

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

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

<syntaxhighlight lang="sql">
-- ===========================================================================
-- Copyright (C) 2008 Author <email@author.com>
--
-- This program 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 of the License, 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, see <http://www.gnu.org/licenses/>.
-- ===========================================================================

create table llx_matable
(
rowid integer AUTO_INCREMENT PRIMARY KEY,
field_one integer,
field_two integer NOT NULL,
fk_field integer,
field_date datetime,
tms timestamp
)ENGINE=innodb;
</syntaxhighlight>

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

<syntaxhighlight lang="sql">
-- ===========================================================================
-- Copyright (C) 2008 Author <email@author.com>
--
-- This program 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 of the License, 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, see <http://www.gnu.org/licenses/>.
-- ===========================================================================

ALTER TABLE llx_matable ADD UNIQUE uk_matable_field(field_one, field_two);

ALTER TABLE llx_matable ADD CONSTRAINT fk_matable_fk_field FOREIGN KEY (fk_field) REFERENCES llx_matablepere (rowid);
</syntaxhighlight>

==Règles de codage SQL==

*Utilisation des alias/nommage de champs

Dans le cas des select on pourra utiliser les alias pour simplifier l'écriture des requêtes:
<syntaxhighlight lang="sql">
select chp1, chpxxx2 as chp2 from table2 as t1, table2 as t2 where t1.chpx = t2.chpy
</syntaxhighlight>
Toutefois, il ne faut pas utiliser ces alias sur des requêtes update car non compatible avec mysql 3.1.

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

<syntaxhighlight lang="sql">
SELECT field_a, field_b, field_c FROM table_1 WHERE field_d = '$id'
</syntaxhighlight>

*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:
<syntaxhighlight lang="sql">
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')
</syntaxhighlight>

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, SYSDATE ou DATEDIFF sont interdites au sein des ordres SQL. S'il faut saisir la date du moment dans un champ, la valeur doit venir du PHP, par exemple par la fonction dol_now(), 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 et ne pas dépendre du TimeZone de la base de donnée.

Par exemple, on ne fera pas:
<syntaxhighlight lang="PHP">
$sql="SELECT rowid FROM table where datefield = NOW()";
</syntaxhighlight>
mais:
<syntaxhighlight lang="PHP">
$sql="SELECT rowid FROM table where datefield = '".$this->db->idate(dol_now())."'";
</syntaxhighlight>

Par exemple, on ne fera pas:
<syntaxhighlight lang="PHP">
$sql="SELECT rowid FROM table where DATEDIFF(table.datefield, NOW()) > 7";
</syntaxhighlight>
mais:
<syntaxhighlight lang="PHP">
$sql="SELECT rowid FROM table where datefield < '".$this->db->idate(dol_now() - (7 * 24 * 3600))."'";
</syntaxhighlight>

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.

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

*Les tables doivent être au format InnoDB.

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.

*Dolibarr DOIT fonctionner même avec les options '''strict''' de Mysql active.

Pour l'activer (fortement recommandé en développement), ajouter la ligne suivante dans le fichier config du serveur Mysql (my.cnf ou my.ini)
{{MySqlStrictMode}}

==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 :
<syntaxhighlight lang="sql">
UPDATE table_taget as target, table_source as source SET fieldtarget=source.fieldsource
WHERE source.rowid=target.rowid;
</syntaxhighlight>

Syntax PgSQL:
<syntaxhighlight lang="sql">
UPDATE table_taget as target SET fieldtarget=source.fieldsource
FROM table_source as source WHERE source.rowid=target.rowid;
</syntaxhighlight>

Il n'en existe pas dans Dolibarr, mais pour vos modules Vous devriez faire tel que :
<syntaxhighlight lang="PHP">
if ($this->db->type=='pgsql') {
$sql="UPDATE table_taget as target SET fieldtarget=source.fieldsource
FROM table_source as source WHERE source.rowid=target.rowid";
} else {
$sql= "UPDATE table_taget as target, table_source as source SET fieldtarget=source.fieldsource
WHERE source.rowid=target.rowid";
}
</syntaxhighlight>

=Normes HTML=

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

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

Par example:
<syntaxhighlight lang="PHP">
print '<a href="'.dol_buildpath('/monrep/mapage.php').'">'.img_picto('Texte alt','nompictopng','').'</a>';
</syntaxhighlight>

*Les tables HTML doivent avoir des colonnes sans valeurs forcées, excepté pour les colonnes qui contiennent une information dont la longueur est non variable. Par exemple, une colonne avec un picto peut être 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"

<syntaxhighlight lang="PHP">
if ($conf->use_javascript_ajax) {
... // Le code php qui génère du javascript est ici
}
</syntaxhighlight>

*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 '''htdocs/modulebuilder/templates'''.

Pr exemple:
*1 fichier qui sert d'exemple de descripteur de module: '''myModule.class.php'''
*1 fichier qui sert d'exemple de code pour faire une nouvelle classe: '''skeleton_class.class.php'''
*1 fichier qui sert d'exemple de code pour faire une nouvelle page: '''skeleton_page.php'''
*1 fichier 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 ([[Module ModuleBuilder]]) 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:

*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 <b>locale du serveur PHP</b>. Cela ne concerne pas les dates mises à jour automatiquement par la base (champ '''tms''' en base).

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

*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

==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
<syntaxhighlight lang="PHP">
print 239.2 - 229.3 - 9.9;
</syntaxhighlight>
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).
<syntaxhighlight lang="PHP">
print price2num(239.2 - 229.3 - 9.9, 'MT');
</syntaxhighlight>
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).

==Comparer la version==

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

<syntaxhighlight lang="PHP">
$version=preg_split('/[\.-]/',DOL_VERSION);
if (versioncompare($version,array(5,0,-4)) >= 0) { //mycode for 5.0 only; } // For dolibarr 5.0.* (the -4 means we include also alpha, beta, rc and rcX)
</syntaxhighlight>

Mais cette solution requiert de faire un include avoir la fonction versioncompare. Une alternative est d'utiliser le test suivant:
<syntaxhighlight lang="PHP">
if ((float) DOL_VERSION >= 5.0) { //mycode for 5.0 only; } // For dolibarr 5.0.*
</syntaxhighlight>

==Logs==
Ajouter des traces dans votre code avec la fonction
<syntaxhighlight lang="PHP">
dol_syslog($yourmessage, LOG_INFO|LOG_DEBUG|LOG_WARNING|LOG_ERR);
</syntaxhighlight>

==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:
<syntaxhighlight lang="PHP">
$mymoduledir=DOL_DATA_ROOT.'/monmodule';
dol_mkdir($mymoduledir);
</syntaxhighlight>

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

==Design patterns d'entreprises (Martin Fowler)==

===Mode d'organisation du code===
[[wikipedia:Martin_Fowler|Martin Fowler]] a identifié 3 méthodes d'organisation du code appelées '''patterns''' ('''motifs'''):

*Le '''Transaction Script''' (Le code est linéaire 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 les parties métiers.

*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ées.

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

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

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

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

==Design Pattern d'Interface Graphique (MVC)==
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.

-> Dolibarr utilise le Design Pattern '''MVC'''. La partie M est matérialisée par une classe DAO contenant les méthode CRUD (Create-Read-Update-Delete) d'accès à la table.
Beaucoup de frameworks ont fait le choix de mettre la partie de code C (Controller) et la partie de code du V (vue) dans des fichiers, voir même répertoires séparés. La maintenance semble plus aisé sur la papier, en pratique, il faut sans arrêt jonglé entre n fichiers, le C étant fortement lié au V. Aussi dans Dolibarr, la séparation est faite par une simple section de commentaire. La partie de code C (Controller) est donc le code qui se trouve sont la balise
<pre>
/*
* Actions
*/
</pre>
Elle est suivi par la partie de code V (Vue), bien séparé du C par la balise
<pre>
/*
* View
*/
</pre>

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

==Design Pattern de Vue - Présentation==
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 de templates PHP (fichier .tpl.php) qui restent le plus simple, le plus universel, le plus évolutif et le plus performant, 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'expérience et le constat "sur le terrain" d'un meilleur rendement de productivité qui a motivé l'abandon des frameworks de Présentation externes au profit du framework PHP.

Langages et normes

2021-09-30T08:27:13Z

Quentic:

[[en:Language_and_development_rules]]
[[de:Sprachen_und_Programmierregeln]]
[[es:Lenguaje_y_Normas_de_Desarrollo]]
[[zh:语言和开发规则]]


{{TemplateDocDev}}

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:

#Tous OS (Windows, Linux, MACOS...)
#PHP {{PHPMinVersion}} (Doit fonctionner sans aucun module PHP complémentaire hors les modules d'accès base de donnée).
#Mysql {{MySqlMinVersion}}

=Normes Copyright=

*Tout fichier PHP doit avoir un en-tête selon le masque suivant

<syntaxhighlight lang="PHP">
<?php
/* Copyright (C) YYYY John Doe <email@email.com>
*
* Licence information
*/
...
</syntaxhighlight>
Quand vous éditez un fichier existant du projet, ajouter une ligne Copyright sous celles existantes.

=Normes PHP=

==PHP==

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

*L'appel aux variables superglobales PHP doit passer par les opérateurs dédiés $_COOKIES, $_SERVER, $_ENV. Mais pour récupérer les contenus de $_GET ou $_POST, il faut passer par la fonction dolibarr [[Fonctions utiles Dolibarr|GETPOST()]] .

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

*Pas d'utilisation de la variable '''PHP_SELF'''. Utiliser à la place $_SERVER["PHP_SELF"]. Notez aussi que le framework Dolibarr passe une routine pour rendre plus sûr le contenu du $_SERVER["PHP_SELF"] (dans le fichier main.inc.php, donc avant tout traitement métier)

*Quand plusieurs variables doivent être initialisées avec la même valeur, il faut utiliser plusieurs instructions:

<syntaxhighlight lang="PHP">
$var1 = 1; $var2 = 1; $var3 = 1;
</syntaxhighlight>
plutôt que
<syntaxhighlight lang="PHP">
$var1 = $var2 = $var3 = 1;
</syntaxhighlight>
qui est moins performant.

*Les chaines doivent avoir les variables sorties de la chaine.

<syntaxhighlight lang="PHP">
print "Mon texte affiche ma ".$variable." !\n";
</syntaxhighlight>

*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

<syntaxhighlight lang="PHP">
/* 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;
}

</syntaxhighlight>

*Les fonctions doivent retourner une valeur 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).

*Le style de code a utiliser est le PSR-12 (https://www.php-fig.org/psr/psr-12/). Seules les règles "MUST" sont imposées. Notez aussi les points/exceptions suivants:
**La longueur des lignes: PSR-12 indique que la longueur des lignes a une limite "soft" à 120. Il est en effet préférable d'avoir de longues lignes de données de déclaration plutôt que de longues pages car ce code ne contient aucune logique intéressante ou utile, toutefois une limite "hard" a été instauré à '''1000''' caractères. Du code qui ira au delà provoquera des erreurs dans la plateforme d'Intégration Continue.
**Les tabulations sont acceptées: L'autre exception est qu'on ne remplace pas les tabulations systématiquement par des espaces. L'utilisation des tabulations simplifie la vie de certains développeurs. De plus, l'utilisation d'espaces rend certaines fonctions d'autoformatage défectueuses (comme sur certaines versions d'Eclipse, lors de copié-collé).
**Note 1: Les règles suivantes sont particulièrement importantes:
***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'''
**Note 2: Vous pouvez utiliser le fichier '''dev/setup/codesniffer/ruleset.xml''' comme fichier de contrôle pour vérifier votre style de code avec PHPCodeSniffer.
**Note 3: Vous pouvez utiliser le fichier '''dev/setup/eclipse/PSR-12 [built-in].xml''' comme fichier de règles de syntax pour configurer Eclipse.
**Note 4: Vous remarquerez que le code actuel ne suit pas forcément tout cela. La raison est historique. La règle fut instaurée en cours de route, aussi, si vous trouvez du code non respectueux de ce standard, n'hésitez pas à le corriger.

==Structures des classes et champs==

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

=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 <tt>llx_</tt>.

*Structure des tables.

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
- entity INTEGER default 1 that is id for the multicompany feature
- date_creation datetime that is the creation date
- 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 varchar(32) qui contiendra le code d'import YYYYMMDDHHMMSS si vous faites des imports en masse dans la table.
- status smallint pour stocker le status d'un object

Eventuellement
- fk_user_creat integer qui est l'id du user de création (fk_user_author also found)
- fk_user_modif integer qui est l'id du user de modification
- fk_user_valid integer qui est l'id du user de validation
- fk_soc integer qui est l'id du tiers (si applicable)

*Type des champs

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 (bigint éventuellement accepté pour les id des très grosses tables)
- smallint pour tout numérique entier de petite taille (comme pour stocker un code de status)
- 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

==Clé primaire==
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.

==Clés étrangères==
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).

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

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

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

<syntaxhighlight lang="sql">
-- ===========================================================================
-- Copyright (C) 2008 Author <email@author.com>
--
-- This program 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 of the License, 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, see <http://www.gnu.org/licenses/>.
-- ===========================================================================

create table llx_matable
(
rowid integer AUTO_INCREMENT PRIMARY KEY,
field_one integer,
field_two integer NOT NULL,
fk_field integer,
field_date datetime,
tms timestamp
)ENGINE=innodb;
</syntaxhighlight>

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

<syntaxhighlight lang="sql">
-- ===========================================================================
-- Copyright (C) 2008 Author <email@author.com>
--
-- This program 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 of the License, 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, see <http://www.gnu.org/licenses/>.
-- ===========================================================================

ALTER TABLE llx_matable ADD UNIQUE uk_matable_field(field_one, field_two);

ALTER TABLE llx_matable ADD CONSTRAINT fk_matable_fk_field FOREIGN KEY (fk_field) REFERENCES llx_matablepere (rowid);
</syntaxhighlight>

==Règles de codage SQL==

*Utilisation des alias/nommage de champs

Dans le cas des select on pourra utiliser les alias pour simplifier l'écriture des requêtes:
<syntaxhighlight lang="sql">
select chp1, chpxxx2 as chp2 from table2 as t1, table2 as t2 where t1.chpx = t2.chpy
</syntaxhighlight>
Toutefois, il ne faut pas utiliser ces alias sur des requêtes update car non compatible avec mysql 3.1.

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

<syntaxhighlight lang="sql">
SELECT field_a, field_b, field_c FROM table_1 WHERE field_d = '$id'
</syntaxhighlight>

*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:
<syntaxhighlight lang="sql">
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')
</syntaxhighlight>

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, SYSDATE ou DATEDIFF sont interdites au sein des ordres SQL. S'il faut saisir la date du moment dans un champ, la valeur doit venir du PHP, par exemple par la fonction dol_now(), 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 et ne pas dépendre du TimeZone de la base de donnée.

Par exemple, on ne fera pas:
<syntaxhighlight lang="PHP">
$sql="SELECT rowid FROM table where datefield = NOW()";
</syntaxhighlight>
mais:
<syntaxhighlight lang="PHP">
$sql="SELECT rowid FROM table where datefield = '".$this->db->idate(dol_now())."'";
</syntaxhighlight>

Par exemple, on ne fera pas:
<syntaxhighlight lang="PHP">
$sql="SELECT rowid FROM table where DATEDIFF(table.datefield, NOW()) > 7";
</syntaxhighlight>
mais:
<syntaxhighlight lang="PHP">
$sql="SELECT rowid FROM table where datefield < '".$this->db->idate(dol_now() - (7 * 24 * 3600))."'";
</syntaxhighlight>

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.

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

*Les tables doivent être au format InnoDB.

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.

*Dolibarr DOIT fonctionner même avec les options '''strict''' de Mysql active.

Pour l'activer (fortement recommandé en développement), ajouter la ligne suivante dans le fichier config du serveur Mysql (my.cnf ou my.ini)
{{MySqlStrictMode}}

==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 :
<syntaxhighlight lang="sql">
UPDATE table_taget as target, table_source as source SET fieldtarget=source.fieldsource
WHERE source.rowid=target.rowid;
</syntaxhighlight>

Syntax PgSQL:
<syntaxhighlight lang="sql">
UPDATE table_taget as target SET fieldtarget=source.fieldsource
FROM table_source as source WHERE source.rowid=target.rowid;
</syntaxhighlight>

Il n'en existe pas dans Dolibarr, mais pour vos modules Vous devriez faire tel que :
<syntaxhighlight lang="PHP">
if ($this->db->type=='pgsql') {
$sql="UPDATE table_taget as target SET fieldtarget=source.fieldsource
FROM table_source as source WHERE source.rowid=target.rowid";
} else {
$sql= "UPDATE table_taget as target, table_source as source SET fieldtarget=source.fieldsource
WHERE source.rowid=target.rowid";
}
</syntaxhighlight>

=Normes HTML=

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

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

Par example:
<syntaxhighlight lang="PHP">
print '<a href="'.dol_buildpath('/monrep/mapage.php').'">'.img_picto('Texte alt','nompictopng','').'</a>';
</syntaxhighlight>

*Les tables HTML doivent avoir des colonnes sans valeurs forcées, excepté pour les colonnes qui contiennent une information dont la longueur est non variable. Par exemple, une colonne avec un picto peut être 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"

<syntaxhighlight lang="PHP">
if ($conf->use_javascript_ajax) {
... // Le code php qui génère du javascript est ici
}
</syntaxhighlight>

*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 '''htdocs/modulebuilder/templates'''.

Pr exemple:
*1 fichier qui sert d'exemple de descripteur de module: '''myModule.class.php'''
*1 fichier qui sert d'exemple de code pour faire une nouvelle classe: '''skeleton_class.class.php'''
*1 fichier qui sert d'exemple de code pour faire une nouvelle page: '''skeleton_page.php'''
*1 fichier 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 ([[Module ModuleBuilder]]) 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:

*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 <b>locale du serveur PHP</b>. Cela ne concerne pas les dates mises à jour automatiquement par la base (champ '''tms''' en base).

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

*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

==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
<syntaxhighlight lang="PHP">
print 239.2 - 229.3 - 9.9;
</syntaxhighlight>
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).
<syntaxhighlight lang="PHP">
print price2num(239.2 - 229.3 - 9.9, 'MT');
</syntaxhighlight>
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).

==Comparer la version==

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

<syntaxhighlight lang="PHP">
$version=preg_split('/[\.-]/',DOL_VERSION);
if (versioncompare($version,array(5,0,-4)) >= 0) { //mycode for 5.0 only; } // For dolibarr 5.0.* (the -4 means we include also alpha, beta, rc and rcX)
</syntaxhighlight>

Mais cette solution requiert de faire un include avoir la fonction versioncompare. Une alternative est d'utiliser le test suivant:
<syntaxhighlight lang="PHP">
if ((float) DOL_VERSION >= 5.0) { //mycode for 5.0 only; } // For dolibarr 5.0.*
</syntaxhighlight>

==Logs==
Ajouter des traces dans votre code avec la fonction
<syntaxhighlight lang="PHP">
dol_syslog($yourmessage, LOG_INFO|LOG_DEBUG|LOG_WARNING|LOG_ERR);
</syntaxhighlight>

==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:
<syntaxhighlight lang="PHP">
$mymoduledir=DOL_DATA_ROOT.'/monmodule';
dol_mkdir($mymoduledir);
</syntaxhighlight>

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

==Design patterns d'entreprises (Martin Fowler)==

===Mode d'organisation du code===
[[wikipedia:Martin_Fowler|Martin Fowler]] a identifié 3 méthodes d'organisation du code appelées '''patterns''' ('''motifs'''):

*Le '''Transaction Script''' (Le code est linéaire 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 les parties métiers.

*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ées.

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

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

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

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

==Design Pattern d'Interface Graphique (MVC)==
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.

-> Dolibarr utilise le Design Pattern '''MVC'''. La partie M est matérialisée par une classe DAO contenant les méthode CRUD (Create-Read-Update-Delete) d'accès à la table.
Beaucoup de frameworks ont fait le choix de mettre la partie de code C (Controller) et la partie de code du V (vue) dans des fichiers, voir même répertoires séparés. La maintenance semble plus aisé sur la papier, en pratique, il faut sans arrêt jonglé entre n fichiers, le C étant fortement lié au V. Aussi dans Dolibarr, la séparation est faite par une simple section de commentaire. La partie de code C (Controller) est donc le code qui se trouve sont la balise
<pre>
/*
* Actions
*/
</pre>
Elle est suivi par la partie de code V (Vue), bien séparé du C par la balise
<pre>
/*
* View
*/
</pre>

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

==Design Pattern de Vue - Présentation==
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 de templates PHP (fichier .tpl.php) qui restent le plus simple, le plus universel, le plus évolutif et le plus performant, 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'expérience et le constat "sur le terrain" d'un meilleur rendement de productivité qui a motivé l'abandon des frameworks de Présentation externes au profit du framework PHP.

Outils de développement - Composants optionnels

2021-09-30T08:22:12Z

Quentic: Correction d'erreur de frappe

[[en:Environment_and_development_tools_-_Optional]]
[[es:Herramientas_de_Desarrollo_-_Opcional]]


{{TemplateDocDev}}
Cette page liste les composants et autres technologies supplémentaires que vous pourriez vouloir installer sur votre environnement de développement. Elles ne sont pas requises pour développer sur Dolibarr, ni pour réaliser des modules mais peuvent être utiles pour des travaux très particuliers.

== Si vous désirez faire des scripts en Perl ==
* Installation du plugin Eclipse pour Perl: EPIC
Pour cela, utiliser la procédure '''Find And Install''' et ajouter l'URL de mise à jour: http://e-p-i-c.sourceforge.net/updates

== Si vous désirez faire des scripts en Python ==
* Installation du plugin Eclipse pour PyThon: PyDev
Pour cela, utiliser la procédure '''Find And Install''' et ajouter l'URL de mise à jour: http://pydev.org/updates

== Si vous êtes sous Windows ==

* Notepad++ (pour ceux qui ne supportent pas java ou utilisent un vieux coucou trop faible pour Eclipse).

* WinMerge (pour la comparaison de fichiers ou répertoires)

* CygWin (pour la commande patch si vous préferez les lignes de commandes)

A noter que Netbeans-PHP fonctionne efficacement avec Dolibarr.

== Si vous désirez faire du debuggage pas à pas ou du tunning (XDebug) ==

* Pour ajouter des infos de tuning page dans la console javascript à partir de Dolibarr 3.8, ajouter la variable d'environnement MAIN_SHOW_TUNING_INFO à 1 dans Apache. Pour cela, inclure la ligne suivante dans votre fichier apache.conf:
<source lang="ini">
SetEnv MAIN_SHOW_TUNING_INFO 1
</source>

* Pour du tuning à la ligne de code près, installer XDebug:
=== [[File:Logo_windows.png|24px]] In Windows ===
* Télécharger le fichier dll '''php_debug_xxx.dll''' sur http://www.xdebug.org et stocker le dans le répertoire /ext de php. Ensuite activer le plugin.

* Modifier le ficiher php.ini ou xdebug.ini pour ajouter le paramètres suivant:
<source lang="ini">
[xdebug]
xdebug.remote_enable=on
xdebug.remote_handle=dbgp
xdebug.remote_host=localhost
xdebug.remote_port=9000
xdebug.show_local_vars=off
xdebug.profiler_output_dir=c:/temp
xdebug.profiler_append=0
xdebug.profiler_enable=0
xdebug.profiler_enable_trigger=1
</source>

=== [[File:Logo_ubuntu.png|24px]] In Ubuntu / Linux ===
* Installer le package '''php-xdebug''':
<source lang="bash">
sudo apt-get install php5-xdebug
</source>

* Modifier xdebug.ini pour ajouter les paramètres suivants après les lignes de type zend_extension=xxx (ou similaire):
<source lang="ini">
; With xdebug 2.1 and more
xdebug.remote_enable=on
xdebug.remote_handle=dbgp
xdebug.remote_host=localhost
xdebug.remote_port=9000
xdebug.show_local_vars=off
xdebug.profiler_output_dir=/tmp
xdebug.profiler_append=0
xdebug.profiler_enable=0
xdebug.profiler_enable_trigger=1
; Add also this for xdebug 2.2 and more
xdebug.show_mem_delta=1
xdebug.trace_output_dir=/tmp
xdebug.auto_trace=0
xdebug.trace_enable_trigger=1
</source>

=== [[File:Eclipsephp.jpg|24px]] Eclipse configuration ===
* Ouvrir Eclipse. Dans Window->Preferences->General->Web Browser, sélectionner navigateur externe, et choisir le navigateur par défaut de votre système.

* Aller dans la rubrique Window->Preferences->PHP->Debug, et positionner les options PHP Debugger à XDebug. Remarquer que la case “Stop a la première ligne” sur cette page doit également être active. Vous pourrez la modifier plus tard.

* Après avoir validé les changements, aller dans la vue PHP Debug prespective, puis aller dans le menu Debug Configurations… Ici, vérifier que le Server Debugger est positionné à XDebug, et que votre server PHP pointe sur http://localhost/ ou le chemin approprié au serveur. La zone de localisation des fichiers doit de plus pointer sur le fichier à débugger, relativement à votre workspace. Ce chemin doit être quelquechose comme /dolibarr/htdocs/index.php.

* Vérifiez la section URL pour voir si elle pointe correctement – si non, vérifier que la case “Auto-Generate” est bien décochée, et entrer manuellement le bon chemin. Appliquer les changement et fermer la fenêtre de dialogue.

* Vous devriez maintenant être prêt pour lancer du debug de Dolibarr. Cliquer sur Run->Debug ou F11 pour activer le debug, Eclipse devrait basculer sur la vue Debug, et la page devrait commencer à se charger dans le navigateur externe. Si la case “Break at First Line” a bien été cochée précédemment, alors le programme aura stoppé à la première ligne. Vous pouvez alors faire du pas à pas sur les lignes de code successives en utilisant les boutons de la barre de Debug d'Eclipse. Eventuellement, vous pouvez placer des point d'arrêts à différents endroits du code pour y stopper l'exécution du code.

Ensuite pour analyser les fichiers de profiling générés par XDebug, il faut appeler l'url avec XDEBUG_PROFILE=1 pour générer le fichier profiling puis installer KCacheGrind (Linux) ou WinCacheGrind (Windows) pour l'analyser.

== Pour développer ou utiliser les contrôles Qualité (PHPUnit, PHPCodeSniffer, PHPCpd, PHPDepends) ==
=== Depuis Eclipse ===
Le plugin PTI pour utiliser PHPUnit et PHPCodesniffer est maintenant abandonnée.

* Pour utiliser PHPUnit, ceci est disponible en standard dans une installation de base d'Eclipse.

* Pour utiliser PHPCodesniffer, vous pouvez créer une entrée "External Tools" avec une configuration de ce type

[[Image:Setup_phpcs.png]]

=== En ligne de commande manuelle ===
==== Installer PHPUnit ====
* Télécharger l'archive de la version sur http://pear.phpunit.de/get/ et dézipper le contenu dans un répertoire inclus dans le paramètre include_path de votre fichier de configuration php.ini.
* Préparer le script phpunit:
** Sur Linux: Renommer le script phpunit.php script en phpunit et remplacer la chaine @php_bin@ dans ce fichier avec le chemin complet de la ligne de commande de l'interpréteur PHP (en général /usr/bin/php).
** Sur Windows: Remplacer la chaine @php_bin@ dans le fichier phpunit.bat avec le chemin complet de la ligne de commande de l'interpréteur PHP et remplacer la chaine @bin_dir@ avec le répertoire de PHPUnit.
** Modifier votre PATH pour inclure le répertoire contenant phpunit.
** Donner les permissions de s'exécuter (chmod +x phpunit sur Linux).
* Préparer le script PHPUnit/Util/PHP.php:
** Remplacer la chaine @php_bin@ dans ce fichier avec le chemin complet de la ligne de commande de l'interpréteur PHP (en général /usr/bin/php).
* Le module xdebug est également requis si vous voulez faire du reporting de couverture de tests.

==== Exécuter les tests PHPUnit ====
* Aller dans le répertoire '''/test''' des sources. Reportez vous au fichier '''README''' pour connaitre la procédure pour lancer une campagne de tests.

==== Installer les autres outils ====
* Référez vous à la documentation des différents outils (PHPCodeSniffer, PHPCpd, PHPDepends) pour leur installation et utilisation en ligne de commande. Par exemple, pour installer ou mettre à jour PHPCodeSniffer:
<source lang="bash">
sudo pear upgrade PHP_CodeSniffer
</source>
Les librairies pear seront installées dans '''/usr/share/php/PHP''' mais pour les prendre en compte avec Eclipse PTI, il faut ajouter une entrée "PHP" sur '''/usr/share/php''' et configurer PHPCheckstyle pour utiliser cette entrée.

== Pour développer ou utiliser les tests Selenium ==
=== Depuis Firefox ===
==== Installer le plugin pour Firefox Selenium IDE ====
* Télécharger le fichier du plugin Selenium IDE pour Firefox.
* L'ajouter dans Outils - Modules complémentaires de Firefox.

==== Exécuter les tests Selenium ====
* Aller dans le menu Outils - Selinum IDE de firefox.
* Ouvrir le fichier de tests xml
* Executer le test.

== Pour générer la documentation Doxygen ==
* Installer Doxygen disponible sur http://www.doxygen.org (ou par le package doxygen sous Ubuntu).
* Installer le plugin Eclipse en ajoutant l'url source http://download.gna.org/eclox/update/ dans l'outil de mise à jour Eclipse puis configurer Eclipse pour indiquer l'emplacement de Doxygen (Window-Preferences-Doxygen).

== Pour ajouter le support asciidoc à Eclipse ==

Ajouter l'URL http://download.eclipse.org/mylyn/snapshots/nightly/docs/ dans les Install repositories. Puis installer le package '''Mylyn Docs - Mylyn Wikitext Extras'''

Outils de développement

2021-09-30T08:20:08Z

Quentic: /* Optionnel */

Outils de développement

2021-09-30T08:19:40Z

Quentic: /* Installer le hook git Pre-commit */Correction d'erreur de frappe

Système de menus

2021-09-30T08:13:04Z

Quentic: /* Ajouter votre entrée menu */Reformulation des actions à la manière "rédaction technique"

[[en:Menus_system]]
[[es:Sistema_de_menús]]
[[de:Menü_System]]
[[zh:菜单]]


[[Category:Noyau]]
{{TemplateDocDev}}

=Le système de menu Dolibarr=

Il y a 2 systèmes de menu. Un système de menu définit les entrées de menu à afficher, conditions et localisation.

Changer de système de menu est possible via la page '''Configuration - Menus'''. Choisir ensuite '''Editeur de menus'''. Prendre par exemple les gestionnaires de menu "auguria", fournis en standard au lieu de "eldy". Ces gestionnaires de menu (gauche et haut) sont complètement opérationnels et offrent la même vision mais en utilisant une technologie de stockage différente.

Pour personnaliser ces menus par défaut, vous pouvez, soit ajouter votre propre entrée menu, soit développer votre propre gestionnaire de menu qui remplacera complètement le gestionnaire par défaut. Vous décidez alors comment stocker votre menu (en base de données comme avec le gestionnaire de menu '''auguria''', centralisé en dur dans un fichier comme avec le gestionnaire de menu '''eldy''', dans un fichier xml, ...). Voir les chapitres suivants pour cela....

=Ajouter votre entrée menu=
Imaginez que vous vouliez ajouter une entrée menu. Allez dans '''Accueil - Configuration - Menus'''. Choisissez '''Editeur de menu'''. Ajoutez l'entrée.

Par exemple, pour ajouter une entrée de menu afin d'arriver sur la page qui liste uniquement les opportunités avec les filtres déjà positionnées, vous ajouterez une entrée qui ressemblera à ceci:

<div class="divforimgcentpercent">
[[File:Menu editor.png]]
</div>

=Développer son propre système de menu=

Le but de cet article est de décrire comment créer un nouveau système de menu dans son intégralité (remplacement de l'intégralité des entrées menus, chamboulement complet du concept de navigation).

Cela ne concerne pas le simple ajout d'entrées de menus. Si tel et le cas et que vous désirez juste savoir comment ajouter des entrées menus au sein d'un gestionnaire de menu existant, dans le cadre du développement d'une extension ou d'un nouveau module par exemple, reporter vous plutôt à la page [[Developpement module]].

Si vous voulez remplacer intégralement un systeme de menu par le votre, le plus simple est de prendre exemple sur le gestionnaire de menu "eldy_backoffice".

==Pour développer son '''système de menu haut'''==
Il suffit de

#Copier le fichier htdocs/core/menus/standard/eldy_backoffice.php sous un autre nom comme htdocs/core/menus/standard/monmenu.php
#Editer ensuite le fichier monmenu.php. La fonction showmenu() de la classe MenuTop est la fonction appelée par Dolibarr lorsqu'il génère une page pour afficher ce menu haut. On peut y mettre le code que l'on veut, cette fonction ne modifie aucune variable extérieur et doit juste afficher par des "print" le menu que l'on veut voir. On peut ainsi récupérer le menu à afficher depuis un fichier de configuration, une base de données et le personnaliser par rapport à l'environnement. L'environnement Dolibarr étant stocké dans les 3 objets global suivant: $user, $conf, $langs.

$user contient les informations propres à l'utilisateur.
$conf contient les informations propres à la configuration (modules actifs, permissions actives, etc...)
$langs contient les informations propres à la langue active.

Exemple de fonction showmenu() du fichier htdocs/core/menus/standard/monmenu.php
<source lang="php">
function showmenu()
{
global $user,$conf,$langs,$dolibarr_main_db_name;

print '<table class="tmenu"><tr class="tmenu">';

// Menu Home
print '<td class="tmenu"><a '.$class.' href="'.DOL_URL_ROOT.'/index.php?mainmenu=home&leftmenu="'.($this->atarget?" target=".$this->atarget:"").'>'.$langs->trans("Home").'</a></td>';

// Put here other entries
// ...

print '</tr></table>';
}
</source>

==Pour développer son '''système de menu gauche'''==
Le principe est aussi simple que le menu haut.

#Copier le fichier htdocs/core/menus/standard/eldy_backoffice.php sous un autre nom comme htdocs/core/menus/standard/monmenu.php.
#Il faut ensuite modifier la fonction showmenu() de la classe MenuLeft afin de fabriquer son menu gauche. Si on veut afficher le menu standard ou juste le modifier légèrement sans recréer le sien complètement, il suffit de boucler sur le contenu du tableau $menu->liste. Si vous voulez afficher un menu complètement différent et totalement contrôlé par vous, il vous faut, dans la fonction showmenu(), créer un objet $newmenu=new Menu() et utiliser les méthodes $newmenu->add et $newmenu->add_submenu pour définir la liste des entrées menu gauche à faire apparaitre. Une fois cela fait, on affiche par des "print" le contenu du tableau $newmenu->liste (qui vient d’être construit) au lieu de $menu->liste.

Exemple de fichier htdocs/core/menus/standard/monmenu.php
<source lang="php">
function showmenu()
{
global $user,$conf,$langs,$dolibarr_main_db_name;
$newmenu = new Menu();

// Put here left menu entries
// ***** START *****

$langs->load("admin"); // Load translation file admin.lang
$newmenu->add(DOL_URL_ROOT."/admin/index.php?leftmenu=setup", $langs->trans("Setup"));
$newmenu->add_submenu(DOL_URL_ROOT."/admin/company.php", $langs->trans("MenuCompanySetup"));
$newmenu->add_submenu(DOL_URL_ROOT."/admin/modules.php", $langs->trans("Modules"));
$newmenu->add_submenu(DOL_URL_ROOT."/admin/ihm.php", $langs->trans("GUISetup"));
$newmenu->add_submenu(DOL_URL_ROOT."/admin/boxes.php", $langs->trans("Boxes"));
$newmenu->add_submenu(DOL_URL_ROOT."/admin/delais.php",$langs->trans("Alerts"));
$newmenu->add_submenu(DOL_URL_ROOT."/admin/triggers.php", $langs->trans("Triggers"));
$newmenu->add_submenu(DOL_URL_ROOT."/admin/perms.php", $langs->trans("Security"));
$newmenu->add_submenu(DOL_URL_ROOT."/admin/dict.php", $langs->trans("DictionnarySetup"));
$newmenu->add_submenu(DOL_URL_ROOT."/admin/const.php", $langs->trans("OtherSetup"));

// ***** END *****

// do not change code after this

// override menu_array by value array in $newmenu
$this->menu_array=$newmenu->liste;

$alt=0;
for ($i = 0 ; $i < sizeof($this->menu_array) ; $i++)
{
$alt++;
if ($this->menu_array[$i]['level']==0) {
if (($alt%2==0))
{
print '<div class="blockvmenuimpair">'."\n";
}
else
{
print '<div class="blockvmenupair">'."\n";
}
}

if ($this->menu_array[$i]['level']==0) {
if ($this->menu_array[$i]['enabled'])
print '<a class="vmenu" href="'.$this->menu_array[$i]['url'].'">'.$this->menu_array[$i]['titre'].'</a><br>';
else
print '<font class="vmenudisabled">'.$this->menu_array[$i]['titre'].'</font><br>';
}
if ($this->menu_array[$i]['level']==1) {
if ($this->menu_array[$i]['enabled'])
print '<a class="vsmenu" href="'.$this->menu_array[$i]['url'].'">'.$this->menu_array[$i]['titre'].'</a><br>';
else
print '<font class="vsmenudisabled">'.$this->menu_array[$i]['titre'].'</font><br>';
}
if ($this->menu_array[$i]['level']==2) {
if ($this->menu_array[$i]['enabled'])
print '    <a class="vsmenu" href="'.$this->menu_array[$i]['url'].'">'.$this->menu_array[$i]['titre'].'</a><br>';
else
print '    <font class="vsmenudisabled">'.$this->menu_array[$i]['titre'].'</font><br>';
}
if ($this->menu_array[$i]['level']==3) {
if ($this->menu_array[$i]['enabled'])
print '        <a class="vsmenu" href="'.$this->menu_array[$i]['url'].'">'.$this->menu_array[$i]['titre'].'</a><br>';
else
print '        <font class="vsmenudisabled">'.$this->menu_array[$i]['titre'].'</font><br>';
}

if ($i == (sizeof($this->menu_array)-1) || $this->menu_array[$i+1]['level']==0) {
print "</div>\n";
}
}

}
</source>

=Forcer l'utilisation de votre gestionnaire de menu=
Vous pouvez aussi forcer l'utilisation de votre gestionnaire au dépend de tout autre en développant un module.
Pour cela, il suffit d'ajouter les 4 constantes suivantes dans le tableau $this->const de votre descripteur de module (Voir la page [[Développement module]]).
<source lang="php">
* 1=>array('MAIN_MENU_STANDARD_FORCED','chaine','monmenu.php','Force menu handler to this value',1,'current',1),
* 2=>array('MAIN_MENUFRONT_STANDARD_FORCED','chaine','monmenu.php','Force menu handler to this value',1,'current',1),
* 3=>array('MAIN_MENU_SMARTPHONE_FORCED','chaine','monmenu.php','Force menu handler to this value',1,'current',1),
* 4=>array('MAIN_MENUFRONT_SMARTPHONE_FORCED','chaine','monmenu.php','Force menu handler to this value',1,'current',1),
</source>
Votre gestionnaire de menu sera utilisé, quelque soit la configuration, une fois que le module aura été activé.

Système de menus

2021-09-30T08:10:31Z

Quentic: /* Le système de menu Dolibarr */Correction d'erreur de frappe

[[en:Menus_system]]
[[es:Sistema_de_menús]]
[[de:Menü_System]]
[[zh:菜单]]


[[Category:Noyau]]
{{TemplateDocDev}}

=Le système de menu Dolibarr=

Il y a 2 systèmes de menu. Un système de menu définit les entrées de menu à afficher, conditions et localisation.

Changer de système de menu est possible via la page '''Configuration - Menus'''. Choisir ensuite '''Editeur de menus'''. Prendre par exemple les gestionnaires de menu "auguria", fournis en standard au lieu de "eldy". Ces gestionnaires de menu (gauche et haut) sont complètement opérationnels et offrent la même vision mais en utilisant une technologie de stockage différente.

Pour personnaliser ces menus par défaut, vous pouvez, soit ajouter votre propre entrée menu, soit développer votre propre gestionnaire de menu qui remplacera complètement le gestionnaire par défaut. Vous décidez alors comment stocker votre menu (en base de données comme avec le gestionnaire de menu '''auguria''', centralisé en dur dans un fichier comme avec le gestionnaire de menu '''eldy''', dans un fichier xml, ...). Voir les chapitres suivants pour cela....

=Ajouter votre entrée menu=
Imaginez que vous vouliez ajouter une entrée menu. Allez dans '''Accueil - Configuration - Menus'''. Choisir '''Editeur de menu'''. Ajouter l'entrée.

Par exemple, pour ajouter une entrée de menu afin d'arriver sur la page qui liste uniquement les opportunités avec les filtres déjà positionnées, vous ajouterez une entrée qui ressemblera à ceci:

<div class="divforimgcentpercent">
[[File:Menu editor.png]]
</div>

=Développer son propre système de menu=

Le but de cet article est de décrire comment créer un nouveau système de menu dans son intégralité (remplacement de l'intégralité des entrées menus, chamboulement complet du concept de navigation).

Cela ne concerne pas le simple ajout d'entrées de menus. Si tel et le cas et que vous désirez juste savoir comment ajouter des entrées menus au sein d'un gestionnaire de menu existant, dans le cadre du développement d'une extension ou d'un nouveau module par exemple, reporter vous plutôt à la page [[Developpement module]].

Si vous voulez remplacer intégralement un systeme de menu par le votre, le plus simple est de prendre exemple sur le gestionnaire de menu "eldy_backoffice".

==Pour développer son '''système de menu haut'''==
Il suffit de

#Copier le fichier htdocs/core/menus/standard/eldy_backoffice.php sous un autre nom comme htdocs/core/menus/standard/monmenu.php
#Editer ensuite le fichier monmenu.php. La fonction showmenu() de la classe MenuTop est la fonction appelée par Dolibarr lorsqu'il génère une page pour afficher ce menu haut. On peut y mettre le code que l'on veut, cette fonction ne modifie aucune variable extérieur et doit juste afficher par des "print" le menu que l'on veut voir. On peut ainsi récupérer le menu à afficher depuis un fichier de configuration, une base de données et le personnaliser par rapport à l'environnement. L'environnement Dolibarr étant stocké dans les 3 objets global suivant: $user, $conf, $langs.

$user contient les informations propres à l'utilisateur.
$conf contient les informations propres à la configuration (modules actifs, permissions actives, etc...)
$langs contient les informations propres à la langue active.

Exemple de fonction showmenu() du fichier htdocs/core/menus/standard/monmenu.php
<source lang="php">
function showmenu()
{
global $user,$conf,$langs,$dolibarr_main_db_name;

print '<table class="tmenu"><tr class="tmenu">';

// Menu Home
print '<td class="tmenu"><a '.$class.' href="'.DOL_URL_ROOT.'/index.php?mainmenu=home&leftmenu="'.($this->atarget?" target=".$this->atarget:"").'>'.$langs->trans("Home").'</a></td>';

// Put here other entries
// ...

print '</tr></table>';
}
</source>

==Pour développer son '''système de menu gauche'''==
Le principe est aussi simple que le menu haut.

#Copier le fichier htdocs/core/menus/standard/eldy_backoffice.php sous un autre nom comme htdocs/core/menus/standard/monmenu.php.
#Il faut ensuite modifier la fonction showmenu() de la classe MenuLeft afin de fabriquer son menu gauche. Si on veut afficher le menu standard ou juste le modifier légèrement sans recréer le sien complètement, il suffit de boucler sur le contenu du tableau $menu->liste. Si vous voulez afficher un menu complètement différent et totalement contrôlé par vous, il vous faut, dans la fonction showmenu(), créer un objet $newmenu=new Menu() et utiliser les méthodes $newmenu->add et $newmenu->add_submenu pour définir la liste des entrées menu gauche à faire apparaitre. Une fois cela fait, on affiche par des "print" le contenu du tableau $newmenu->liste (qui vient d’être construit) au lieu de $menu->liste.

Exemple de fichier htdocs/core/menus/standard/monmenu.php
<source lang="php">
function showmenu()
{
global $user,$conf,$langs,$dolibarr_main_db_name;
$newmenu = new Menu();

// Put here left menu entries
// ***** START *****

$langs->load("admin"); // Load translation file admin.lang
$newmenu->add(DOL_URL_ROOT."/admin/index.php?leftmenu=setup", $langs->trans("Setup"));
$newmenu->add_submenu(DOL_URL_ROOT."/admin/company.php", $langs->trans("MenuCompanySetup"));
$newmenu->add_submenu(DOL_URL_ROOT."/admin/modules.php", $langs->trans("Modules"));
$newmenu->add_submenu(DOL_URL_ROOT."/admin/ihm.php", $langs->trans("GUISetup"));
$newmenu->add_submenu(DOL_URL_ROOT."/admin/boxes.php", $langs->trans("Boxes"));
$newmenu->add_submenu(DOL_URL_ROOT."/admin/delais.php",$langs->trans("Alerts"));
$newmenu->add_submenu(DOL_URL_ROOT."/admin/triggers.php", $langs->trans("Triggers"));
$newmenu->add_submenu(DOL_URL_ROOT."/admin/perms.php", $langs->trans("Security"));
$newmenu->add_submenu(DOL_URL_ROOT."/admin/dict.php", $langs->trans("DictionnarySetup"));
$newmenu->add_submenu(DOL_URL_ROOT."/admin/const.php", $langs->trans("OtherSetup"));

// ***** END *****

// do not change code after this

// override menu_array by value array in $newmenu
$this->menu_array=$newmenu->liste;

$alt=0;
for ($i = 0 ; $i < sizeof($this->menu_array) ; $i++)
{
$alt++;
if ($this->menu_array[$i]['level']==0) {
if (($alt%2==0))
{
print '<div class="blockvmenuimpair">'."\n";
}
else
{
print '<div class="blockvmenupair">'."\n";
}
}

if ($this->menu_array[$i]['level']==0) {
if ($this->menu_array[$i]['enabled'])
print '<a class="vmenu" href="'.$this->menu_array[$i]['url'].'">'.$this->menu_array[$i]['titre'].'</a><br>';
else
print '<font class="vmenudisabled">'.$this->menu_array[$i]['titre'].'</font><br>';
}
if ($this->menu_array[$i]['level']==1) {
if ($this->menu_array[$i]['enabled'])
print '<a class="vsmenu" href="'.$this->menu_array[$i]['url'].'">'.$this->menu_array[$i]['titre'].'</a><br>';
else
print '<font class="vsmenudisabled">'.$this->menu_array[$i]['titre'].'</font><br>';
}
if ($this->menu_array[$i]['level']==2) {
if ($this->menu_array[$i]['enabled'])
print '    <a class="vsmenu" href="'.$this->menu_array[$i]['url'].'">'.$this->menu_array[$i]['titre'].'</a><br>';
else
print '    <font class="vsmenudisabled">'.$this->menu_array[$i]['titre'].'</font><br>';
}
if ($this->menu_array[$i]['level']==3) {
if ($this->menu_array[$i]['enabled'])
print '        <a class="vsmenu" href="'.$this->menu_array[$i]['url'].'">'.$this->menu_array[$i]['titre'].'</a><br>';
else
print '        <font class="vsmenudisabled">'.$this->menu_array[$i]['titre'].'</font><br>';
}

if ($i == (sizeof($this->menu_array)-1) || $this->menu_array[$i+1]['level']==0) {
print "</div>\n";
}
}

}
</source>

=Forcer l'utilisation de votre gestionnaire de menu=
Vous pouvez aussi forcer l'utilisation de votre gestionnaire au dépend de tout autre en développant un module.
Pour cela, il suffit d'ajouter les 4 constantes suivantes dans le tableau $this->const de votre descripteur de module (Voir la page [[Développement module]]).
<source lang="php">
* 1=>array('MAIN_MENU_STANDARD_FORCED','chaine','monmenu.php','Force menu handler to this value',1,'current',1),
* 2=>array('MAIN_MENUFRONT_STANDARD_FORCED','chaine','monmenu.php','Force menu handler to this value',1,'current',1),
* 3=>array('MAIN_MENU_SMARTPHONE_FORCED','chaine','monmenu.php','Force menu handler to this value',1,'current',1),
* 4=>array('MAIN_MENUFRONT_SMARTPHONE_FORCED','chaine','monmenu.php','Force menu handler to this value',1,'current',1),
</source>
Votre gestionnaire de menu sera utilisé, quelque soit la configuration, une fois que le module aura été activé.

Projet Dolibarr

2021-09-30T08:06:47Z

Quentic: /* Et Dark Vador ? */Correction d'erreur de frappe

[[en:Dolibarr_Project]]
[[es:Proyecto_Dolibarr]]


{{TemplateDocDevFr}}
{{TemplateDocUtil}}
Cette page fournit des informations sur l'organisation du projet, les rôles occupés par les différents acteurs (ainsi que les postes à pourvoir) et comment participer.

=[[File:orientation.png]] Histoire et futur du projet (Roadmap)=
Voir la page [[Origines et histoire du projet|Origines, histoire et futures versions de Dolibarr]]

=[[File:who.png]] Les acteurs et leurs rôles dans la galaxie Dolibarr=

L'équipe Dolibarr actuelle est constituée de différents responsables, soutenus (voire sponsorisés) par divers contributeurs physiques ou moral (sociétés, associations).
Les lignes suivantes présentent les différents rôles et postes occupés dans la gestion du projet Dolibarr et permettent ainsi de comprendre le fonctionnement interne du projet.
De nombreux rôles et postes sont en permanence à pourvoir.

Les volontaires pour postuler à une responsabilité dans le projet sont invités à se manifester sur la mailing list dev de Dolibarr.

Si vous désirez des informations pour participer en tant que développeur, la page [[FAQ_D%C3%A9veloppeur#Comment_devenir_d.C3.A9veloppeur_officiel|FAQ Développeur - Comment devenir développeur officiel]] est peut-être plus appropriée.

Les liens suivants présentent une liste des acteurs qui participent ou ont participé au projet.

*[[:Category:Everybody|Tout le monde (+ trombinoscope)]]
*[[:Category:User Retired|Tous les acteurs retraités]]
*[[:Category:User Active|Tous les acteurs actifs]]

La suite présente les différents '''rôles développeurs''' dans un premier temps puis tous les '''rôles non développeurs'''. Tous ces rôles constituent un part du moteur de l'avancement de Dolibarr.

==Les rôles développeurs==

===Développeur grade [[FAQ_D%C3%A9veloppeur#Yoda|Yoda]] (Chefs de projet commiteurs GIT, head release manager et B.D.F.L)===

Objectifs/Autorisations: Gérer le projet Dolibarr au sens large. Organiser les beta, figer les releases et réaliser le packaging de la version standard.

Ont ce rôle actuellement (par ordre alphabétique):

{{ListOfYodas|lang=FR}}

Fonction à pourvoir: Non (par définition, ce rôle est limité au chef de projet et backups)

Note: Tous les gestes pour construire un package pour une nouvelle version de Dolibarr sont définis dans le fichier '''build/makepack-howto.txt''' disponible avec les sources.

===Développeur grade Jedi (Release manager versions de maintenance)===

Objectifs/Autorisations: Packager et diffuser les releases des versions de maintenance.

A ce rôle actuellement:
{{ListOfModulesWithDedicatedJedi
|lang=FR}}

Fonction à pourvoir: Oui. Se manifester pour endosser ce rôle.

===Développeur grade Amiral (Réaliseur de GIT Pull Request)===

Objectifs/Autorisations : Développer, intégrer ou simplement valider et commiter dans le GIT.

L'obtention du grade d'Amiral est automatique dès lors que votre premier Pull Request sous Git est validé et intégré dans Dolibarr.

Fonction à pourvoir : Oui (Surtout pour la soumission de corrections de [https://github.com/dolibarr/dolibarr/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22 bogues déclarés sur Github], fortement recommandé pour commencer).

Articles en relation : [[FAQ_Développeur#Comment_devenir_d.C3.A9veloppeur_officiel|FAQ Comment_devenir_développeur_officiel]].

Identifiés comme ayant ce rôle actuellement ou récemment (comptes actifs dans {{TemplateURLSCM}}) :

*Voir {{ListOfAdmirals|lang=FR}}

===Développeur grade Z-6PO (Traducteurs sur transifex.com)===

Objectifs/Autorisations : Traduire Dolibarr en utilisant la plateforme collaborative Transifex.

Tous les utilisateurs qui sont enregistrés en tant que traducteur sur le projet Transifex Dolibarr sont Z-6PO.

Identifiés comme ayant ce rôle actuellement:

*Beaucoup de gens sont en fait des Z-6PO (à ce jour, plus de 1 150 contributeurs dans plus de 80 langues).

Fonction à pourvoir : Oui (aller sur https://www.transifex.com/projects/p/dolibarr/ pour trouver votre langue et aider à la traduire),

Articles en relation : [[Documentation traducteur]]

===Développeur grade Soldat===

Objectifs/Autorisations: Animer les forums, la communauté, promouvoir Dolibarr.

Fonction à pourvoir : Oui (sans limite)

Identifiés comme ayant ce rôle actuellement:

*Nombre trop variable pour être recensé. Tout utilisateur Dolibarr est un soldat potentiel de l'armée Dolibarr.

===Et Dark Vador ?===

Il existe hélas. Il y aura toujours des parasites qui polluent le forum ou la mailing-list de messages ou critiques non constructives, qui ralentissent le développement de Dolibarr plutôt que d'offrir des critiques aidant à progresser. Certains sont très très forts en mauvaise foi ou mauvais ton. Ce sont eux que l'on appellent les Dark Vador.
Heureusement, statistiquement, on ne constate l'apparition et la mort que d'un à deux Dark Vador par an environ ... Ce qui est un ratio très très bon par rapport aux autres projets Open-Source de même taille.

==Les autres rôles dans le projet Dolibarr==

===Role A: Hébergement site web (https://www.dolibarr.org ou sites locaux)===

Objectif: Fournir et maintenir une plateforme d'hébergement du site Dolibarr basée sur Joomla.

A ce rôle actuellement:
{{HosterOfWebSites}}

Fonction à pourvoir: Oui pour les autres langues/pays. Voir la page [[Create a Dolibarr local community]].

===Role B: Hébergement site démo (https://demo.dolibarr.org<nowiki/>)===

Objectif: Fournir et maintenir une plateforme d'hébergement du site de démo online Dolibarr (Version internationale, langage autodétecté).

A ce rôle actuellement:

*Dolibarr foundation (Version internationale avec langage auto-détecté https://demo.dolibarr.orgo)

Fonction à pourvoir: Non

===Role C1: Hébergement wiki (https://wiki.dolibarr.org<nowiki/>)===

Objectif: Fournir et maintenir une plateforme d'hébergement du wiki Dolibarr

A ce rôle actuellement:

*Dolibarr foundation

Fonction à pourvoir: Non

===Role C2: Hébergement place de marché (https://wwww.dolistore.com<nowiki/>)===

Objectif: Fournir une plateforme de diffusion et/ou vente centralisant les modules externes (basée sur prestashop). Valider les soumissions de modules.

A ce rôle actuellement

*Dolibarr foundation (plateforme)
*[[Juanjo Menent]] (validation modules)

Fonction à pourvoir: No

===Role E1: Responsable DoliWamp (Installeur pour Windows)===

A ce rôle actuellement:

*[[Laurent Destailleur]] ([https://www.nltechno.com NLTechno])

Fonction à pourvoir: Non

===Role E2: Responsable DoliDeb+DoliRpm (Installeur pour Ubuntu/Debian/Fedora/Mandriva/Redhat/Opensuse)===

A ce rôle actuellement:

*[[Laurent Destailleur]] ([https://www.nltechno.com NLTechno])

Fonction à pourvoir: Non

===Role E3: Responsable DoliMamp (Installeur pour Mac OS X)===

A ce rôle actuellement:

*Personne

Fonction à pourvoir: Oui

===Role G: Gestion de l'association Dolibarr===

Objectif: Créer et gérer une association de promotion et d'utilisateurs Dolibarr

Identifiés comme ayant ce rôle actuellement:

*1 président - Voir la page [[Association Dolibarr]].
*1 secrétaire - Voir la page [[Association Dolibarr]].
*1 trésorier - Voir la page [[Association Dolibarr]].
*D'autres acteurs, membres du conseil d'administration de l'association - Voir la page [[Association Dolibarr]].

===Role H: Promoteur/Communication pour Dolibarr===

Objectif: Faire de la '''communication/évangélisation''' pour Dolibarr, sur les forums, sites de news, presse, etc... Mettre à jour la page wiki '''Revues de presse''' ([[Presse papier]]). Saisir des articles sur les sites de Dolibarr. Animer les réseaux sociaux.

Identifiés comme ayant ce rôle actuellement:

*L'[[Association Dolibarr]]
*Fonction à pourvoir. Merci aux amateurs de se manifester sur la ML Dolibarr. Volontaires fortement désirés.

Articles en relation: Quelques exemples de [[modèles de messages]] utilisés pour annoncer les beta ou release.

===Role I: Testeur Dolibarr===

Objectif: Tester la version courante de Dolibarr (Branch develop dand GIT) et reporter sur la mailing-list le maximum de bugs.

Identifiés comme ayant ce rôle actuellement:

*Une cinquantaine de personnes régulières environ (chiffre obtenu par analyse des messages du forum), beaucoup plus si on intègre les rapporteurs occasionnels.

===Role J: Administrer les noms de domaines===
Goal: Administrer les DNS/noms de domaines

Identifiés comme ayant ce rôle actuellement:
{{ListOfDomainAdmins}}

=[[File:workcomputer.png]] Les accès GIT=

Le serveur GIT est hébergé chez {{TemplateUrlSCM}}

*Les instructions d'accès au GIT en lecture pour récupérer la version courante de développement sont sur [https://github.com/Dolibarr/dolibarr/ cette page]
*En ce qui concerne, les requêtes pour obtenir un accès en écriture, lire la [[FAQ_D%C3%A9veloppeur#Comment_devenir_d.C3.A9veloppeur_officiel|FAQ Comment devenir développeur officiel]] pour connaître l'organisation du projet et les étapes à franchir avant d'atteindre ce but.

=[[File:communaute.png]] Les Mailing-lists et groupes d'information=
Voir la page [[FAQ Comment être informé de ce qui se passe sur Dolibarr ?]]

=[[File:Lug.png]] Aider le projet=
Voici une liste de pistes possibles pour vous permettre d'aider le projet Dolibarr.

'''Si vous êtes une développeur'''

*Si vous êtes un développeur, rejoignez l'équipe de développement Dolibarr pour contribuer au projet. Voir [[FAQ Développeur]] pour cela.

'''Si vous parlez une langue non anglophone'''

*Traduire Dolibarr dans votre langue si sa traduction n'existe pas ou est incomplète. Voir [[Documentation traducteur]].
*Soumettre des articles pour promouvoir Dolibarr sur les sites d'informations dans votre langue ou sur votre propre site. A défaut un lien vers le site https://www.dolibarr.org ne peut pas faire de mal.

'''Si vous n'êtes ni développeur, ni traducteur'''

*Vous pouvez compléter la documentation Dolibarr de ce wiki, notamment la rubrique [[Documentation utilisateur]].
{{Template:LinksToVoteForDolibarr}}

*Vous pouvez adhérer à l'association Dolibarr. [[Adhérer|Voir ici pour adhérer]].

'''Si vous voulez monter un groupe d'utilisateur ou une communauté locale'''

*Pour cela, lisez notre guide sur la page [[Create a Dolibarr local community]] (anglais uniquement).

=[[File:Lug.png]] Dons=
Même si vous ne voulez pas être membre de l'association Dolibarr, vous pouvez toujours faire une adhésion pour aider le développement financièrement: [[Adh%C3%A9rer]].

FAQ Développeur

2021-09-30T08:02:09Z

Quentic: /* Comment devenir développeur officiel */Correction d'erreurs de frappe. Orthographe.

[[en:Developer_FAQ]]
[[de:Entwickler_FAQ]]
[[es:FAQ_Desarrolladores]]


[[Category:FAQ FR]]
{{TemplateDocDev}}
Cette page contient quelques questions-réponses en rapport avec le développement de Dolibarr. Pour des questions-réponses sur l'utilisation, consulter plutot la page [[FAQ Utilisateur]].

=Comment devenir développeur officiel=

Dans la galaxie du projet Dolibarr, il existe plusieurs intervenants de différents niveaux/grades.
Le nombre de développeurs et contributions est important, or tout projet qui veut atteindre un certain niveau de qualité se doit d'avoir une gestion contrôlée et des modifications validées des évolutions, aussi bien au niveau des besoins fonctionnels que du code.
Pour cette raison, les accès en écriture sur les sources (serveur GIT) sont limités et régis par une organisation qui est décrite dans les lignes qui suivent.
Chaque développeur a un '''grade''' qui dépend de son ancienneté et de ses contributions passées. Le niveau d'habilitation d'une personne sur le projet augmente avec les étapes de promotion de grade.

Le cursus d'un développeur Dolibarr passe donc par ces étapes, que l'on classe par un titre familier aux adeptes de science-fiction. Voici ces étapes.
Il est important de comprendre que cette organisation a pour seul but d'améliorer la qualité de Dolibarr et qu'il est nécessaire qu'elle soit rigoureusement respectée afin d'atteindre ce but.

Les grades des contributeurs au projet Dolibarr, et ce qu'il faut faire pour atteindre ce grade, sont définis sur la page suivante: [[Projet_Dolibarr#Les_r.C3.B4les_d.C3.A9veloppeurs|Projet Dolibarr]] dans la section '''Les rôles développeurs'''.

=L'équipe actuelle=
Voir la page [[projet Dolibarr]] pour connaitre la liste des personnes, participant au projet Dolibarr, à chaque grade actuellement.

=Démarrer le développement=
Consulter intégralement la [[Documentation Développeur]] pour assimiler toutes les règles et principes imposées aux développeurs.
Vous pouvez aussi consulter les FAQ suivantes.

=Récupérer/mettre à jour les sources du projet=
Voir la page [[FAQ Récupérer, mettre à jours les sources du projet]].

=Comment créer un nouveau theme=
Voir pour cela la page [[Themes]]

=Comment développer mon propre module=
Pour développer son propre module de numérotation, voir [[Créer un module de numérotation]].

Pour développer son propre modèle de document, PDF ou autre, voir [[Créer un modèle de document PDF]] ou [[Créer un modèle de document ODT]].

Pour développer un module fonctionnel entier (écrans, tables), voir pour cela la page [[Développement module]].

=Comment ajouter ou compléter une traduction=
Voir pour cela la page [[Documentation_traducteur]]

=Changer mon système de numérotation des factures en cours de route=
Si le nouveau système de numérotation n'entre pas en conflit avec l'ancien, il suffit d'aller dans le menu Configuration - Modules - Configuration factures et prendre un nouveau modèle dans la liste.
Si le nouveau système rentre en conflit, il est nécessaire de renuméroter vos références existantes. Cela peut-être fait avec une requête SQL.
Par exemple, pour passer de Jupiter (FYYYYMM99) à Terre (FAYYMM-999), vous pouvez exécuter la requête suivante:
<source lang="sql">
update llx_facture set facnumber=concat('FA',substr(facnumber,4,4),'-',substr(facnumber,8))
where facnumber like 'F%' and facnumber not like 'FA%';
</source>

Par exemple, pour passer d'un modele FAYYMM999 à Terre (FAYYMM-999), vous pouvez exécuter la requête suivante:
<source lang="sql">
update llx_facture set facnumber=concat('FA',substr(facnumber,3,4),'-',substr(CONCAT('0000',substr(facnumber,7)),-4))
where facnumber like 'FA%' and facnumber not like '%-%';
</source>

=Soumettre un patch, amélioration ou participer au développement=
Si vous cherchez comment commencer ou contribuer aux développements Dolibarr, lisez le chapitre [[FAQ_Développeur#Comment devenir développeur officiel]]. Si votre patch est déjà prêt et voulez le diffuser, ce chapitre est pour vous.

==Avec un compte GitHub==
Les accès au dépot des sources en lecture est publique. La soumission de contributions dépend toutefois de votre niveau dans le projet.

*Si vous bénéficiez d'un grade Yoda (rarissime), et donc un accès en écriture direct au dépôt de référence, utilisez-le (Voir [[FAQ_D%C3%A9veloppeur#Comment_devenir_d.C3.A9veloppeur_officiel|FAQ Développeur - Devenir développeur officiel]] pour les différents grades).

*Si vous n'avez pas d'accès en écriture direct au dépôt de référence (votre grade est donc [[Developer FAQ#Soldier|Jedi]] ou [[Developer FAQ#Soldier|Admiral]] ou [[Developer FAQ#Soldier|Soldier]]), vous devez alors utiliser GitHub en « Forkant » le dépôt sur votre compte, puis en faisant une demande de « Pull Request » de votre branche sur le dépôt principal. C'est la méthode recommandée la plus propre et la plus performante. Voir pour plus d'info la page https://wiki.dolibarr.org/index.php/FAQ_Get,update_GIT_project_sources

Note: Si vous ne savez pas bien utiliser l'outil GIT et si votre modification est petite (porte sur un ou deux fichiers), sachez qu'il est possible simplement, en allant sur votre compte GitHub et sur votre repository "Forké" depuis l'interface Web de GitHub, de modifier le fichier en ligne. Une fois la modification faite, vous pouvez utiliser la fonction soumettre Pull Request pour la suggérer au projet. Un valideur l'intégrera alors sans effort si elle est valide.

*La procédure qui suit reste un alternative techniquement possible mais n'est plus pratiquée que pour les toutes petites modifications...

==Sans compte GitHub==
Sans compte GitHub, il est nécessaire de générer et fournir par mail, sur la mailing-list développeur '''dolibarr-dev''' votre fichier patch (Voir ici pour cela {{TemplateURLMLDev}}). Voici la procédure pour générer un fichier patch:

''Sous tout OS:'' [[Image:Logo_windows.png|20px]] [[Image:Logo_ubuntu.png|20px]] [[Image:Logo_apple.png|20px]]

Voici la ''méthode Pro'' selon laquelle travailler pour pouvoir générer un tel fichier patch:

- Avoir un répertoire qui contient la version de Dolibarr de référence (résultat de la mise à jour GIT ou bien tout simplement l'arborescence résultant de la décompression d'un snapshot tgz de Dolibarr). On appellera ce répertoire '''ancien_rep'''. Vous pouvez récupérer le snapshot de la version de dev en cours sur le [http://www.dolibarr.org/downloads/ site officiel de Dolibarr - espace téléchargement - version développement].

- Avoir un autre répertoire qui contient l'arborescence de Dolibarr mais dans laquelle vous faites ou avez fait vos modifications. On appellera ce répertoire '''nouveau_rep'''.

Pour générer le fichier patch, il suffit alors de lancer la commande '''diff''' (en standard sous Linux, fourni dans [http://www.cygwin.org/cygwin cygwin] sous Windows) de la manière suivante:
<source lang="bash">
diff -BNaur --exclude=CVS --exclude="*.patch" --exclude=".#*" --exclude="*~" --exclude="*.rej" \
--exclude="*.orig" --exclude="*.bak" --exclude=conf.php --exclude=documents \
ancien_rep nouveau_rep > mypatch.patch
</source>
Un script ksh réalisant cette commande est disponible dans le répertoire '''build/patch'''.
Envoyer votre patch sur la ML à l'adresse '''dolibarr-dev@nongnu.org'''.
L'intégration de votre patch n'est toutefois pas garantie, pas plus que le délai, mais si le patch est réalisé en suivant rigoureusement cette procédure, il a de forte chance d'être au moins testé (dans le cas contraire les chances sont proches de 0).

''Sous Windows:'' [[Image:Logo_windows.png|20px]]

Si vous êtes sous Windows, une ''méthode moins Pro'' mais qui donne le même résultat est la suivante. Installer l'excellent outil open source de comparaison Winmerge qui sait fabriquer des patchs au format ''diff -Naur''. Pour cela, comparer avec Winmerge le fichier référence et le fichier modifié et choisir dans le menu ''"Tools - Generate patch"'' (''Générer des retouches'' en version française). Saisir un nom de fichier comme ''"resultat.patch"'', cocher la case ''"Append"'' et choisir l'option ''"Format Unified"'' (''Style : unifié'' en version française). Cliquer sur ''"Ok"''.
Éventuellement recommencer pour chaque fichier modifié.
Au final, on obtient un beau fichier ''resultat.patch'' qui contient toutes les modifications au bon format.

''Tester/Appliquer un patch''

Pour appliquer un fichier patch sur une version non modifié afin d'intégrer les modifications décrites dans le fichier patch, vous pouvez utiliser l'utilitaire '''patch'''.
Imaginons que vous avez un répertoire des sources d'une version non modifiée de Dolibarr sur un serveur. Pour appliquer le patch, placer dans le répertoire racine de Dolibarr et lancez la commande:
<source lang="bash">
patch -u -p0 -d . < monfichier.patch
</source>
<nowiki>Pour information: -p0 permet d'utiliser le chemin entier tel que mentionné dans le fichier de patch pour retrouver les fichiers à modifier dans votre arborescence source (-pn en retire les n premiers niveau de l'arborescence)
-d permet de préciser le chemin relatif vers le dossier à patcher.
< permet de donner le chemin vers le fichier source à utiliser (le patch doit être au format unifié)
-u permet de préciser que le patch est en mode unifié</nowiki>

''Envoyer le patch par mail''

Une fois votre fichier patch généré et testé avec succès, vous pouvez l'envoyer sur la mailing-list de développement '''dolibarr-dev''' de Dolibarr (Voir ici pour cela {{TemplateURLMLDev}}).
Cette mailing-list est lu de tous les développeurs principaux mais nous ne pouvons garantir que le patch sera inclus, cela dépend de sa qualité et des autres priorités de développement du moment.

=Comment packager/livrer un module=
Voir la page [[Développement_module#Cr.C3.A9er_un_package_pour_livrer_et_installer_votre_module|Developpement module - Créer un package pour livrer et installer votre module]]

La procédure est également valide pour générer un package pour le soumettre sur la place de marché https://www.dolistore.com

=Comment être informé de ce qui se passe sur Dolibarr ?=
Voir la page [[FAQ Comment être informé de l'actualité de Dolibarr ?]]

=Migrer ma base de Mysql vers PostgreSQL=
Voir la page [[FAQ Migrer ma base Mysql vers PostgreSQL]]