31,029
edits
Langages et normes: Difference between revisions
m
→Les dates et TimeZone
Tags: Mobile edit Mobile web edit Advanced mobile edit |
Tag: 2017 source edit |
||
| (6 intermediate revisions by the same user not shown) | |||
| Line 88: | Line 88: | ||
*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). | *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). | *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). | ||
*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: | *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: | ||
| Line 415: | Line 415: | ||
==Les dates et TimeZone== | ==Les dates et TimeZone== | ||
Dolibarr | 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 : | ||
* | * En mémoire, une date doit toujours être stockée au format Timestamp GMT. | ||
*Une date stockée en base de données | * Une date stockée en base de données correspond au Timestamp GMT de la date soumise dans la requête, en utilisant le fuseau horaire du serveur PHP. Cela ne s'applique pas aux dates mises à jour automatiquement par le moteur de base de données (champs `tms` en base de données). | ||
Par exemple, le 1er janvier 1970 à 3 heures à Paris (fuseau horaire +1) équivaut à 2 heures à Greenwich (fuseau horaire 0) ; la date sera stockée en mémoire sous la forme de l'entier 7200 (2 * 3600 s) et transmise à la base de données via une requête SQL sous la chaîne '19700101030000' (PHP convertit l'entier selon son fuseau horaire, et la base de données effectue la conversion inverse en utilisant également son propre fuseau horaire, identique à celui de PHP). | |||
'''Gestion des dates incluant les heures''' | |||
Ainsi, toutes les méthodes d'insertion ou de mise à jour doivent convertir, lors de la génération de la requête SQL, la date stockée en mémoire (sous forme d'entier) en une chaîne de caractères compatible avec la base de données, en utilisant `db->idate` (des exemples sont disponibles dans le squelette de code). | |||
*La manipulation | De même, 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 '19700101030000') en un champ timestamp (entier) en appelant la méthode `db->jdate()`. Cela permet de stocker la date en mémoire sous forme d'entier (Timestamp GMT). | ||
'''Gestion des dates sans heures (jour uniquement)''' | |||
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'''. | |||
==L'encodage UTF8/ISO== | ==L'encodage UTF8/ISO== | ||
| Line 499: | Line 511: | ||
C'est le motif à l'ancienne utilisé dans les langages procéduraux. | 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. | Inconvénient: Redondance du code. Nécessité de connaitre le modèle physique pour développer les parties métiers. | ||
*Le '''Domain Model''' | *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. | 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 complexe à maintenir. | |||
Inconvénient : Motif plus complexe à maintenir. | |||
*Le '''Table Module''' | *Le '''Table Module''' | ||
| Line 510: | Line 524: | ||
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. | 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 chapitre précédent Normes Dolibarr et squelettes de code), Dolibarr se base sur le principe du '''Table Module'''. | -> 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. | ||
===Communication Logique métier - Données (ORM)=== | ===Communication Logique métier - Données (ORM)=== | ||
| Line 523: | Line 537: | ||
*Le '''Active Record''' | *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. | 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 mode choisi pour les développements Dolibarr et de nombreuses autres applications PHP qui ont leur propre framework et pratiques de développement. | 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. | ||
La couche ORM de Dolibarr se limite à une couche d abstraction de la base (on développe une fois et le driver de base converti le code pour l'accès base dans la syntaxe de la base de donnée: mysql vs postgresql vs ...) | |||
*Le '''Data Mapper''' | *Le '''Data Mapper''' | ||
| Line 532: | Line 548: | ||
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). | 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 | 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. | ||
-> 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). | -> 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). | ||
| Line 558: | Line 574: | ||
==Design Pattern de Vue - Présentation== | ==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. | 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 (fichiers .php ou .tpl.php) qui restent, | 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. | 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. | ||