Langages et normes: Difference between revisions

{{TemplateDocDevFr}}

#PHP {{PHPMinVersion}} (Doit fonctionner sans aucun module PHP complémentaire hors les modules d'accès base de donnée). Voir la page [[Versions|Liste des versions, journal des modifications et compatibilités]] pour les prérequis des versions plus anciennes.

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

*Utiliser "include_once" ou "require_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).

==Structure et nom des tables et champs==

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 et ces processus ne doivent pas dépendre de la présence d'un module externe. Il vous faut donc assurer l'intégrité de manière applicative si nécessaire.

*Les fonctions SQL de date NOW, SYSDATE, DATEDIFF, DATE 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 pour les raisons suivantes:

**afin d'avoir une meilleure portabilité du code

**avoir une gestion correcte des TimeZone et ne pas dépendre du TimeZone de la base de donnée (le timezone de réference est le timezone de PHP et le timezone de la base de données peut être différent de celui-ci, aussi les conversions de date doivent se faire toute côté PHP).

*Les liens href doivent être absolus en se basant sur la fonction dol_buildpath() obtenir un chemin absolu depuis un chemin relatif au répertoire htdocs (pour les modules externes) ou en utilisant DOL_URL_ROOT pour le code core. Pour les tags img, il faut faire appel à la fonction img_picto().

*1 fichier qui sert d'exemple de descripteur de module: '''core/modules/myModule.class.php'''

*1 fichier qui sert d'exemple de code pour faire une nouvelle classe: '''class/skeleton_class.class.php'''

*1 fichier qui sert d'exemple de code pour faire un script à exécuter en ligne de commande: '''scripts/skeleton_script.php'''

Dolibarr est une application multi-utilisateur et multi-site. Il est donc nécessaire de stocker les dates dans le format approprié. Pour éviter les problèmes de conversion, les règles suivantes doivent être appliquées :

 

 

 

 

 

 

Pour les insertions et mises à jour, vous devez effectuer la conversion avec `db->idate(valeur, 'gmt')` ; ainsi, pour la valeur 0, vous obtiendrez '19700101000000'.

Toutes les méthodes de sélection doivent convertir les champs de date provenant de la base de données (chaînes au format du fuseau horaire du serveur, par exemple '19700101000000') en utilisant `$db->jdate(..., 'gmt')`.  

'''Autres cas'''

*Les dates mises à jour automatiquement (champ '''tms''' en base de données) contiennent un horodatage GMT correspondant au moment où la modification a été effectuée. La requête de sélection utilise également `db->jdate` (qui s'appuie sur le fuseau horaire du serveur PHP) pour convertir les données lues en un horodatage GMT en mémoire. Ainsi, si le fuseau horaire de la base de données diffère de celui du serveur PHP (par exemple, si l'un d'eux est mal configuré), vous pourriez constater des écarts entre la date de création et la date de mise à jour. Il est conseillé de ne pas se baser sur ce champ dans Dolibarr (ce champ à mise à jour automatique est principalement destiné au débogage).

*La manipulation des dates en PHP doit s'effectuer à l'aide des fonctions de date de Dolibarr : '''dol_now(), dol_mktime(), dol_stringtotime(), dol_getdate(), dol_time_plus_duree()'''. Vous trouverez également d'autres fonctions disponibles dans le fichier '''date.lib.php'''.

Mais cette solution requiert de faire un include avoir la fonction versioncompare. Une alternative est d'utiliser le test suivant:

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. C'est le modèle dit le plus "puriste".

 

Inconvénient : Motif plus complexe à maintenir.

-> Comme le montre les squelettes de code (voir chapitre précédent Normes Dolibarr et squelettes de code), Dolibarr se base sur le principe du '''Table Module''', car le plus pragmatique des 3.

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. Jugé plus éloigné des standards scolaires de la programmation objet, c'est toutefois le pattern qui offre le meilleur rapport fonctionnalité/complexité.

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

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

-> Dolibarr utilise le Design Pattern '''MVC''' (Model - Vue - Contrôleur). 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 (Contrôleur) 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 jongler 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 (Contrôleur) est donc le code qui se trouve sont la balise

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 (les constats faits 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 pour être MVC, peu importe comment est matérialisée cette séparation, du moment qu'elle l'est (Rappel: Ne pas confondre la notion de séparation du C et du V qui relève du design pattern MVC avec la notion de séparation du code pour alimenter les données d'une Vue et du code pour formater la Vue, cette deuxième notion étant un principe de séparation relevant du Design Pattern de Vue, autrement appelé notion de templates, sans lien avec le MVC donc, voir point suivant).

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 (fichiers .php ou .tpl.php) qui restent, de tous les frameworks de présentation, le plus simple, plus universel, plus évolutif, plus performant et surtout plus résilient au temps.

 

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 pour le rendering écran). 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é, d'évolution applicative et de performance qui a motivé l'abandon des frameworks de Présentation externes au profit du framework PHP.

= Règles pour définir la branche cible d'une contribution =

Les règles pour décider si une contribution (Pull Request) doit être poussée dans une ancienne branche de maintenance ou dans une branche de développement ne sont pas strictes et sont souvent définies par le bon sens (pragmatisme avant tout).

Nous pouvons nous aider du diagramme de décision disponible sur cette page [[:Category:RoadMap#Merging_PR_process_.28develop_or_maintenance_.3F.29]]