Dolibarr ERP CRM Wiki - User contributions [en]

Premiers paramétrages

2009-02-04T13:14:10Z

Mcg: /* Quelques options cachées */

{{TemplateDocUtil}}

Après l'installation proprement dite de Dolibarr, vous devez le paramétrer pour l'adapter à vos besoins avant de le mettre en production.

== Société/Institution ==

Pour commencer, à partir de la page d'accueil, rendez-vous dans la partie "Configuration -> Société/Institution" et éditez les informations de votre institution.
N'oubliez pas d'indiquer votre pays car certaines fonctions (TVA) en dépendent.

== Modules ==

L'activation des modules est très importante. Elle dépend de l'utilisation que vous prévoyez de faire de Dolibarr. Il est très peu probable que vous ayez besoin de la totalité des modules.
Il vous faut donc activer les modules dont vous aurez très probablement besoin. Par exemple: Sociétés, Factures éventuellement Comptabilité.

Si vous n'êtes pas sûr de vous, activez les modules les uns après les autres et voyez les fonctionnalités qu'ils ajoutent dans Dolibarr (vérifiez avant les droits, voir ci-dessous). Il est bien sûr possible de désactiver des modules après coup.

Une fois activés, certains modules nécessitent une configuration supplémentaire (cliquer sur l'icône qui apparait tout à droite sur la même ligne).
Voir, par exemple, pour les factures [[FactureConfiguration]].

== Affichage ==

Cette partie vous permet de choisir la langue et la présentation des pages. Dans un premier temps vous devriez conserver les options par défaut.

== Autres (Boites, Alertes, Sécurité, Limites et précisions, EMails, Dico...) ==
Les autres entrées du menu Configuration sont des options avancées.
Il n'est pas obligatoire de les parcourir.

== Utilisateurs ==
La dernière étape consiste à créer les utilisateurs et à attribuer les permissions.
Presque tous les modules, même activés précédemment, ne sont pas accessibles si on n'en donne pas la permission.
Pour cela, vous pouvez vous rendre dans le menu '''Accueil -> Utilisateurs & Groupes''' pour définir les utilisateurs et leurs droits. Attention, il faudra penser à vérifier et redéfinir les droits utilisateurs quand vous activerez à nouveau de nouveaux modules.
La liste des droits disponibles dépendant des modules activés (voir plus haut), il est recommandé de configurer cette partie après avoir activé les modules désirés.
Pour certaines actions, si vous n'avez pas les droits pour faire une action, Dolibarr ne vous la proposera pas. Vous risquez de rater des choses utiles et/ou importantes.
Pour donner les droits à un utilisateur ou vous-même si vous êtes administrateur, aller dans '''Accueil -> Utilisateurs & Groupes''', choisissez la fiche de l'utilisateur désiré, puis cliquer sur l'onglet '''Permission'''.

== Quelques options cachées ==
Quelques options non visibles dans les interfaces (souvent car en bêta ou en expérimentation) sont disponibles. Dans la plupart des cas, vous n'avez pas besoin de ces fonctions et leur utilisation peut rendre instable l'application.

Pour les activer il faut définir une constante à 1 dans '''Accueil - Configuration - Divers''':

=== Options globales ===
* MAIN_APPLICATION_TITLE => Permet de définir le nom de l'application (qui apparait sur la page de login par defaut).

* MAIN_CONFIRM_AJAX => Si cette constante est définie (à autre chose que 0), le message de confirmation de suppression de lignes de facture, propal, etc, est une popup Ajax, au lieu d'un formulaire affiché par rechargement de la page.

* MAIN_DISABLE_FULL_SCANLIST => Constante à définir pour désactiver le scan complet des tables afin de connaitre le nombre total d'éléments pour permettre des paginations affichant le nombre de pages. A activer sur les systèmes ayant un nombre très important de données (Tables de + de 500 000 enregistrements).

* MAIN_AUTOFILL_DATE => Si cette constante est définie (à autre chose que 0), la date de facture, propal, commande ou paiement est préremplie avec la date du jour. Il est fortement recommandé de NE PAS ACTIVER cette option, ceci générant une saisie sans validation de la part des utilisateurs sur les dates, ce qui se traduit par des données incorrectes enregistrées et un beau casse tête lorsqu'il faut faire sa compta ! Toutefois l'option reste disponible, à la demande de certains utilisateurs.

* MAIN_AUTOFILL_TOWNFROMZIP => Permet le remplissage automatique de la ville depuis le code postal. Ajax ne doit pas etre désactivé pour que cette option fonctionne (Fonction bugguée).

* MAIN_MAIL_ALLOW_SENDMAIL_F => Sur les systèmes Linux ou BSD, la fonction d'envoi de mail de PHP utilise la commande sendmail local au serveur. Dans certains cas, l'email émetteur doit être passé en ligne de commande par l'option -f à sendmail. Cette option permet donc de demander à Dolibarr d'utiliser la fonction '''mail''' de php en intégrant l'option -f. Notons que dans la plupart des cas, même avec sendmail, l'email émetteur est bien géré car intégré avec les autres paramètres dans l'entête technique du mail. Cette option permet juste de passer outre certaines configurations qui rendent obligatoire l'option -f.

* MAIN_DEMO => Désactive certaines fonctions pour rendre l'application figée à certains niveaux. Ceci est requis si Dolibarr est en accès comme site de démo à des utilisateurs qui aiment un peu trop faire n'importe quoi.

* MAIN_USE_HOURMIN_IN_DATE_RANGE => Sur toutes les lignes de détail d'entité (facture, commande, contrat...), il est possible de définir l'heure en plus du jour sur les champs date de début et de fin de services.

* MAIN_SHOW_LOGO => Affiche logo société en haut du menu gauche.

* MAIN_REMOVE_INSTALL_WARNING => Supprime le warning de sécurité apparent aux administrateurs si l'URL /install est accessible. Il est préférable de ne pas utiliser ce paramètre mais de plutôt placer un fichier nommé install.lock dans la racine de Dolibarr, ce qui a pour effet non seulement de supprimer le warning mais aussi d'empêcher tout utilisation de l'outil d'installation et mise à jour (qui ne requiert pas d'habilitation) tant que ce fichier est présent.

* MAIN_DISABLE_FORCE_SAVEAS => Si votre navigateur propose systématiquement d'enregistrer les fichiers sur disques (comme les PDF), essayer d'ajouter cette option. Les fichiers pourront alors s'afficher dans le lecteur du navigateur.

* MAIN_DISABLE_PDF_COMPRESSION => Désactive la compression sur les PDF générés. Ne fonctionne qu'avec certains modèles de génération PDF.

=== Module Propositions Commerciales ===
Aucune

=== Module Factures ===
* FACTURE_ENABLE_RECUR => Active la fonction des factures prédéfinies. Fonction instable.
* FACTURE_VENTILATION => Active une veille fonctionnalité de ventilation comptable. Fonction instable.

=== Module Commandes ===
* COMMANDE_REQUIRE_SOURCE => Rend obligatoire la saisie du champ source lors de la création d'une commande.

=== Module Contrat ===
* CONTRAT_EDITWHENVALIDATED => Rend possible la modification d'un contrat après qu'il ait été validé.

=== Module Agenda ===
* AGENDA_MAX_EVENTS_DAY_VIEW => Défini le nombre max d'entrées visibles pour chaque jour dans l'agenda. Vaut 3 par défaut. La valeur 0 signifie aucune limite.

=== Module Produit ===
* PRODUCT_CANVAS_ABILITY => Autorise les fonctions canvas (Ancien système de module).
Ceci rend visible les fonctions du module de livres basé sur l'ancienne architecture.

=== Module Bookmark ===
* BOOKMARKS_SHOW_IN_MENU => Mettre le nombre de marques-pages qui s'affichent dans le menu gauche.

Premiers paramétrages

2009-02-04T13:12:02Z

Mcg: /* Utilisateurs */

{{TemplateDocUtil}}

Après l'installation proprement dite de Dolibarr, vous devez le paramétrer pour l'adapter à vos besoins avant de le mettre en production.

== Société/Institution ==

Pour commencer, à partir de la page d'accueil, rendez-vous dans la partie "Configuration -> Société/Institution" et éditez les informations de votre institution.
N'oubliez pas d'indiquer votre pays car certaines fonctions (TVA) en dépendent.

== Modules ==

L'activation des modules est très importante. Elle dépend de l'utilisation que vous prévoyez de faire de Dolibarr. Il est très peu probable que vous ayez besoin de la totalité des modules.
Il vous faut donc activer les modules dont vous aurez très probablement besoin. Par exemple: Sociétés, Factures éventuellement Comptabilité.

Si vous n'êtes pas sûr de vous, activez les modules les uns après les autres et voyez les fonctionnalités qu'ils ajoutent dans Dolibarr (vérifiez avant les droits, voir ci-dessous). Il est bien sûr possible de désactiver des modules après coup.

Une fois activés, certains modules nécessitent une configuration supplémentaire (cliquer sur l'icône qui apparait tout à droite sur la même ligne).
Voir, par exemple, pour les factures [[FactureConfiguration]].

== Affichage ==

Cette partie vous permet de choisir la langue et la présentation des pages. Dans un premier temps vous devriez conserver les options par défaut.

== Autres (Boites, Alertes, Sécurité, Limites et précisions, EMails, Dico...) ==
Les autres entrées du menu Configuration sont des options avancées.
Il n'est pas obligatoire de les parcourir.

== Utilisateurs ==
La dernière étape consiste à créer les utilisateurs et à attribuer les permissions.
Presque tous les modules, même activés précédemment, ne sont pas accessibles si on n'en donne pas la permission.
Pour cela, vous pouvez vous rendre dans le menu '''Accueil -> Utilisateurs & Groupes''' pour définir les utilisateurs et leurs droits. Attention, il faudra penser à vérifier et redéfinir les droits utilisateurs quand vous activerez à nouveau de nouveaux modules.
La liste des droits disponibles dépendant des modules activés (voir plus haut), il est recommandé de configurer cette partie après avoir activé les modules désirés.
Pour certaines actions, si vous n'avez pas les droits pour faire une action, Dolibarr ne vous la proposera pas. Vous risquez de rater des choses utiles et/ou importantes.
Pour donner les droits à un utilisateur ou vous-même si vous êtes administrateur, aller dans '''Accueil -> Utilisateurs & Groupes''', choisissez la fiche de l'utilisateur désiré, puis cliquer sur l'onglet '''Permission'''.

== Quelques options cachées ==
Quelques options non visibles dans les interfaces (souvent car en bêta ou en expérimentation) sont disponibles. Dans la plupart des cas, vous n'avez pas besoin de ces fonctions et leur utilisation peu rendre instable l'application.

Pour les activer il faut définir une constante à 1 dans '''Accueil - Configuration - Divers''':

=== Options globales ===
* MAIN_APPLICATION_TITLE => Permet de définir le nom de l'application (qui apparait sur la page de login par defaut).

* MAIN_CONFIRM_AJAX => Si cette constante est définie (à autre chose que 0), le message de confirmation de suppression de lignes de facture, propal, etc, est une popup Ajax, au lieu d'un formulaire affiché par rechargement de la page.

* MAIN_DISABLE_FULL_SCANLIST => Constante à définir pour désactiver le scan complet des tables afin de connaitre le nombre total d'éléments pour permettre des paginations affichant le nombre de pages. A activer sur les systèmes ayant un nombre très important de données (Tables de + de 500 000 enregistrements).

* MAIN_AUTOFILL_DATE => Si cette constante est définie (à autre chose que 0), la date de facture, propal, commande ou paiement est préremplie avec la date du jour. Il est fortement recommandé de NE PAS ACTIVER cette option, ceci générant une saisie sans validation de la part des utilisateurs sur les dates, ce qui se traduit par des données incorrectes enregistrées et un beau casse tête lorsqu'il faut faire sa compta ! Toutefois l'option reste disponible, à la demande de certains utilisateurs.

* MAIN_AUTOFILL_TOWNFROMZIP => Permet le remplissage automatique de la ville depuis le code postal. Ajax ne doit pas etre désactivé pour que cette option fonctionne (Fonction bugguée).

* MAIN_MAIL_ALLOW_SENDMAIL_F => Sur les systèmes Linux ou BSD, la fonction d'envoi de mail de PHP utilise la commande sendmail local au serveur. Dans certains cas, l'email émetteur doit être passé en ligne de commande par l'option -f à sendmail. Cette option permet donc de demander à Dolibarr d'utiliser la fonction '''mail''' de php en intégrant l'option -f. Notons que dans la plupart des cas, même avec sendmail, l'email émetteur est bien géré car intégré avec les autres paramètres dans l'entête technique du mail. Cette option permet juste de passer outre certaines configurations qui rendent obligatoire l'option -f.

* MAIN_DEMO => Désactive certaines fonctions pour rendre l'application figée à certains niveaux. Ceci est requis si Dolibarr est en accès comme site de démo à des utilisateurs qui aiment un peu trop faire n'importe quoi.

* MAIN_USE_HOURMIN_IN_DATE_RANGE => Sur toutes les lignes de détail d'entité (facture, commande, contrat...), il est possible de définir l'heure en plus du jour sur les champs date de début et de fin de services.

* MAIN_SHOW_LOGO => Affiche logo société en haut du menu gauche.

* MAIN_REMOVE_INSTALL_WARNING => Supprime le warning de sécurité apparent aux administrateurs si l'URL /install est accessible. Il est préférable de ne pas utiliser ce paramètre mais de plutôt placer un fichier nommé install.lock dans la racine de Dolibarr, ce qui a pour effet non seulement de supprimer le warning mais aussi d'empêcher tout utilisation de l'outil d'installation et mise à jour (qui ne requiert pas d'habilitation) tant que ce fichier est présent.

* MAIN_DISABLE_FORCE_SAVEAS => Si votre navigateur propose systématiquement d'enregistrer les fichiers sur disques (comme les PDF), essayer d'ajouter cette option. Les fichiers pourront alors s'afficher dans le lecteur du navigateur.

* MAIN_DISABLE_PDF_COMPRESSION => Désactive la compression sur les PDF générés. Ne fonctionne qu'avec certains modèles de génération PDF.

=== Module Propositions Commerciales ===
Aucune

=== Module Factures ===
* FACTURE_ENABLE_RECUR => Active la fonction des factures prédéfinies. Fonction instable.
* FACTURE_VENTILATION => Active une veille fonctionnalité de ventilation comptable. Fonction instable.

=== Module Commandes ===
* COMMANDE_REQUIRE_SOURCE => Rend obligatoire la saisie du champ source lors de la création d'une commande.

=== Module Contrat ===
* CONTRAT_EDITWHENVALIDATED => Rend possible la modification d'un contrat après qu'il ait été validé.

=== Module Agenda ===
* AGENDA_MAX_EVENTS_DAY_VIEW => Défini le nombre max d'entrées visibles pour chaque jour dans l'agenda. Vaut 3 par défaut. La valeur 0 signifie aucune limite.

=== Module Produit ===
* PRODUCT_CANVAS_ABILITY => Autorise les fonctions canvas (Ancien système de module).
Ceci rend visible les fonctions du module de livres basé sur l'ancienne architecture.

=== Module Bookmark ===
* BOOKMARKS_SHOW_IN_MENU => Mettre le nombre de marques-pages qui s'affichent dans le menu gauche.

Développement de scripts

2009-02-04T13:08:18Z

Mcg: /* Développer un nouveau script */

{{TemplateDocDev}}

== Localisation ==
Les scripts en ligne de commande de Dolibarr doivent être situés dans le répertoire '''scripts''' de Dolibarr. Les scripts sont ensuite répartis dans des sous-répertoires en fonction de leur vocation.
Un certain nombre de scripts est donc fourni en standard.

== Développer un nouveau script ==
Les scripts étant souvent réalisés pour un besoin spécifique, il y a de fortes chances que vous ne trouviez pas celui qui vous intéresse. Dans ce cas, nous allons vous expliquer comment développer votre propre script.

=== Etape 1 - Création du squelette du script ===
La première étape est de reprendre le squelette de script disponible en '''dev/skeletons/skeleton_scripts.php''' et de le recopier en renommant, ce script dans le répertoire '''scripts/monrep/monscript.php'''

Une fois le script renommé, donnez lui les droits en exécution par la commande:
<pre>
cd scripts/monrep;
chmod a+rx monscript.php
</pre>
Ensuite, lancez le pour voir si vous pouvez exécuter un script en mode ligne de commande. Pour cela, taper:
<pre>php-cli ./monscript.php
ou
php ./monscript.php</pre>
Vous devriez obtenir le résultat suivant:
<pre>
Usage: monscript.php param1 param2 ...
</pre>

=== Etape 2 - Edition du code du script ===
Modifier le contenu du script pour réaliser les opérations qui vous intéressent.
Tout le code qui se trouve entre les balises
<pre>// ---------- START OF YOUR CODE HERE</pre>
et
<pre>// ---------- END OY YOUR CODE</pre>
est fourni à titre d'exemple.
Vous pouvez le supprimer et y mettre le code qui vous intéresse.
Notez que dans cette portion, vous pouvez utiliser la variable $db qui est la ressource d'accès à la base Dolibarr et qui est déjà initialisée.
L'objet $conf qui contient la configuration Dolibarr est également disponible.

==== Exemple insertion d'un produit ====
Par exemple pour insérer un produit dans la base dolibarr, vous pouvez y placer le code suivant:
<pre>
// Inclusion classe métier utilisateur et product
require_once(DOL_DOCUMENT_ROOT."/user.class.php");
require_once(DOL_DOCUMENT_ROOT."/product.class.php");

// Création d'une instance utilisateur
$user=new User($db);

// Création d'une instance de product
$myproduct=new Product($db);

// Définition des propriétés de l'instance utilisateur
$user->id = 0;

// Définition des propriétés de l'instance product
$product->ref = '1234'
$product->libelle = 'libelle';
$product->price = '10';
$product->price_base_type = 'HT';
$product->tva_tx = '19.6';
$product->type = 0;
$product->status = 1;
$product->description = 'Description';
$product->note = 'Note';
$product->weight = 10;
$product->weight_units = 0;

// Création du produit en base
$idproduct = $product->create($user);

// Gestion erreur
if ($idproduct < 0) dolibarr_print_error($db,$product->error);
else print "Produit $idproduct cree.\n";
</pre>

Développement de scripts

2009-02-04T13:05:58Z

Mcg: /* Localisation */

{{TemplateDocDev}}

== Localisation ==
Les scripts en ligne de commande de Dolibarr doivent être situés dans le répertoire '''scripts''' de Dolibarr. Les scripts sont ensuite répartis dans des sous-répertoires en fonction de leur vocation.
Un certain nombre de scripts est donc fourni en standard.

== Développer un nouveau script ==
Les scripts étant souvent réalisés pour un besoin spécifiques, il y a de forte chance que vous ne trouviez pas celui qui vous intéresse. Dans ce cas, nous allons vous expliquer comment développer votre propre script.

=== Etape 1 - Création du squelette du script ===
La première étape est de reprendre le squelette de script disponible en '''dev/skeletons/skeleton_scripts.php''' et de recopier en le renommant, ce script dans le répertoire '''scripts/monrep/monscript.php'''

Une fois le script renommé, donnez lui les droits en exécution par la commande:
<pre>
cd scripts/monrep;
chmod a+rx monscript.php
</pre>
Ensuite, lancez le pour voir si vous pouvez exécuter un script en mode ligne de commande. Pour cela, taper:
<pre>php-cli ./monscript.php
ou
php ./monscript.php</pre>
Vous devriez obtenir le resultat suivant:
<pre>
Usage: monscript.php param1 param2 ...
</pre>

=== Etape 2 - Edition du code du script ===
Modifier le contenu du script pour réaliser les opérations qui vous intéressent.
Tout le code qui se trouve entre les balises
<pre>// ---------- START OF YOUR CODE HERE</pre>
et
<pre>// ---------- END OY YOUR CODE</pre>
est fourni à titre d'exemple.
Vous pouvez le supprimer et y mettre le code qui vous intéresse.
Notez que dans cette portion, vous pouvez utiliser la variable $db qui est la ressource d'accès à la base Dolibarr et qui est déjà initialisée.
L'objet $conf qui contient la configuration Dolibarr est également disponible.

==== Exemple insertion d'un produit ====
Par exemple pour insérer un produit dans la base dolibarr, vous pouvez y placer le code suivant:
<pre>
// Inclusion classe métier utilisateur et product
require_once(DOL_DOCUMENT_ROOT."/user.class.php");
require_once(DOL_DOCUMENT_ROOT."/product.class.php");

// Création d'une instance utilisateur
$user=new User($db);

// Création d'une instance de product
$myproduct=new Product($db);

// Définition des propriétés de l'instance utilisateur
$user->id = 0;

// Définition des propriétés de l'instance product
$product->ref = '1234'
$product->libelle = 'libelle';
$product->price = '10';
$product->price_base_type = 'HT';
$product->tva_tx = '19.6';
$product->type = 0;
$product->status = 1;
$product->description = 'Description';
$product->note = 'Note';
$product->weight = 10;
$product->weight_units = 0;

// Création du produit en base
$idproduct = $product->create($user);

// Gestion erreur
if ($idproduct < 0) dolibarr_print_error($db,$product->error);
else print "Produit $idproduct cree.\n";
</pre>

Imports de masse - Migrer mes données dans Dolibarr

2009-02-04T13:05:12Z

Mcg: /* Import des tiers et contacts */

{{TemplateDocDev}}
Suite à une installation neuve de Dolibarr, les bases sont vides. Parfois on désire démarrer avec des données importées d'un autre système.
Voici quelques informations pour vous y aider.

== Utiliser le module Import de Dolibarr ==
Ce module n'est pas encore disponible.
Il est en cours de développement.

En attendant, vous devez développer vos propres scripts d'import comme décrit dans le chapitre suivant.

== Développer son propre script d'import ==

=== Import des tiers et contacts ===
Il faut distinguer les tiers des contacts physiques.
Dans les tiers on aura toutes les entités sujetes à facturation (aussi bien entreprises, association que particuliers). Les tiers sont obligatoires.
Les contacts physiques sont optionels. Il s'agit juste d'un annuaire de personnes (avec téléphone et fonction) liées à un tiers. Dans le cas d'un tiers entreprise, il pourra y avoir plusieurs contacts physiques. Dans le cas d'un particulier, le contact physique sera unique et identique au tiers (voire le contact physique ne sera pas renseigné).

L'import des tiers consiste à insérer des lignes dans la table [[Table llx_societe]].
S'assurer que les champs importants sont bien renseignés:
* Nom: Doit contenir le nom de la société
* Client: Doit contenir 1 si client, 2 si prospect, 0 sinon
* Fournisseur: Doit contenir 1 si fournisseur, 0 sinon

L'import des contacts physiques consiste à insérer des lignes dans la table [[Table llx_socpeople]].
S'assurer que les champs importants sont bien renseignés:
* Name: Doit contenir le nom de la personne
* Firstname: Doit contenir le prénom de la société
* fk_soc: Doit contenir l'id de la ligne Tiers dans la [[Table llx_societe]].

=== Import des factures ===
A compléter

=== Mise en pratique ===

La page [[Developpement script]] vous explique comment créer votre propre script de traitement Dolibarr.
Des exemples sont fournis sur des cas de chargement de données.

Imports de masse - Migrer mes données dans Dolibarr

2009-02-04T13:01:24Z

Mcg: /* Utiliser le module Import de Dolibarr */

{{TemplateDocDev}}
Suite à une installation neuve de Dolibarr, les bases sont vides. Parfois on désire démarrer avec des données importées d'un autre système.
Voici quelques informations pour vous y aider.

== Utiliser le module Import de Dolibarr ==
Ce module n'est pas encore disponible.
Il est en cours de développement.

En attendant, vous devez développer vos propres scripts d'import comme décrit dans le chapitre suivant.

== Développer son propre script d'import ==

=== Import des tiers et contacts ===
Il faut distinguer les tiers des contacts physiques.
Dans les tiers on aura toutes les entités sujetes à facturation (aussi bien entreprises, association que particuliers). Les tiers sont obligatoires.
Les contacts physiques sont optionels. Il s'agit juste d'un annuaire de personnes (avec téléphone et fonction) liées à un tiers. Dans le cas d'un tiers entreprise, il pourra y avoir plusieurs contacts physiques. Dans le cas d'un particulier, le contact physique sera unique et identique au tiers (voire le contact physique ne sera pas renseigné).

L'import des tiers consiste à insérer des lignes dans la table [[Table llx_societe]].
S'assurer que les champs important sont bien renseigné:
* Nom: Doit contenir le nom de la société
* Client: Doit contenir 1 si client, 2 si prospect, 0 sinon
* Fournisseur: Doit contenir 1 si fournisseur, 0 sinon

L'import des contacts physiques consiste à insérer des lignes dans la table [[Table llx_socpeople]].
S'assurer que les champs important sont bien renseigné:
* Name: Doit contenir le nom de la personne
* Firstname: Doit contenir le prénom de la société
* fk_soc: Doit contenir l'id de la ligne Tiers dans la [[Table llx_societe]].

=== Import des factures ===
A compléter

=== Mise en pratique ===

La page [[Developpement script]] vous explique comment créer votre propre script de traitement Dolibarr.
Des exemples sont fournis sur des cas de chargement de données.

Installation - Mise à jour

2009-02-04T12:59:14Z

Mcg: /* Procédure d'installation manuelle */

{{TemplateDocUtil}}

Les procédures suivantes décrivent comment installer ou mettre à jour Dolibarr sur une plateforme Linux, sans package particulier.

Si vous chercher un mode opératoire pour Windows, celui-ci peut être adapté. Toutefois, il existe aussi une distribution Dolibarr nommée '''DoliWamp''' qui permet de faire une installation Dolibarr sous Windows avec tous les prérequis (Apache, Mysql, PHP) sans connaissance informatique (Voir la page de [http://www.nltechno.com/pages/dolibarrwinbin.php téléchargement de DoliWamp chez NLTechno]).

Si vous êtes sous Linux et avez déjà un serveur Apache, Mysql et PHP d'opérationnel, les chapitres suivants vous présentent comment installer et mettre à jour une version de Dolibarr.

== Procédure d'installation manuelle ==

Prérequis: Apache, Mysql et PHP sont présent et opérationnel.

Cette procédure décrit l'installation manuelle (recommandée) sur un système GNU/Linux (Debian, Mandriva, ...), elle est valable avec d'autres systèmes moyennant quelques modifications.
Elle est applicable pour toute version de Dolibarr >= 2.0.0

* Vérifiez que vous avez bien Apache, Mysql et PHP d'installés (consulter pour cela la liste des packages installés sur votre machine grâce au gestionnaire de mise à jour de package de votre distribution).

* Placez-vous dans le répertoire dans lequel installer Dolibarr (le répertoire racine défini pour votre serveur web)
$ cd /var/www
# Pour Debian et les familles Ubuntu, il s'agit en général de: /var/www
# Pour Mandriva: /var/www/html
# Pour RedHat: à compléter
# Pour Suse: à compléter

* Récupérez l'archive de l'application
$ wget http://www.dolibarr.org/files/dolibarr.tgz

* Décompressez l'archive
$ tar xvfz dolibarr.tgz

* Renommez le répertoire dolibarr-x.y.z en dolibarr afin d'avoir un nom de répertoire indépendant de la version (où x.y.z correspond à la version source)
$ mv dolibarr-x.y.z dolibarr

* En tant que root, créez, dans le répertoire dolibarr/htdocs/conf, un fichier de configuration vide, et attribuez-lui comme propriétaire du fichier, l'utilisateur du serveur web (exemple www-data sur debian, nobody sur une vieille RedHat, apache sur une autre version ...). Ceci est requis car le serveur web a besoin d'écrire dans ce fichier lors de l'installation.
$ cd dolibarr ; touch htdocs/conf/conf.php ; chown www-data htdocs/conf/conf.php

* Toujours en root, créez le répertoire qui servira aux documents générés ou stockés par Dolibarr (factures pdf, images, ...), et attribuez lui comme propriétaire, l'utilisateur du serveur web (exemple www-data sur Debian, nobody sur une vieille RedHat, Apache sur une Mandriva ou une RedHat récente, ...). Le serveur web doit avoir les droits en écriture dans ce répertoire.
$ mkdir documents ; chown www-data documents

* Pointez votre navigateur sur la page principale
http://127.0.0.1/dolibarr/htdocs/

* Suivez les instructions de l'installation

* Pour des raisons de sécurité nous vous conseillons, une fois l'installation terminée, de créer un fichier install.lock dans le répertoire d'installation, que seul root doit avoir le droit d'effacer.
$ touch /var/www/dolibarr/install.lock; chmod ug-w /var/www/dolibarr;

== Procédure de mise à jour manuelle ==

Cette procédure décrit la mise à jour manuelle de Dolibarr (depuis une ancienne version) vers une plus récente.
Elle est applicable dès lors que la mise à jour se fait pour une version de Dolibarr >= 2.0.0

* Placez-vous dans le répertoire dans lequel a été installé Dolibarr (le répertoire racine de votre serveur web, par exemple /var/www sous Debian)
$ cd /var/www

* Récupérez l'archive de la nouvelle version
$ wget http://www.nltechno.com/files/dolibarr.tgz

* Décompressez l'archive
$ tar xvfz dolibarr.tgz

* Recopiez les nouveaux fichiers (qui ont été décompressés dans le répertoire dolibarr-x.y.z) vers le répertoire où vous avez votre ancienne version de Dolibarr
$ cp -r dolibarr-x.y.z/* dolibarr

* Vous pouvez alors supprimer le répertoire des fichiers sources
$ rm -fr dolibarr-x.y.z

* Pointez votre navigateur sur la page d'install
http://127.0.0.1/dolibarr/install/

* Choisissez ''Mise à jour'' dans le menu proposé

* Pour des raisons de sécurité nous vous conseillons, une fois la mise à jour terminée, de verrouiller le répertoire d'installation. Dans le cas contraire, Dolibarr vous avertira d'un message dans l'interface une fois loggé
$ echo > dolibarr/install.lock
$ chmod 444 dolibarr/install.lock

== Configurer une connexion LDAP ==

A compléter.

== Importer des données externes ==

Pour cette opération, consulter la page [[Imports_de_masse]].

Installation - Mise à jour

2009-02-04T12:57:04Z

Mcg:

{{TemplateDocUtil}}

Les procédures suivantes décrivent comment installer ou mettre à jour Dolibarr sur une plateforme Linux, sans package particulier.

Si vous chercher un mode opératoire pour Windows, celui-ci peut être adapté. Toutefois, il existe aussi une distribution Dolibarr nommée '''DoliWamp''' qui permet de faire une installation Dolibarr sous Windows avec tous les prérequis (Apache, Mysql, PHP) sans connaissance informatique (Voir la page de [http://www.nltechno.com/pages/dolibarrwinbin.php téléchargement de DoliWamp chez NLTechno]).

Si vous êtes sous Linux et avez déjà un serveur Apache, Mysql et PHP d'opérationnel, les chapitres suivants vous présentent comment installer et mettre à jour une version de Dolibarr.

== Procédure d'installation manuelle ==

Prérequis: Apache, Mysql et PHP sont présent et opérationnel.

Cette procédure décrit l'installation manuelle (recommandée) sur un système GNU/Linux (Debian, Mandriva, ...), elle est valable avec d'autres systèmes moyennant quelques modifications.
Elle est applicable pour toute version de Dolibarr >= 2.0.0

* Vérifiez que vous avez bien Apache, Mysql et PHP d'installés (consulter pour cela la liste des packages installés sur votre machine grâce au gestionnaire de mise à jour de package de votre distribution).

* Placez-vous dans le répertoire dans lequel installer Dolibarr (le répertoire racine défini pour votre serveur web)
$ cd /var/www
# Pour Debian et les familles Ubuntu, il s'agit en général de: /var/www
# Pour Mandriva: /var/www/html
# Pour RedHat: à compléter
# Pour Suse: à compléter

* Récupérez l'archive de l'application
$ wget http://www.dolibarr.org/files/dolibarr.tgz

* Décompressez l'archive
$ tar xvfz dolibarr.tgz

* Renommez le répertoire dolibarr-x.y.z en dolibarr afin d'avoir un nom de répertoire indépendant de la version (ou x.y.z correspond a la version source)
$ mv dolibarr-x.y.z dolibarr

* En tant que root, créez, dans le répertoire dolibarr/htdocs/conf, un fichier de configuration vide, et attribuez-lui comme propriétaire du fichier, l'utilisateur du serveur web (exemple www-data sur debian, nobody sur une vieille RedHat, apache sur une autre version ...). Ceci est requis car le serveur web a besoin d'écrire dans ce fichier lors de l'installation.
$ cd dolibarr ; touch htdocs/conf/conf.php ; chown www-data htdocs/conf/conf.php

* Toujours en root, créez le répertoire qui servira aux documents générés ou stockés par Dolibarr (factures pdf, images, ...), et attribuez lui comme propriétaire, l'utilisateur du serveur web (exemple www-data sur Debian, nobody sur une vieille RedHat, Apache sur une Mandriva ou une RedHat récente, ...). Le serveur web doit avoir les droits en écriture dans ce répertoire.
$ mkdir documents ; chown www-data documents

* Pointez votre navigateur sur la page principale
http://127.0.0.1/dolibarr/htdocs/

* Suivez les instructions de l'installation

* Pour des raisons de sécurité nous vous conseillons, une fois l'installation terminée, de créer un fichier install.lock dans le répertoire d'installation, que seul root doit avoir le droit d'effacer.
$ touch /var/www/dolibarr/install.lock; chmod ug-w /var/www/dolibarr;

== Procédure de mise à jour manuelle ==

Cette procédure décrit la mise à jour manuelle de Dolibarr (depuis une ancienne version) vers une plus récente.
Elle est applicable dès lors que la mise à jour se fait pour une version de Dolibarr >= 2.0.0

* Placez-vous dans le répertoire dans lequel a été installé Dolibarr (le répertoire racine de votre serveur web, par exemple /var/www sous Debian)
$ cd /var/www

* Récupérez l'archive de la nouvelle version
$ wget http://www.nltechno.com/files/dolibarr.tgz

* Décompressez l'archive
$ tar xvfz dolibarr.tgz

* Recopiez les nouveaux fichiers (qui ont été décompressés dans le répertoire dolibarr-x.y.z) vers le répertoire où vous avez votre ancienne version de Dolibarr
$ cp -r dolibarr-x.y.z/* dolibarr

* Vous pouvez alors supprimer le répertoire des fichiers sources
$ rm -fr dolibarr-x.y.z

* Pointez votre navigateur sur la page d'install
http://127.0.0.1/dolibarr/install/

* Choisissez ''Mise à jour'' dans le menu proposé

* Pour des raisons de sécurité nous vous conseillons, une fois la mise à jour terminée, de verrouiller le répertoire d'installation. Dans le cas contraire, Dolibarr vous avertira d'un message dans l'interface une fois loggé
$ echo > dolibarr/install.lock
$ chmod 444 dolibarr/install.lock

== Configurer une connexion LDAP ==

A compléter.

== Importer des données externes ==

Pour cette opération, consulter la page [[Imports_de_masse]].

Projet Dolibarr

2009-02-04T11:05:14Z

Mcg: /* Les acteurs et leurs rôles */

Cette page les différents postes occupés dans le projet Dolibarr ainsi que les postes à pourvoir.

== Les acteurs et leurs rôles ==

L'équipe Dolibarr actuelle est constituée de différents responsables, soutenus voire sponsorisés par divers contributeurs physiques ou sociétés.
Les lignes suivantes présentent les différents rôles et postes occupés dans la gestion du projet Dolibarr.
De nombreux rôles et postes sont à pourvoir. Les volontaires pour postuler à une responsabilité dans le projet sont invités à se manifester sur la mailing list dev de Dolibarr.
Pour juste aider au développement, voir la page [[FAQ_D%C3%A9veloppeur#Comment_devenir_d.C3.A9veloppeur_officiel|FAQ Développeur - Comment devenir développeur officiel]]

=== Les rôles développeurs ===
<hr>

==== Développeur grade [[FAQ_Développeur#Comment_devenir_d.C3.A9veloppeur_officiel|Yoda]] (Chefs de projet commiteurs CVS, tous modules) ====

Objectif: Gérer le projet Dolibarr au sens large.

Ont ce rôle actuellement (par ordre alphabétique):
* [[Laurent Destailleur]] ([http://www.nltechno.com NLTechno]) - Contributeur / Mainteneur officiel
* [[Régis Houssin]] - Contributeur
* [[Rodolphe Quiédeville]] - Créateur / ex-Mainteneur (2002 à juin 2008)

Fonction à pourvoir: Non

==== Développeur grade [[FAQ_Développeur#Comment_devenir_d.C3.A9veloppeur_officiel|Jedi]] module X (Chefs de projet commiteurs CVS, module X) ====

Objectif: Externaliser le développement de nouveaux modules en dehors des équipes qui forment le noyau dur des développements Dolibarr.

A ce rôle actuellement pour module OSCommerce:
* [[Jean Heimburger]] ([http://www.tiaris.fr Tiaris])
Fonction à pourvoir pour module X: Oui pour les modules n'existant pas et à créer (1 responsable par module). Se manifester pour endosser ce rôle avec une idée de nouveau module.

==== Développeur grade [[FAQ_Développeur#Comment_devenir_d.C3.A9veloppeur_officiel|Amiral]] (Commiteurs CVS, patch correctifs) ====

Objectif: Développer, intégrer ou simplement valider et commiter dans le CVS, les '''patchs correctifs'''.

Ce n'est qu'au bout d'un temps variable (qui peut être très long) au rang de Chasseur, et si la qualité des patch qui ont été envoyée est satisfaisante, qu'un Maitre Yoda en place vous offrira un accès CVS direct. Vous êtes devenu un Amiral de l'alliance Dolibarr.

Ce titre ne se demande pas, il s'obtient par décision ou proposition d'un Jedi ou Maitre Yoda qui estime que vous avez soumis suffisamment de patch pour être un sérieux Amiral. L'accès CVS d'un Amiral doit cependant n'être utilisé que pour commiter soit des traductions, soit des corrections de bugs déclarées sur Savannah ou le forum (que ces corrections soit personnelles ou issues d'un patch soumis par un Chasseur). Tout commit CVS doit ainsi obligatoirement inclure, dans la description (le champ log de commit), le numéro du bug Savannah corrigé OU le titre du message du forum signalant le problème. Seul une traduction échappe à cette contrainte (pas de restrictions pour les traductions). Le non respect de cette contrainte, peut provoquer une rétrogradation au rang de Chasseur. Pour la soumission de nouvelles fonctionnalités, il faut donc obligatoirement continuer sur le principe de patchs envoyés sur la ML.

L'obtention du grade d'Amiral est toutefois rare car limité. La qualité de Dolibarr ne pouvant être atteinte que par un nombre d'Amiraux contrôlé, ce qui n'empêche pas d'avoir un nombre de développeurs (Chasseurs) très important (grâce au système de patch).

Fonction à pourvoir: Oui (Ce rôle ne s'obtient pas toutefois simplement en postulant, Voir [[FAQ_Développeur#Comment_devenir_d.C3.A9veloppeur_officiel|Comment_devenir_développeur_officiel]] pour le circuit à suivre)

Identifiés comme ayant ce rôle actuellement ou récemment (comptes validés dans savannah, par ordre alphabétique) :
* [[Marc Barilley]] (marc_ocebo)
* [[Jean-Louis Bergamo]] (jbergamo) - Désengagé.
* [[Raphaël Bertrand]] (raphael_bertrand)
* [[Guillaume Carta]] (bouda)
* [[André Cianfarini]] (andre)
* [[Christophe Combelles]] (ccomb)
* [[Cyrille de Lambert]] (cdelambert) - Auguria (http://www.auguria.net)
* [[Loic Le Bleis]] (activedev)
* [[Gaëtan Frenoy]] (gfrenoy)
* [[Julien Jehl]] (jjehl)
* [[Juanjo Menent]] (simnandez)
* [[Benoit Mortier]] - Désengagé.
* [[Marc Henry Parmiseux]] (marconi)
* [[Paul Pulain]] (tipaul)
* [[Patrick Raguin]] (patrickrgn)
* [[Eric Seigne]] (erics)
* [[Simon Tosser]] (simontosser)
* [[Yannick Warnier]] (ywarnier)
+ Les développeurs de grade supérieurs.

==== Développeur grade [[FAQ_Développeur#Comment_devenir_d.C3.A9veloppeur_officiel|Chasseur]] (Soumission fichier patch) ====

Objectif: Intégrer et commiter dans le CVS, les patchs correctifs de bogues.

Fonction à pourvoir: Oui (sans limite. Patch à soumettre sur la Mailing-List dev Dolibarr)

Identifiés comme ayant ce rôle actuellement:
* Nombre trop variable pour être recensé.

==== Développeur grade [[FAQ_Développeur#Comment_devenir_d.C3.A9veloppeur_officiel|Membre alliance]] (Utilisateur n'ayant jamais soumis de correctifs) ====

Objectif: Soumettre son premier patch pour passer au grade chasseur.

Fonction à pourvoir: Oui (sans limite. Patch à soumettre sur la Mailing-List dev Dolibarr)

Identifiés comme ayant ce rôle actuellement:
* Impossible à déterminer.

=== Les autres rôles dans le projet Dolibarr (Rôle A à J) ===
<hr>

==== Role A: Hébergement site web (dolibarr.fr et dolibarr.org) ====

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

A ce rôle actuellement:
* [[Régis Houssin]]

Fonction à pourvoir: Non

==== Role B: Hébergement site démo (http://demo.dolibarr.org) ====

Objectif: Fournir et maintenir une plateforme d'hébergement du site de démo online Dolibarr.

A ce rôle actuellement:
* [[Laurent Destailleur]] ([http://www.nltechno.com NLTechno])

Fonction à pourvoir: Non

==== Role C: Hébergement wiki (wiki.dolibarr.org) ====

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

A ce rôle actuellement:
* [[Laurent Destailleur]] ([http://www.nltechno.com NLTechno])

Fonction à pourvoir: Non

==== Role D: Responsable distribution DoliWamp (Installeur Dolibarr pour Windows) ====

A ce rôle actuellement:
* [[Laurent Destailleur]] ([http://www.nltechno.com NLTechno])

Fonction à pourvoir: Non

==== Role E: Outils de création de modules par MDA (UML2Dolibarr) ====

Identifiés comme ayant ce rôle actuellement ou récemment:
* [[Patrick Raguin]] (Société [http://www.auguria.net/ Auguria])
* [[Samuel Bouchet]] (Société [http://www.auguria.net/ Auguria])

Fonction à pourvoir: Voir société Auguria si reprise envisagée de l'outil.

==== Role F: 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:
* [[Cyrille De Lambert]] (Société [http://www.auguria.net/ Auguria])
* A pourvoir (1 président, 1 trésorier, 1 secrétaire).

Articles en relation: [[AssociationDolibarr]]

==== Role G: Animation du site Web Dolibarr ====

Objectif: Saisie régulièrement des news et articles en anglais et français sur le site Web Dolibarr

Identifiés comme ayant ce rôle actuellement:
* Fonction à pourvoir. Merci aux amateurs de se manifester sur la ML Dolibarr. Volontaires fortement désirés.

==== 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]] et [[Presse en ligne]]).
* Saisir des articles sur le site Dolibarr.

Identifiés comme ayant ce rôle actuellement:
* [[Cyrille de Lambert]] (cdelambert) - Auguria (http://www.auguria.net)
* 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: Traducteur langue X ====

Objectif: Traduire Dolibarr dans d'autres langues. Consolider les traductions existantes.

Identifiés comme ayant ce rôle actuellement:
* Fonction à pourvoir. Pas de limite dans le nombre.
1 responsable par langue serait suffisant, mais plus serait mieux.
* Français: [[Laurent Destailleur]] (eldy)
* Anglais: [[Laurent Destailleur]] (eldy)
* Espagnol: [[Juanjo Menent]] (simnandez)
* Portugais:
* Italien:
* Allemand:
* Hollandais:
* Allemand:
* Finlandais:
* Roumain:
* Russe:
* Danois:
* Norvégien:
* Polonais:

Articles en relation: [[Documentation traducteur]]

==== Role J: Testeur Dolibarr ====

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

Identifiés comme ayant ce rôle actuellement:
* Une cinquantaines de personnes régulières environ (chiffre obtenu par analyse des messages du forum), beaucoup plus si on intègre les rapporteurs occasionnels.

== Les accès CVS ==

Le serveur CVS est hébergé chez savannah.
* Les instructions d'accès au CVS en lecture pour récupérer la version courante de développement sont sur [https://savannah.nongnu.org/cvs/?group=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]]) pour connaître l'organisation du projet et les étapes à franchir avant d'atteindre ce but.

Un suivi graphique des commits CVS de la branche principale de développement est également disponible sur la page [http://www.nltechno.com/stats/dolibarr/cvschangelogbuilder_dolibarr.html suivante].

== Les Mailing-lists ==

Le serveur de mailing-list est hébergé chez savannah.
Les instructions d'accès au CVS sont sur [https://savannah.nongnu.org/mail/?group=dolibarr cette page]

Lire la [[FAQ Développeur]] pour plus d'informations.

== Actions dans les cartons ==
* Mettre en place backup croisé joomla / demo-wiki (a faire)
* Appel a développeur (a faire)
* Création association (en cours, voir [[AssociationDolibarr]])
* Intégration module caisse (en cours)
* Développer les taches en priorité High pour releaser la 2.6

Fichier de configuration

2009-02-03T19:21:31Z

Mcg:

{{TemplateDocDev}}

Le fichier de configuration de Dolibarr est '''conf/conf.php'''. Il est écrit par la procédure d'installation automatisée.
Le contenu du fichier standard est :

$dolibarr_main_document_root="/home/www/dolibarr/htdocs";
$dolibarr_main_url_root="http://mondomaine.com/dolibarr";
$dolibarr_main_db_type="mysql";
$dolibarr_main_db_host="localhost";
$dolibarr_main_db_name="dolibarr";
$dolibarr_main_db_user="dolibarr";
$dolibarr_main_db_pass="";

Dolibarr fournit un fichier conf modèle nommé conf/conf.php.example où chaque paramètre est commenté.

Ce fichier ne doit pas jamais être ni modifié, ni lu directement, par aucune fonctionnalité de Dolibarr.

Il est créé par la procédure d'installation ou de mise a jour de Dolibarr (install/index.php) qui est la seule habilitée à effectuer des actions sur ce fichier.

Le contenu de ce fichier est accessible au développement à travers de constantes ou de l'objet '''$conf''' créé par le script '''master.inc.php''' qui est appelé par tout programme PHP (scripts ou pages).

Ainsi:
# $dolibarr_main_document_root est connu dans le code grâce à la constante: DOL_DOCUMENT_ROOT
# $dolibarr_main_url_root est connu dans le code grâce à la constante: DOL_URL_ROOT
# $dolibarr_main_db_type est accessible par $conf->db->type
# $dolibarr_main_db_host est accessible par $conf->db->host
# $dolibarr_main_db_name est accessible par $conf->db->name
# $dolibarr_main_db_user est accessible par $conf->db->login
# $dolibarr_main_db_pass n'est pas accessible. Il est lu par le script '''master.inc.php''' (appelé par tout fichier PHP) qui crée un connexion db puis efface de sa mémoire le mot de passe.

Normalement, vos développements ne devraient avoir besoin que des constantes DOL_DOCUMENT_ROOT (qui indique le chemin physique du répertoire de stockage de fichiers temporaires ou à conserver) et DOL_URL_ROOT (qui indique le chemin URL vers le répertoire racine de Dolibarr).
D'autres informations et objets sont disponibles après insertion de l'include de '''master.inc.php''' dans son code. Voir les tutoriaux sur le développements de modules Dolibarr pour plus d'information.

Langages et normes

2009-02-03T19:16:37Z

Mcg: /* Communication Logique métier - Données (ORM): */

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

== Normes PHP ==

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

* L'appel aux variables superglobales PHP doit passer par les opérateurs dédiés $_GET, $_POST, $_COOKIES, $_SERVER, $_ENV.
Les autres opérateurs ($HTTP_SERVER_GET, ...) ayant été passés en deprecated au sein de PHP, ne doivent plus être utilisés. Ainsi le code doit fonctionner y compris quand l'option '''register_long_arrays''' est à off.
De plus, le code doit fonctionner quand l'option PHP '''register_globals''' est à off (recommandé par PHP) aussi bien que quand l'option '''register_globals''' à on (par défaut sur de nombreuses installations).

* Les smart tags PHP ne sont pas utilisés. Les sections de code doivent commencer par '''<?php'''

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

* Quand plusieurs variables doivent être initialisées avec la même valeur, il faut utiliser plusieurs lignes
<pre>
$var1=1;$var2=1;$var3=1;
</pre>
plutôt que
<pre>
$var1=$var2=$var3=1;
</pre>
qui est moins performant.

* Les chaines doivent être encadrés de simple quote et les variables sorties de la chaine.
<pre>
print 'Mon texte affiche ma '.$variable.' !';
</pre>

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

/* 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;
}

</pre>

* Les fichiers doivent etre 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 fonctions doivent retourner 0 en cas de succès, et un nombre <0 en cas d'erreur.
A ce jour, très peu de fonctions respectent ce standard mais c'est celui vers lequel il faut tendre.

== Normes SQL ==

* 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:
<pre>
SELECT field_a, field_b, field_c FROM table_1 WHERE field_d = '$id'
</pre>

* 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 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:
<pre>
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')
</pre>

Remarque, le pb 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', 'MT' ou 'MS' selon le besoin. (voir doc fonction)

* Dolibarr doit fonctionner même avec l'option '''strict''' de Mysql active.

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

== Normes HTML ==

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

* Les liens href doivent être absolus et se baser pour les pages sur la constante DOL_URL_ROOT qui pointe sur htdocs et pour les images se base sur l'appel de la fonction img_picto.
Par exemple:
<pre>
print '<a href="'.DOL_URL_ROOT.'/monrep/mapage.php">'.img_picto('Texte alt','nompictopng','').'</a>';
</pre>

* Le javascript 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"
<pre>
if ($conf->use_javascript)
{
... // Le code php qui génère du javascript est ici
}
</pre>

* Les popups windows ne doivent pas être utilisées, sauf pour des tooltips (et restent condtionné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. Le langage devra être maitrisé par au moins 2 développeurs pour en assurer la maintenance.

== Normes Dolibarr et squelettes de code ==

=== Squelettes de code ===
Afin d'uniformiser le code et d'accélérer le développement de nouveaux composants dans Dolibarr, se trouvent dans le répertoire '''dev/skeletons''', 4 squelettes de code tout préparés.

* 1 qui sert d'exemple de descripteur de module: '''myModule.class.php'''
* 1 qui sert d'exemple de code pour faire une nouvelle classe: '''skeleton_class.class.php'''
* 1 qui sert d'exemple de code pour faire une nouvelle page: '''skeleton_page.php'''
* 1 qui sert d'exemple de code pour faire un script à exécuter en ligne de commande: '''skeleton_script.php'''

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

=== Les dates et TimeZone ===
Dolibarr se veut une application mutli-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 GMT en rapport avec la date soumise dans la requête en heure locale du serveur PHP. Cela ne concerne pas les dates mises à jour automatiquement par la base (champ '''tms''' en base).
Ainsi le 1er janvier 1970, 2 heures à Paris (TZ=+1) sera stocké en mémoire sera soumis à la base de données avec la chaine '19700101020000' (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 ('19700101020000') 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 GMT au moment où la modification est faite. Les méthodes select récupèrent directement cette donnée en mémoire au format Timestamp GMT.

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

=== Les nombres réels, montants et calculs ===
En PHP comme dans d'autres langages (Java par exemple), les données non entières (float, real, double) ne sont pas fiables.
Essayer de faire par exemple
<pre>
print 239.2 - 229.3 - 9.9;
</pre>
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).
<pre>
print price2num(239.2 - 229.3 - 9.9, 'MT');
</pre>
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 Créer un module qui explique comment joindre des tables qui se créent à l'activation du module et non à son utilisation (voir plus haut).

=== Logs ===
Ajouter des traces dans votre code avec la fonction
dolibarr_syslog($yourmessage, LOG_INFO|LOG_DEBUG|LOG_WARNING|LOG_ERR);

=== 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:
<pre>
$mymoduledir=DOL_DATA_ROOT.'/monmodule';
if (! is_dir($mymoduledir)) create_exdir($mymoduledir);
</pre>

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

== Programmation Objet ==

=== Motifs d'organisation du code: ===

'''Martin Fowler''' a identifié 3 méthodes d'organisation du code appelées '''motifs''':
* Le '''Transaction Script''' (Le code est linéraire 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.
* 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 table par classe et chaque classe est un pont avec la table correspondante, voir une classe par ligne de table. 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.

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 propres à la table ou à l'enregistrement.

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 plus complexe sur le plan pratique.
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).

Langages et normes

2009-02-03T19:15:16Z

Mcg: /* Motifs d'organisation du code: */

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

== Normes PHP ==

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

* L'appel aux variables superglobales PHP doit passer par les opérateurs dédiés $_GET, $_POST, $_COOKIES, $_SERVER, $_ENV.
Les autres opérateurs ($HTTP_SERVER_GET, ...) ayant été passés en deprecated au sein de PHP, ne doivent plus être utilisés. Ainsi le code doit fonctionner y compris quand l'option '''register_long_arrays''' est à off.
De plus, le code doit fonctionner quand l'option PHP '''register_globals''' est à off (recommandé par PHP) aussi bien que quand l'option '''register_globals''' à on (par défaut sur de nombreuses installations).

* Les smart tags PHP ne sont pas utilisés. Les sections de code doivent commencer par '''<?php'''

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

* Quand plusieurs variables doivent être initialisées avec la même valeur, il faut utiliser plusieurs lignes
<pre>
$var1=1;$var2=1;$var3=1;
</pre>
plutôt que
<pre>
$var1=$var2=$var3=1;
</pre>
qui est moins performant.

* Les chaines doivent être encadrés de simple quote et les variables sorties de la chaine.
<pre>
print 'Mon texte affiche ma '.$variable.' !';
</pre>

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

/* 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;
}

</pre>

* Les fichiers doivent etre 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 fonctions doivent retourner 0 en cas de succès, et un nombre <0 en cas d'erreur.
A ce jour, très peu de fonctions respectent ce standard mais c'est celui vers lequel il faut tendre.

== Normes SQL ==

* 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:
<pre>
SELECT field_a, field_b, field_c FROM table_1 WHERE field_d = '$id'
</pre>

* 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 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:
<pre>
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')
</pre>

Remarque, le pb 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', 'MT' ou 'MS' selon le besoin. (voir doc fonction)

* Dolibarr doit fonctionner même avec l'option '''strict''' de Mysql active.

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

== Normes HTML ==

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

* Les liens href doivent être absolus et se baser pour les pages sur la constante DOL_URL_ROOT qui pointe sur htdocs et pour les images se base sur l'appel de la fonction img_picto.
Par exemple:
<pre>
print '<a href="'.DOL_URL_ROOT.'/monrep/mapage.php">'.img_picto('Texte alt','nompictopng','').'</a>';
</pre>

* Le javascript 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"
<pre>
if ($conf->use_javascript)
{
... // Le code php qui génère du javascript est ici
}
</pre>

* Les popups windows ne doivent pas être utilisées, sauf pour des tooltips (et restent condtionné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. Le langage devra être maitrisé par au moins 2 développeurs pour en assurer la maintenance.

== Normes Dolibarr et squelettes de code ==

=== Squelettes de code ===
Afin d'uniformiser le code et d'accélérer le développement de nouveaux composants dans Dolibarr, se trouvent dans le répertoire '''dev/skeletons''', 4 squelettes de code tout préparés.

* 1 qui sert d'exemple de descripteur de module: '''myModule.class.php'''
* 1 qui sert d'exemple de code pour faire une nouvelle classe: '''skeleton_class.class.php'''
* 1 qui sert d'exemple de code pour faire une nouvelle page: '''skeleton_page.php'''
* 1 qui sert d'exemple de code pour faire un script à exécuter en ligne de commande: '''skeleton_script.php'''

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

=== Les dates et TimeZone ===
Dolibarr se veut une application mutli-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 GMT en rapport avec la date soumise dans la requête en heure locale du serveur PHP. Cela ne concerne pas les dates mises à jour automatiquement par la base (champ '''tms''' en base).
Ainsi le 1er janvier 1970, 2 heures à Paris (TZ=+1) sera stocké en mémoire sera soumis à la base de données avec la chaine '19700101020000' (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 ('19700101020000') 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 GMT au moment où la modification est faite. Les méthodes select récupèrent directement cette donnée en mémoire au format Timestamp GMT.

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

=== Les nombres réels, montants et calculs ===
En PHP comme dans d'autres langages (Java par exemple), les données non entières (float, real, double) ne sont pas fiables.
Essayer de faire par exemple
<pre>
print 239.2 - 229.3 - 9.9;
</pre>
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).
<pre>
print price2num(239.2 - 229.3 - 9.9, 'MT');
</pre>
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 Créer un module qui explique comment joindre des tables qui se créent à l'activation du module et non à son utilisation (voir plus haut).

=== Logs ===
Ajouter des traces dans votre code avec la fonction
dolibarr_syslog($yourmessage, LOG_INFO|LOG_DEBUG|LOG_WARNING|LOG_ERR);

=== 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:
<pre>
$mymoduledir=DOL_DATA_ROOT.'/monmodule';
if (! is_dir($mymoduledir)) create_exdir($mymoduledir);
</pre>

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

== Programmation Objet ==

=== Motifs d'organisation du code: ===

'''Martin Fowler''' a identifié 3 méthodes d'organisation du code appelées '''motifs''':
* Le '''Transaction Script''' (Le code est linéraire 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.
* 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 table par classe et chaque classe est un pont avec la table correspondante, voir une classe par ligne de table. 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.

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 propres à la table ou à l'enregistrement.

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 plus complexe sur le plan pratique.
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 autre.

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

Langages et normes

2009-02-03T19:14:03Z

Mcg: /* Répertoires de travail */

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

== Normes PHP ==

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

* L'appel aux variables superglobales PHP doit passer par les opérateurs dédiés $_GET, $_POST, $_COOKIES, $_SERVER, $_ENV.
Les autres opérateurs ($HTTP_SERVER_GET, ...) ayant été passés en deprecated au sein de PHP, ne doivent plus être utilisés. Ainsi le code doit fonctionner y compris quand l'option '''register_long_arrays''' est à off.
De plus, le code doit fonctionner quand l'option PHP '''register_globals''' est à off (recommandé par PHP) aussi bien que quand l'option '''register_globals''' à on (par défaut sur de nombreuses installations).

* Les smart tags PHP ne sont pas utilisés. Les sections de code doivent commencer par '''<?php'''

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

* Quand plusieurs variables doivent être initialisées avec la même valeur, il faut utiliser plusieurs lignes
<pre>
$var1=1;$var2=1;$var3=1;
</pre>
plutôt que
<pre>
$var1=$var2=$var3=1;
</pre>
qui est moins performant.

* Les chaines doivent être encadrés de simple quote et les variables sorties de la chaine.
<pre>
print 'Mon texte affiche ma '.$variable.' !';
</pre>

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

/* 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;
}

</pre>

* Les fichiers doivent etre 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 fonctions doivent retourner 0 en cas de succès, et un nombre <0 en cas d'erreur.
A ce jour, très peu de fonctions respectent ce standard mais c'est celui vers lequel il faut tendre.

== Normes SQL ==

* 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:
<pre>
SELECT field_a, field_b, field_c FROM table_1 WHERE field_d = '$id'
</pre>

* 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 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:
<pre>
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')
</pre>

Remarque, le pb 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', 'MT' ou 'MS' selon le besoin. (voir doc fonction)

* Dolibarr doit fonctionner même avec l'option '''strict''' de Mysql active.

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

== Normes HTML ==

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

* Les liens href doivent être absolus et se baser pour les pages sur la constante DOL_URL_ROOT qui pointe sur htdocs et pour les images se base sur l'appel de la fonction img_picto.
Par exemple:
<pre>
print '<a href="'.DOL_URL_ROOT.'/monrep/mapage.php">'.img_picto('Texte alt','nompictopng','').'</a>';
</pre>

* Le javascript 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"
<pre>
if ($conf->use_javascript)
{
... // Le code php qui génère du javascript est ici
}
</pre>

* Les popups windows ne doivent pas être utilisées, sauf pour des tooltips (et restent condtionné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. Le langage devra être maitrisé par au moins 2 développeurs pour en assurer la maintenance.

== Normes Dolibarr et squelettes de code ==

=== Squelettes de code ===
Afin d'uniformiser le code et d'accélérer le développement de nouveaux composants dans Dolibarr, se trouvent dans le répertoire '''dev/skeletons''', 4 squelettes de code tout préparés.

* 1 qui sert d'exemple de descripteur de module: '''myModule.class.php'''
* 1 qui sert d'exemple de code pour faire une nouvelle classe: '''skeleton_class.class.php'''
* 1 qui sert d'exemple de code pour faire une nouvelle page: '''skeleton_page.php'''
* 1 qui sert d'exemple de code pour faire un script à exécuter en ligne de commande: '''skeleton_script.php'''

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

=== Les dates et TimeZone ===
Dolibarr se veut une application mutli-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 GMT en rapport avec la date soumise dans la requête en heure locale du serveur PHP. Cela ne concerne pas les dates mises à jour automatiquement par la base (champ '''tms''' en base).
Ainsi le 1er janvier 1970, 2 heures à Paris (TZ=+1) sera stocké en mémoire sera soumis à la base de données avec la chaine '19700101020000' (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 ('19700101020000') 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 GMT au moment où la modification est faite. Les méthodes select récupèrent directement cette donnée en mémoire au format Timestamp GMT.

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

=== Les nombres réels, montants et calculs ===
En PHP comme dans d'autres langages (Java par exemple), les données non entières (float, real, double) ne sont pas fiables.
Essayer de faire par exemple
<pre>
print 239.2 - 229.3 - 9.9;
</pre>
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).
<pre>
print price2num(239.2 - 229.3 - 9.9, 'MT');
</pre>
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 Créer un module qui explique comment joindre des tables qui se créent à l'activation du module et non à son utilisation (voir plus haut).

=== Logs ===
Ajouter des traces dans votre code avec la fonction
dolibarr_syslog($yourmessage, LOG_INFO|LOG_DEBUG|LOG_WARNING|LOG_ERR);

=== 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:
<pre>
$mymoduledir=DOL_DATA_ROOT.'/monmodule';
if (! is_dir($mymoduledir)) create_exdir($mymoduledir);
</pre>

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

== Programmation Objet ==

=== Motifs d'organisation du code: ===

'''Martin Fowler''' a identifié 3 méthodes d'organisation du code appelées '''motifs''':
* Le '''Transaction Script''' (Le code est linéraire 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.
* 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ée.

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 table par classe et chaque classe est un pont avec la table correspondante, voir une classe par ligne de table. 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.

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 propres à la table ou à l'enregistrement.

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 plus complexe sur le plan pratique.
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 autre.

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

Langages et normes

2009-02-03T19:13:19Z

Mcg: /* Création de tables */

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

== Normes PHP ==

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

* L'appel aux variables superglobales PHP doit passer par les opérateurs dédiés $_GET, $_POST, $_COOKIES, $_SERVER, $_ENV.
Les autres opérateurs ($HTTP_SERVER_GET, ...) ayant été passés en deprecated au sein de PHP, ne doivent plus être utilisés. Ainsi le code doit fonctionner y compris quand l'option '''register_long_arrays''' est à off.
De plus, le code doit fonctionner quand l'option PHP '''register_globals''' est à off (recommandé par PHP) aussi bien que quand l'option '''register_globals''' à on (par défaut sur de nombreuses installations).

* Les smart tags PHP ne sont pas utilisés. Les sections de code doivent commencer par '''<?php'''

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

* Quand plusieurs variables doivent être initialisées avec la même valeur, il faut utiliser plusieurs lignes
<pre>
$var1=1;$var2=1;$var3=1;
</pre>
plutôt que
<pre>
$var1=$var2=$var3=1;
</pre>
qui est moins performant.

* Les chaines doivent être encadrés de simple quote et les variables sorties de la chaine.
<pre>
print 'Mon texte affiche ma '.$variable.' !';
</pre>

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

/* 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;
}

</pre>

* Les fichiers doivent etre 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 fonctions doivent retourner 0 en cas de succès, et un nombre <0 en cas d'erreur.
A ce jour, très peu de fonctions respectent ce standard mais c'est celui vers lequel il faut tendre.

== Normes SQL ==

* 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:
<pre>
SELECT field_a, field_b, field_c FROM table_1 WHERE field_d = '$id'
</pre>

* 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 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:
<pre>
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')
</pre>

Remarque, le pb 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', 'MT' ou 'MS' selon le besoin. (voir doc fonction)

* Dolibarr doit fonctionner même avec l'option '''strict''' de Mysql active.

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

== Normes HTML ==

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

* Les liens href doivent être absolus et se baser pour les pages sur la constante DOL_URL_ROOT qui pointe sur htdocs et pour les images se base sur l'appel de la fonction img_picto.
Par exemple:
<pre>
print '<a href="'.DOL_URL_ROOT.'/monrep/mapage.php">'.img_picto('Texte alt','nompictopng','').'</a>';
</pre>

* Le javascript 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"
<pre>
if ($conf->use_javascript)
{
... // Le code php qui génère du javascript est ici
}
</pre>

* Les popups windows ne doivent pas être utilisées, sauf pour des tooltips (et restent condtionné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. Le langage devra être maitrisé par au moins 2 développeurs pour en assurer la maintenance.

== Normes Dolibarr et squelettes de code ==

=== Squelettes de code ===
Afin d'uniformiser le code et d'accélérer le développement de nouveaux composants dans Dolibarr, se trouvent dans le répertoire '''dev/skeletons''', 4 squelettes de code tout préparés.

* 1 qui sert d'exemple de descripteur de module: '''myModule.class.php'''
* 1 qui sert d'exemple de code pour faire une nouvelle classe: '''skeleton_class.class.php'''
* 1 qui sert d'exemple de code pour faire une nouvelle page: '''skeleton_page.php'''
* 1 qui sert d'exemple de code pour faire un script à exécuter en ligne de commande: '''skeleton_script.php'''

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

=== Les dates et TimeZone ===
Dolibarr se veut une application mutli-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 GMT en rapport avec la date soumise dans la requête en heure locale du serveur PHP. Cela ne concerne pas les dates mises à jour automatiquement par la base (champ '''tms''' en base).
Ainsi le 1er janvier 1970, 2 heures à Paris (TZ=+1) sera stocké en mémoire sera soumis à la base de données avec la chaine '19700101020000' (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 ('19700101020000') 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 GMT au moment où la modification est faite. Les méthodes select récupèrent directement cette donnée en mémoire au format Timestamp GMT.

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

=== Les nombres réels, montants et calculs ===
En PHP comme dans d'autres langages (Java par exemple), les données non entières (float, real, double) ne sont pas fiables.
Essayer de faire par exemple
<pre>
print 239.2 - 229.3 - 9.9;
</pre>
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).
<pre>
print price2num(239.2 - 229.3 - 9.9, 'MT');
</pre>
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 Créer un module qui explique comment joindre des tables qui se créent à l'activation du module et non à son utilisation (voir plus haut).

=== Logs ===
Ajouter des traces dans votre code avec la fonction
dolibarr_syslog($yourmessage, LOG_INFO|LOG_DEBUG|LOG_WARNING|LOG_ERR);

=== 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éer dans votre code à l'exécution par le code suivant:
<pre>
$mymoduledir=DOL_DATA_ROOT.'/monmodule';
if (! is_dir($mymoduledir)) create_exdir($mymoduledir);
</pre>

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

== Programmation Objet ==

=== Motifs d'organisation du code: ===

'''Martin Fowler''' a identifié 3 méthodes d'organisation du code appelées '''motifs''':
* Le '''Transaction Script''' (Le code est linéraire 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.
* 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ée.

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 table par classe et chaque classe est un pont avec la table correspondante, voir une classe par ligne de table. 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.

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 propres à la table ou à l'enregistrement.

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 plus complexe sur le plan pratique.
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 autre.

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

Langages et normes

2009-02-03T19:12:54Z

Mcg: /* Les nombres réels, montants et calculs */

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

== Normes PHP ==

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

* L'appel aux variables superglobales PHP doit passer par les opérateurs dédiés $_GET, $_POST, $_COOKIES, $_SERVER, $_ENV.
Les autres opérateurs ($HTTP_SERVER_GET, ...) ayant été passés en deprecated au sein de PHP, ne doivent plus être utilisés. Ainsi le code doit fonctionner y compris quand l'option '''register_long_arrays''' est à off.
De plus, le code doit fonctionner quand l'option PHP '''register_globals''' est à off (recommandé par PHP) aussi bien que quand l'option '''register_globals''' à on (par défaut sur de nombreuses installations).

* Les smart tags PHP ne sont pas utilisés. Les sections de code doivent commencer par '''<?php'''

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

* Quand plusieurs variables doivent être initialisées avec la même valeur, il faut utiliser plusieurs lignes
<pre>
$var1=1;$var2=1;$var3=1;
</pre>
plutôt que
<pre>
$var1=$var2=$var3=1;
</pre>
qui est moins performant.

* Les chaines doivent être encadrés de simple quote et les variables sorties de la chaine.
<pre>
print 'Mon texte affiche ma '.$variable.' !';
</pre>

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

/* 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;
}

</pre>

* Les fichiers doivent etre 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 fonctions doivent retourner 0 en cas de succès, et un nombre <0 en cas d'erreur.
A ce jour, très peu de fonctions respectent ce standard mais c'est celui vers lequel il faut tendre.

== Normes SQL ==

* 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:
<pre>
SELECT field_a, field_b, field_c FROM table_1 WHERE field_d = '$id'
</pre>

* 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 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:
<pre>
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')
</pre>

Remarque, le pb 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', 'MT' ou 'MS' selon le besoin. (voir doc fonction)

* Dolibarr doit fonctionner même avec l'option '''strict''' de Mysql active.

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

== Normes HTML ==

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

* Les liens href doivent être absolus et se baser pour les pages sur la constante DOL_URL_ROOT qui pointe sur htdocs et pour les images se base sur l'appel de la fonction img_picto.
Par exemple:
<pre>
print '<a href="'.DOL_URL_ROOT.'/monrep/mapage.php">'.img_picto('Texte alt','nompictopng','').'</a>';
</pre>

* Le javascript 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"
<pre>
if ($conf->use_javascript)
{
... // Le code php qui génère du javascript est ici
}
</pre>

* Les popups windows ne doivent pas être utilisées, sauf pour des tooltips (et restent condtionné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. Le langage devra être maitrisé par au moins 2 développeurs pour en assurer la maintenance.

== Normes Dolibarr et squelettes de code ==

=== Squelettes de code ===
Afin d'uniformiser le code et d'accélérer le développement de nouveaux composants dans Dolibarr, se trouvent dans le répertoire '''dev/skeletons''', 4 squelettes de code tout préparés.

* 1 qui sert d'exemple de descripteur de module: '''myModule.class.php'''
* 1 qui sert d'exemple de code pour faire une nouvelle classe: '''skeleton_class.class.php'''
* 1 qui sert d'exemple de code pour faire une nouvelle page: '''skeleton_page.php'''
* 1 qui sert d'exemple de code pour faire un script à exécuter en ligne de commande: '''skeleton_script.php'''

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

=== Les dates et TimeZone ===
Dolibarr se veut une application mutli-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 GMT en rapport avec la date soumise dans la requête en heure locale du serveur PHP. Cela ne concerne pas les dates mises à jour automatiquement par la base (champ '''tms''' en base).
Ainsi le 1er janvier 1970, 2 heures à Paris (TZ=+1) sera stocké en mémoire sera soumis à la base de données avec la chaine '19700101020000' (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 ('19700101020000') 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 GMT au moment où la modification est faite. Les méthodes select récupèrent directement cette donnée en mémoire au format Timestamp GMT.

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

=== Les nombres réels, montants et calculs ===
En PHP comme dans d'autres langages (Java par exemple), les données non entières (float, real, double) ne sont pas fiables.
Essayer de faire par exemple
<pre>
print 239.2 - 229.3 - 9.9;
</pre>
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).
<pre>
print price2num(239.2 - 229.3 - 9.9, 'MT');
</pre>
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 Créer un module qui explique comment joindre des tables qui se crée à l'activation du module et non à son utilisation (voir plus haut).

=== Logs ===
Ajouter des traces dans votre code avec la fonction
dolibarr_syslog($yourmessage, LOG_INFO|LOG_DEBUG|LOG_WARNING|LOG_ERR);

=== 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éer dans votre code à l'exécution par le code suivant:
<pre>
$mymoduledir=DOL_DATA_ROOT.'/monmodule';
if (! is_dir($mymoduledir)) create_exdir($mymoduledir);
</pre>

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

== Programmation Objet ==

=== Motifs d'organisation du code: ===

'''Martin Fowler''' a identifié 3 méthodes d'organisation du code appelées '''motifs''':
* Le '''Transaction Script''' (Le code est linéraire 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.
* 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ée.

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 table par classe et chaque classe est un pont avec la table correspondante, voir une classe par ligne de table. 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.

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 propres à la table ou à l'enregistrement.

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 plus complexe sur le plan pratique.
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 autre.

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

Langages et normes

2009-02-03T19:11:08Z

Mcg: /* Les dates et TimeZone */

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

== Normes PHP ==

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

* L'appel aux variables superglobales PHP doit passer par les opérateurs dédiés $_GET, $_POST, $_COOKIES, $_SERVER, $_ENV.
Les autres opérateurs ($HTTP_SERVER_GET, ...) ayant été passés en deprecated au sein de PHP, ne doivent plus être utilisés. Ainsi le code doit fonctionner y compris quand l'option '''register_long_arrays''' est à off.
De plus, le code doit fonctionner quand l'option PHP '''register_globals''' est à off (recommandé par PHP) aussi bien que quand l'option '''register_globals''' à on (par défaut sur de nombreuses installations).

* Les smart tags PHP ne sont pas utilisés. Les sections de code doivent commencer par '''<?php'''

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

* Quand plusieurs variables doivent être initialisées avec la même valeur, il faut utiliser plusieurs lignes
<pre>
$var1=1;$var2=1;$var3=1;
</pre>
plutôt que
<pre>
$var1=$var2=$var3=1;
</pre>
qui est moins performant.

* Les chaines doivent être encadrés de simple quote et les variables sorties de la chaine.
<pre>
print 'Mon texte affiche ma '.$variable.' !';
</pre>

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

/* 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;
}

</pre>

* Les fichiers doivent etre 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 fonctions doivent retourner 0 en cas de succès, et un nombre <0 en cas d'erreur.
A ce jour, très peu de fonctions respectent ce standard mais c'est celui vers lequel il faut tendre.

== Normes SQL ==

* 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:
<pre>
SELECT field_a, field_b, field_c FROM table_1 WHERE field_d = '$id'
</pre>

* 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 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:
<pre>
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')
</pre>

Remarque, le pb 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', 'MT' ou 'MS' selon le besoin. (voir doc fonction)

* Dolibarr doit fonctionner même avec l'option '''strict''' de Mysql active.

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

== Normes HTML ==

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

* Les liens href doivent être absolus et se baser pour les pages sur la constante DOL_URL_ROOT qui pointe sur htdocs et pour les images se base sur l'appel de la fonction img_picto.
Par exemple:
<pre>
print '<a href="'.DOL_URL_ROOT.'/monrep/mapage.php">'.img_picto('Texte alt','nompictopng','').'</a>';
</pre>

* Le javascript 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"
<pre>
if ($conf->use_javascript)
{
... // Le code php qui génère du javascript est ici
}
</pre>

* Les popups windows ne doivent pas être utilisées, sauf pour des tooltips (et restent condtionné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. Le langage devra être maitrisé par au moins 2 développeurs pour en assurer la maintenance.

== Normes Dolibarr et squelettes de code ==

=== Squelettes de code ===
Afin d'uniformiser le code et d'accélérer le développement de nouveaux composants dans Dolibarr, se trouvent dans le répertoire '''dev/skeletons''', 4 squelettes de code tout préparés.

* 1 qui sert d'exemple de descripteur de module: '''myModule.class.php'''
* 1 qui sert d'exemple de code pour faire une nouvelle classe: '''skeleton_class.class.php'''
* 1 qui sert d'exemple de code pour faire une nouvelle page: '''skeleton_page.php'''
* 1 qui sert d'exemple de code pour faire un script à exécuter en ligne de commande: '''skeleton_script.php'''

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

=== Les dates et TimeZone ===
Dolibarr se veut une application mutli-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 GMT en rapport avec la date soumise dans la requête en heure locale du serveur PHP. Cela ne concerne pas les dates mises à jour automatiquement par la base (champ '''tms''' en base).
Ainsi le 1er janvier 1970, 2 heures à Paris (TZ=+1) sera stocké en mémoire sera soumis à la base de données avec la chaine '19700101020000' (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 ('19700101020000') 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 GMT au moment où la modification est faite. Les méthodes select récupèrent directement cette donnée en mémoire au format Timestamp GMT.

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

=== Les nombres réels, montants et calculs ===
En PHP comme dans d'autres langages (Java par exemple), les données non entières (float, real, double) ne sont pas fiables.
Essayer de faire par exemple
<pre>
print 239.2 - 229.3 - 9.9;
</pre>
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 exemple 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és par la fonction price2num avec le 2eme paramètre renseigné à: 'MU', 'MT' ou 'MS' selon le besoin (voir doc fonction).
<pre>
print price2num(239.2 - 229.3 - 9.9, 'MT');
</pre>
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 Créer un module qui explique comment joindre des tables qui se crée à l'activation du module et non à son utilisation (voir plus haut).

=== Logs ===
Ajouter des traces dans votre code avec la fonction
dolibarr_syslog($yourmessage, LOG_INFO|LOG_DEBUG|LOG_WARNING|LOG_ERR);

=== 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éer dans votre code à l'exécution par le code suivant:
<pre>
$mymoduledir=DOL_DATA_ROOT.'/monmodule';
if (! is_dir($mymoduledir)) create_exdir($mymoduledir);
</pre>

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

== Programmation Objet ==

=== Motifs d'organisation du code: ===

'''Martin Fowler''' a identifié 3 méthodes d'organisation du code appelées '''motifs''':
* Le '''Transaction Script''' (Le code est linéraire 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.
* 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ée.

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 table par classe et chaque classe est un pont avec la table correspondante, voir une classe par ligne de table. 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.

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 propres à la table ou à l'enregistrement.

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 plus complexe sur le plan pratique.
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 autre.

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

Langages et normes

2009-02-03T19:08:58Z

Mcg: /* Normes HTML */

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

== Normes PHP ==

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

* L'appel aux variables superglobales PHP doit passer par les opérateurs dédiés $_GET, $_POST, $_COOKIES, $_SERVER, $_ENV.
Les autres opérateurs ($HTTP_SERVER_GET, ...) ayant été passés en deprecated au sein de PHP, ne doivent plus être utilisés. Ainsi le code doit fonctionner y compris quand l'option '''register_long_arrays''' est à off.
De plus, le code doit fonctionner quand l'option PHP '''register_globals''' est à off (recommandé par PHP) aussi bien que quand l'option '''register_globals''' à on (par défaut sur de nombreuses installations).

* Les smart tags PHP ne sont pas utilisés. Les sections de code doivent commencer par '''<?php'''

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

* Quand plusieurs variables doivent être initialisées avec la même valeur, il faut utiliser plusieurs lignes
<pre>
$var1=1;$var2=1;$var3=1;
</pre>
plutôt que
<pre>
$var1=$var2=$var3=1;
</pre>
qui est moins performant.

* Les chaines doivent être encadrés de simple quote et les variables sorties de la chaine.
<pre>
print 'Mon texte affiche ma '.$variable.' !';
</pre>

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

/* 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;
}

</pre>

* Les fichiers doivent etre 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 fonctions doivent retourner 0 en cas de succès, et un nombre <0 en cas d'erreur.
A ce jour, très peu de fonctions respectent ce standard mais c'est celui vers lequel il faut tendre.

== Normes SQL ==

* 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:
<pre>
SELECT field_a, field_b, field_c FROM table_1 WHERE field_d = '$id'
</pre>

* 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 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:
<pre>
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')
</pre>

Remarque, le pb 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', 'MT' ou 'MS' selon le besoin. (voir doc fonction)

* Dolibarr doit fonctionner même avec l'option '''strict''' de Mysql active.

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

== Normes HTML ==

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

* Les liens href doivent être absolus et se baser pour les pages sur la constante DOL_URL_ROOT qui pointe sur htdocs et pour les images se base sur l'appel de la fonction img_picto.
Par exemple:
<pre>
print '<a href="'.DOL_URL_ROOT.'/monrep/mapage.php">'.img_picto('Texte alt','nompictopng','').'</a>';
</pre>

* Le javascript 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"
<pre>
if ($conf->use_javascript)
{
... // Le code php qui génère du javascript est ici
}
</pre>

* Les popups windows ne doivent pas être utilisées, sauf pour des tooltips (et restent condtionné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. Le langage devra être maitrisé par au moins 2 développeurs pour en assurer la maintenance.

== Normes Dolibarr et squelettes de code ==

=== Squelettes de code ===
Afin d'uniformiser le code et d'accélérer le développement de nouveaux composants dans Dolibarr, se trouvent dans le répertoire '''dev/skeletons''', 4 squelettes de code tout préparés.

* 1 qui sert d'exemple de descripteur de module: '''myModule.class.php'''
* 1 qui sert d'exemple de code pour faire une nouvelle classe: '''skeleton_class.class.php'''
* 1 qui sert d'exemple de code pour faire une nouvelle page: '''skeleton_page.php'''
* 1 qui sert d'exemple de code pour faire un script à exécuter en ligne de commande: '''skeleton_script.php'''

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

=== Les dates et TimeZone ===
Dolibarr se veut une application mutli-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ée contient le Timestamp GMT en rapport avec la date soumise dans la requête en heure locale du serveur PHP. Cela ne concerne pas les dates mises à jour automatiquement par la base (champ '''tms''' en base).
Ainsi le 1er janvier 1970, 2 heures à Paris (TZ=+1) sera stocké en mémoire sera soumis à la base de données avec la chaine '19700101020000' (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 ('19700101020000') 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éthode 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 GMT au moment ou la modification est faite. Les méthodes select récupèrent directement cette donnée en mémoire au format Timestamp GMT.

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

=== Les nombres réels, montants et calculs ===
En PHP comme dans d'autres langages (Java par exemple), les données non entières (float, real, double) ne sont pas fiables.
Essayer de faire par exemple
<pre>
print 239.2 - 229.3 - 9.9;
</pre>
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 exemple 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és par la fonction price2num avec le 2eme paramètre renseigné à: 'MU', 'MT' ou 'MS' selon le besoin (voir doc fonction).
<pre>
print price2num(239.2 - 229.3 - 9.9, 'MT');
</pre>
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 Créer un module qui explique comment joindre des tables qui se crée à l'activation du module et non à son utilisation (voir plus haut).

=== Logs ===
Ajouter des traces dans votre code avec la fonction
dolibarr_syslog($yourmessage, LOG_INFO|LOG_DEBUG|LOG_WARNING|LOG_ERR);

=== 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éer dans votre code à l'exécution par le code suivant:
<pre>
$mymoduledir=DOL_DATA_ROOT.'/monmodule';
if (! is_dir($mymoduledir)) create_exdir($mymoduledir);
</pre>

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

== Programmation Objet ==

=== Motifs d'organisation du code: ===

'''Martin Fowler''' a identifié 3 méthodes d'organisation du code appelées '''motifs''':
* Le '''Transaction Script''' (Le code est linéraire 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.
* 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ée.

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 table par classe et chaque classe est un pont avec la table correspondante, voir une classe par ligne de table. 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.

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 propres à la table ou à l'enregistrement.

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 plus complexe sur le plan pratique.
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 autre.

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

Langages et normes

2009-02-03T19:07:06Z

Mcg: /* Normes SQL */

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

== Normes PHP ==

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

* L'appel aux variables superglobales PHP doit passer par les opérateurs dédiés $_GET, $_POST, $_COOKIES, $_SERVER, $_ENV.
Les autres opérateurs ($HTTP_SERVER_GET, ...) ayant été passés en deprecated au sein de PHP, ne doivent plus être utilisés. Ainsi le code doit fonctionner y compris quand l'option '''register_long_arrays''' est à off.
De plus, le code doit fonctionner quand l'option PHP '''register_globals''' est à off (recommandé par PHP) aussi bien que quand l'option '''register_globals''' à on (par défaut sur de nombreuses installations).

* Les smart tags PHP ne sont pas utilisés. Les sections de code doivent commencer par '''<?php'''

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

* Quand plusieurs variables doivent être initialisées avec la même valeur, il faut utiliser plusieurs lignes
<pre>
$var1=1;$var2=1;$var3=1;
</pre>
plutôt que
<pre>
$var1=$var2=$var3=1;
</pre>
qui est moins performant.

* Les chaines doivent être encadrés de simple quote et les variables sorties de la chaine.
<pre>
print 'Mon texte affiche ma '.$variable.' !';
</pre>

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

/* 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;
}

</pre>

* Les fichiers doivent etre 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 fonctions doivent retourner 0 en cas de succès, et un nombre <0 en cas d'erreur.
A ce jour, très peu de fonctions respectent ce standard mais c'est celui vers lequel il faut tendre.

== Normes SQL ==

* 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:
<pre>
SELECT field_a, field_b, field_c FROM table_1 WHERE field_d = '$id'
</pre>

* 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 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:
<pre>
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')
</pre>

Remarque, le pb 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', 'MT' ou 'MS' selon le besoin. (voir doc fonction)

* Dolibarr doit fonctionner même avec l'option '''strict''' de Mysql active.

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

== Normes HTML ==

* Tous les attributs dans les balises HTML doivent être *en minuscule* et quottés avec des *doubles quote* (Norme xhtml)

* Les liens href doivent etre absolu et se baser pour les pages sur la constante DOL_URL_ROOT qui pointe sur htdocs et pour les images se base sur l'appel de la fonction img_picto.
Par exemple:
<pre>
print '<a href="'.DOL_URL_ROOT.'/monrep/mapage.php">'.img_picto('Texte alt','nompictopng','').'</a>';
</pre>

* Le javascript 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"
<pre>
if ($conf->use_javascript)
{
... // Le code php qui génère du javascript est ici
}
</pre>

* Les popups windows ne doivent pas être utilisées, sauf pour des tooltips (et restent condtionner 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. Le langage devra être maitrisé par au moins 2 développeurs pour en assurer la maintenance.

== Normes Dolibarr et squelettes de code ==

=== Squelettes de code ===
Afin d'uniformiser le code et d'accélérer le développement de nouveaux composants dans Dolibarr, se trouvent dans le répertoire '''dev/skeletons''', 4 squelettes de code tout préparés.

* 1 qui sert d'exemple de descripteur de module: '''myModule.class.php'''
* 1 qui sert d'exemple de code pour faire une nouvelle classe: '''skeleton_class.class.php'''
* 1 qui sert d'exemple de code pour faire une nouvelle page: '''skeleton_page.php'''
* 1 qui sert d'exemple de code pour faire un script à exécuter en ligne de commande: '''skeleton_script.php'''

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

=== Les dates et TimeZone ===
Dolibarr se veut une application mutli-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ée contient le Timestamp GMT en rapport avec la date soumise dans la requête en heure locale du serveur PHP. Cela ne concerne pas les dates mises à jour automatiquement par la base (champ '''tms''' en base).
Ainsi le 1er janvier 1970, 2 heures à Paris (TZ=+1) sera stocké en mémoire sera soumis à la base de données avec la chaine '19700101020000' (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 ('19700101020000') 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éthode 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 GMT au moment ou la modification est faite. Les méthodes select récupèrent directement cette donnée en mémoire au format Timestamp GMT.

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

=== Les nombres réels, montants et calculs ===
En PHP comme dans d'autres langages (Java par exemple), les données non entières (float, real, double) ne sont pas fiables.
Essayer de faire par exemple
<pre>
print 239.2 - 229.3 - 9.9;
</pre>
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 exemple 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és par la fonction price2num avec le 2eme paramètre renseigné à: 'MU', 'MT' ou 'MS' selon le besoin (voir doc fonction).
<pre>
print price2num(239.2 - 229.3 - 9.9, 'MT');
</pre>
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 Créer un module qui explique comment joindre des tables qui se crée à l'activation du module et non à son utilisation (voir plus haut).

=== Logs ===
Ajouter des traces dans votre code avec la fonction
dolibarr_syslog($yourmessage, LOG_INFO|LOG_DEBUG|LOG_WARNING|LOG_ERR);

=== 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éer dans votre code à l'exécution par le code suivant:
<pre>
$mymoduledir=DOL_DATA_ROOT.'/monmodule';
if (! is_dir($mymoduledir)) create_exdir($mymoduledir);
</pre>

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

== Programmation Objet ==

=== Motifs d'organisation du code: ===

'''Martin Fowler''' a identifié 3 méthodes d'organisation du code appelées '''motifs''':
* Le '''Transaction Script''' (Le code est linéraire 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.
* 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ée.

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 table par classe et chaque classe est un pont avec la table correspondante, voir une classe par ligne de table. 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.

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 propres à la table ou à l'enregistrement.

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 plus complexe sur le plan pratique.
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 autre.

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

Langages et normes

2009-02-03T19:03:57Z

Mcg: /* Normes PHP */

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

== Normes PHP ==

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

* L'appel aux variables superglobales PHP doit passer par les opérateurs dédiés $_GET, $_POST, $_COOKIES, $_SERVER, $_ENV.
Les autres opérateurs ($HTTP_SERVER_GET, ...) ayant été passés en deprecated au sein de PHP, ne doivent plus être utilisés. Ainsi le code doit fonctionner y compris quand l'option '''register_long_arrays''' est à off.
De plus, le code doit fonctionner quand l'option PHP '''register_globals''' est à off (recommandé par PHP) aussi bien que quand l'option '''register_globals''' à on (par défaut sur de nombreuses installations).

* Les smart tags PHP ne sont pas utilisés. Les sections de code doivent commencer par '''<?php'''

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

* Quand plusieurs variables doivent être initialisées avec la même valeur, il faut utiliser plusieurs lignes
<pre>
$var1=1;$var2=1;$var3=1;
</pre>
plutôt que
<pre>
$var1=$var2=$var3=1;
</pre>
qui est moins performant.

* Les chaines doivent être encadrés de simple quote et les variables sorties de la chaine.
<pre>
print 'Mon texte affiche ma '.$variable.' !';
</pre>

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

/* 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;
}

</pre>

* Les fichiers doivent etre 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 fonctions doivent retourner 0 en cas de succès, et un nombre <0 en cas d'erreur.
A ce jour, très peu de fonctions respectent ce standard mais c'est celui vers lequel il faut tendre.

== Normes SQL ==

* 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:
<pre>
SELECT field_a, field_b, field_c FROM table_1 WHERE field_d = '$id'
</pre>

* Dans les requètes SQL, on quote les champs mais pas les numériques qui contiennent des montantsdestinés a etre stoké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 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 probleme. 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:
<pre>
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')
</pre>

Remarque, le pb des float est general et pas seulement sur les acces 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', 'MT' ou 'MS' selon le besoin. (voir doc fonction)

* Dolibarr doit fonctionner même avec l'option '''strict''' de Mysql active.

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

== Normes HTML ==

* Tous les attributs dans les balises HTML doivent être *en minuscule* et quottés avec des *doubles quote* (Norme xhtml)

* Les liens href doivent etre absolu et se baser pour les pages sur la constante DOL_URL_ROOT qui pointe sur htdocs et pour les images se base sur l'appel de la fonction img_picto.
Par exemple:
<pre>
print '<a href="'.DOL_URL_ROOT.'/monrep/mapage.php">'.img_picto('Texte alt','nompictopng','').'</a>';
</pre>

* Le javascript 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"
<pre>
if ($conf->use_javascript)
{
... // Le code php qui génère du javascript est ici
}
</pre>

* Les popups windows ne doivent pas être utilisées, sauf pour des tooltips (et restent condtionner 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. Le langage devra être maitrisé par au moins 2 développeurs pour en assurer la maintenance.

== Normes Dolibarr et squelettes de code ==

=== Squelettes de code ===
Afin d'uniformiser le code et d'accélérer le développement de nouveaux composants dans Dolibarr, se trouvent dans le répertoire '''dev/skeletons''', 4 squelettes de code tout préparés.

* 1 qui sert d'exemple de descripteur de module: '''myModule.class.php'''
* 1 qui sert d'exemple de code pour faire une nouvelle classe: '''skeleton_class.class.php'''
* 1 qui sert d'exemple de code pour faire une nouvelle page: '''skeleton_page.php'''
* 1 qui sert d'exemple de code pour faire un script à exécuter en ligne de commande: '''skeleton_script.php'''

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

=== Les dates et TimeZone ===
Dolibarr se veut une application mutli-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ée contient le Timestamp GMT en rapport avec la date soumise dans la requête en heure locale du serveur PHP. Cela ne concerne pas les dates mises à jour automatiquement par la base (champ '''tms''' en base).
Ainsi le 1er janvier 1970, 2 heures à Paris (TZ=+1) sera stocké en mémoire sera soumis à la base de données avec la chaine '19700101020000' (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 ('19700101020000') 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éthode 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 GMT au moment ou la modification est faite. Les méthodes select récupèrent directement cette donnée en mémoire au format Timestamp GMT.

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

=== Les nombres réels, montants et calculs ===
En PHP comme dans d'autres langages (Java par exemple), les données non entières (float, real, double) ne sont pas fiables.
Essayer de faire par exemple
<pre>
print 239.2 - 229.3 - 9.9;
</pre>
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 exemple 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és par la fonction price2num avec le 2eme paramètre renseigné à: 'MU', 'MT' ou 'MS' selon le besoin (voir doc fonction).
<pre>
print price2num(239.2 - 229.3 - 9.9, 'MT');
</pre>
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 Créer un module qui explique comment joindre des tables qui se crée à l'activation du module et non à son utilisation (voir plus haut).

=== Logs ===
Ajouter des traces dans votre code avec la fonction
dolibarr_syslog($yourmessage, LOG_INFO|LOG_DEBUG|LOG_WARNING|LOG_ERR);

=== 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éer dans votre code à l'exécution par le code suivant:
<pre>
$mymoduledir=DOL_DATA_ROOT.'/monmodule';
if (! is_dir($mymoduledir)) create_exdir($mymoduledir);
</pre>

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

== Programmation Objet ==

=== Motifs d'organisation du code: ===

'''Martin Fowler''' a identifié 3 méthodes d'organisation du code appelées '''motifs''':
* Le '''Transaction Script''' (Le code est linéraire 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.
* 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ée.

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 table par classe et chaque classe est un pont avec la table correspondante, voir une classe par ligne de table. 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.

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 propres à la table ou à l'enregistrement.

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 plus complexe sur le plan pratique.
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 autre.

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

Librairies externes et dépendances

2009-02-03T19:00:57Z

Mcg: /* Librairies PHP */

{{TemplateDocDev}}

== Librairies embarquées dans le code source (valable pour la version 2.4) ==

Toutes les librairies embarqués Dolibarr sont situées, soit dans le répertoire '''htdocs/includes''':
* Librairies AdoDb-Date
* Librairies PHP-barcode
* Librairies Fckeditor (http://www.fckeditor.net)
* Librairies de génération de pdf FPDF (http://www.fpdf.org)
* Librairies de génération de pdf FPDI
* Librairies chargement RSS Magpierss
* Librairies Nusoap modifié pour ne pas avoir de conflit avec PHP5
* Librairies PHP_WriteExcel
* Librairies Prototype
* Librairies PWC
* Librairies Scriptaculous
* Librairies Treemenu
* Librairies VCard

Soit dans le répertoire '''external-libs''':
* Librairies Artichow pour les graphismes
* Librairies Smarty (non utilisé)

Toutes ces librairies embarquées doivent respecter les règles suivantes:
* Elles doivent être compatibles avec la licence de Dolibarr. Le fichier '''COPYRIGHT''' dans la racine de Dolibarr liste toutes les librairies embarquée avec leur licence en vigueur.
* Si une modification est faite sur le livrable d'une librairie externe, la modification doit être notifiée dans le fichier '''htdocs/includes/dolibarr_changes.txt'''. Normalement, on ne devrait jamais toucher aux librairies externes et les utiliser tel que disponibles. Ceci afin de permettre une mise à jour sans avoir à gérer des reports de modifications.

== Librairies Apache ==
Aucune librairie particulière requise.

== Librairies PHP ==
'''Librairie''': php4-imagick (package dev-php/PECL-imagick sou Gentoo)

'''Statut''': Optionnel

'''Rôle''': Les onglets "Aperçu" ne sont pas opérationnels si ce module n'est pas présent. Dans ce cas, il est possible de les désactiver depuis le menu Configuration - Affichage.

Outils de développement

2009-02-03T18:59:20Z

Mcg: /* Optionnel */

{{TemplateDocDev}}

Tout environnement de développement peut être utilisé.
Toutefois voici une liste d'outils fortement recommandés pour leur complétude, leur qualité et la productivité du développement qu'ils apportent. Ils sont utilisés par la plupart des développeurs principaux de Dolibarr. Notons que toutes ces solutions sont gratuites et OpenSource.

== Pour tous ==

Voici le socle de travail recommandé, toutefois tout outil respectant les standards Web, PHP, Mysql peuvent faire l'affaire.

* Firefox 3.0 avec les plugins: Tamper Data, HTMLValidator, Phplangeditor, Firebug + Firecookie.
A télécharger depuis le site http://www.firefox.com

* SquirrelSql pour l'administration de base
A télécharger depuis le site http://squirrelsql.sf.net

* Installation d'Eclipse 3.2 ou 3.3
A télécharger depuis le site http://www.eclipse.org

* Installation du plugin Eclipse pour PHP: PDT.
Pour cela, utiliser la procédure Find And Install et ajouter l'URL de mise à jour: http://download.eclipse.org/tools/pdt/updates/

== Optionnel ==

=== Si vous gérez d'autres projets sous SVN ===
* Installation du plugin pour Eclipse pour SVN: SubClipse.
Pour cela, utiliser la procédure Find And Install et ajouter l'URL de mise à jour: http://subclipse.tigris.org/install.html

=== 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.sf.net/updates

=== Si vous désirez développer des modules avec le générateur UML2Dolibarr ===

* Vérifier dans Eclipse - Help - Software update - Manage Configuration que votre Eclipse contient les composants
- Si Eclipse 3.2:
# EMF 2.2.2
# UML2 2.0.3
- Si Eclipse 3.3:
# EMF 2.3.0
# UML2 2.1.1

Si non, les installer via la procédure '''Find And Install''' et choisir EMF et UML2 End-User.

* Installation de TopCased 1.4
Pour cela, utiliser la procédure '''Find And Install''' et ajouter l'URL de mise à jour:
http://topcased-mm.gforge.enseeiht.fr/release/update-site3.3/

* Installation d'acceleo 2.2.1
Pour cela, utiliser la procédure '''Find And Install''' et ajouter l'URL de mise à jour:
http://www.acceleo.org/update/

* Installation d'UML2Dolibarr
Pour cela, récupérer les projets par la commande:
<pre>
svn checkout svn://svn.forge.objectweb.org/svnroot/acceleo/trunk/modules/community/uml21/dolibarr/trunk/
</pre>
et les importer dans Eclipse.

=== Si vous désirez faire du debuggage avec XDebug ===

* Installer xdebug (package php-xdebug sous Ubuntu)

* Modifier le fichier php.ini (ou xdebug.ini) pour ajouter les paramètres
- xdebug.remote_enable=1

- xdebug.profiler_enable=1

- xdebug.show_local_vars=1

=== Et si vous êtes sous Windows ===

* WampServer 2 (pour le base Mysql, Apache et PHP tout clé en main). Ce serveur WAMP offre le trio MySql+Apache+PHP installé en clé en main, avec possibilité de basculer de version pour n'importe lequel des ces composants d'un simple clic). Un must !

* 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 et la commande en ligne cvs si vous préferez les lignes de commandes)

== Configuration ==
Si vous êtes un développeur officiel avec accès CVS en écriture, ajouter dans la configuration CVS de votre Eclipse, une entrée CVS.

''':ext:yourlogin@cvs.savannah.nongnu.org:/cvsroot/dolibarr'''

Sinon il vous faut récupérer les sources depuis le tarball disponible sur le site web Dolibarr ( http://www.dolibarr.fr ) dans l'espace téléchargement

Outils de développement

2009-02-03T18:57:55Z

Mcg: /* Pour tous */

{{TemplateDocDev}}

Tout environnement de développement peut être utilisé.
Toutefois voici une liste d'outils fortement recommandés pour leur complétude, leur qualité et la productivité du développement qu'ils apportent. Ils sont utilisés par la plupart des développeurs principaux de Dolibarr. Notons que toutes ces solutions sont gratuites et OpenSource.

== Pour tous ==

Voici le socle de travail recommandé, toutefois tout outil respectant les standards Web, PHP, Mysql peuvent faire l'affaire.

* Firefox 3.0 avec les plugins: Tamper Data, HTMLValidator, Phplangeditor, Firebug + Firecookie.
A télécharger depuis le site http://www.firefox.com

* SquirrelSql pour l'administration de base
A télécharger depuis le site http://squirrelsql.sf.net

* Installation d'Eclipse 3.2 ou 3.3
A télécharger depuis le site http://www.eclipse.org

* Installation du plugin Eclipse pour PHP: PDT.
Pour cela, utiliser la procédure Find And Install et ajouter l'URL de mise à jour: http://download.eclipse.org/tools/pdt/updates/

== Optionnel ==

=== Si vous gérez d'autres projets sous SVN ===
* Installation du plugin pour Eclipse pour SVN: SubClipse.
Pour cela, utiliser la procédure Find And Install et ajouter l'URL de mise a jour: http://subclipse.tigris.org/install.html

=== 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 a jour: http://e-p-i-c.sf.net/updates

=== Si vous désirez développer des modules avec le générateur UML2Dolibarr ===

* Vérifier dans Eclipse - Help - Software update - Manage Configuration que votre Eclipse contient les composants
- Si Eclipse 3.2:
# EMF 2.2.2
# UML2 2.0.3
- Si Eclipse 3.3:
# EMF 2.3.0
# UML2 2.1.1

Si non, les installer via la procédure '''Find And Install''' et choisir EMF et UML2 End-User.

* Installation de TopCased 1.4
Pour cela, utiliser la procédure '''Find And Install''' et ajouter l'URL de mise a jour:
http://topcased-mm.gforge.enseeiht.fr/release/update-site3.3/

* Installation d'acceleo 2.2.1
Pour cela, utiliser la procédure '''Find And Install''' et ajouter l'URL de mise a jour:
http://www.acceleo.org/update/

* Installation d'UML2Dolibarr
Pour cela, récupérer les projets par la commande:
<pre>
svn checkout svn://svn.forge.objectweb.org/svnroot/acceleo/trunk/modules/community/uml21/dolibarr/trunk/
</pre>
et les importer dans Eclipse.

=== Si vous désirez faire du debuggage avec XDebug ===

* Installer xdebug (package php-xdebug sous Ubuntu)

* Modifier le fichier php.ini (ou xdebug.ini) pour ajouter les paramètres
- xdebug.remote_enable=1

- xdebug.profiler_enable=1

- xdebug.show_local_vars=1

=== Et si vous êtes sous Windows ===

* WampServer 2 (pour le base Mysql, Apache et PHP tout clé en main). Ce serveur WAMP offre le trio MySql+Apache+PHP installé en clé en main, avec possibilité de basculer de version pour n'importe lequel des ces composants d'un simple clic). Un must !

* 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 et la commande en ligne cvs si vous préferez les lignes de commandes)

== Configuration ==
Si vous êtes un développeur officiel avec accès CVS en écriture, ajouter dans la configuration CVS de votre Eclipse, une entrée CVS.

''':ext:yourlogin@cvs.savannah.nongnu.org:/cvsroot/dolibarr'''

Sinon il vous faut récupérer les sources depuis le tarball disponible sur le site web Dolibarr ( http://www.dolibarr.fr ) dans l'espace téléchargement

A savoir avant de commencer

2009-02-03T18:56:55Z

Mcg:

{{TemplateDocDev}}

Si vous souhaitez devenir développeur de Dolibarr vous devez :

# Lire ce wiki et plus particulièrement la [[Documentation Développeur]] dans son intégralité (dont est issue cette page).
# Créer un compte sur [http://savannah.nongnu.org Savannah] et s'inscrire à la mailing-list ML développeur ([http://savannah.nongnu.org/mail/?group=dolibarr Voir ici]). Inutile de demander à faire partie du groupe "Dolibarr" savannah, ceci donnant accès au CVS, cela n'est validé que lorsque votre grade passe au rang de Amiral, Jedi ou Yoda (Voir [[FAQ_D%C3%A9veloppeur#Comment_devenir_d.C3.A9veloppeur_officiel]] pour plus d'informations).
# Poster sur cette ML, une courte présentation de vos cursus, attentes ou intentions.
# Vous pouvez commencer par réaliser des évolutions chez vous et les tester sans géner l'organisation de Dolibarr.
# Pour soumettre vos premiers travaux ou encore devenir développeur officiel, il est important de savoir que ceci passe par un circuit qui peut être long mais qui est nécessaire pour garantir la qualité de Dolibarr. Plus d'info sur ces liens:
* [[FAQ_D%C3%A9veloppeur#Soumettre_un_patch.2C_amelioration_ou_participer_au_d.C3.A9veloppement|FAQ Développeur (soumettre un patch)]]
* [[FAQ_D%C3%A9veloppeur#Comment_devenir_d.C3.A9veloppeur_officiel|FAQ Développeur (devenir développeur officiel)]]

Ces quelques obligations n'ont pour seul but que le développement se fasse dans les meilleures conditions possibles.

Documentation Développeur

2009-02-03T18:55:06Z

Mcg: /* Les modules de numérotation */

== Informations générales ==
Ce chapitre regroupe des informations générales qu'il est nécessaire de lire avant de commencer toute action de développement sur Dolibarr.
# [[Outils et principe|A savoir avant de commencer]]
# [[Outils de développement|Environnement et Outils de développement]]
# [[Librairies externes et dépendances]]
# [[Langages|Langage et normes de développement]]
# [[FAQ_D%C3%A9veloppeur#R.C3.A9cup.C3.A9rer.2Fmettre_.C3.A0_jour_la_version_CVS_d.C3.A9veloppeur|Récupérer une version depuis le CVS]]

== La configuration technique de Dolibarr ==
La configuration technique de Dolibarr (mode authentification à l'application, identifiant de la base de données et location de l'espace de stockage des fichiers) est définie dans le seul fichier de configuration conf/conf.php.
Voir [[Fichier de configuration]] pour plus d'informations.

== La Base de données ==
# [[Charte de nommage]]
# [[Liste des tables]]
# [[Mise à jour du format de la base]]

== Comprendre un module existant ==
La documentation, pour les développeurs, spécifique à un module fonctionnel standard de Dolibarr, est définie sur la page [[Modules]].

La liste des modules complémentaires est définie sur la page des Modules complémentaires [http://wiki.dolibarr.org/index.php?title=Category:Modules_compl%C3%A9mentaires&]

== Développer un nouveau module/extension pour les IHM (nouveaux écrans) ==
Cette section décrit comment développer un nouveau module sur l'interface utilisateur de Dolibarr (IHM).
Un module pour l'IHM contient aussi bien des écrans que des données propres, voir une feuille de style.
Le développement de script ne rentre pas dans ce périmètre et est décrit au chapitre suivant.
Le développement de modules de numérotations, de documents, de thèmes ou de triggers est décrit dans des chapitres suivants également.

Pour développer votre propre module d'extension des IHM, aller sur le didacticiel: [[Developpement module]]

== Développer un script ligne de commande ou batch ==
Cette section décrit la procédure pour développer son propre script batch afin de réaliser des traitements dans Dolibarr (lecture, écriture, etc...).
La réalisation de modification sur l'interface utilisateur (IHM) ne rentre pas dans ce périmètre. Voir le chapitre précédent pour cela.

Pour développer un script quel qu'il soit, comme un script de traitement cron ou encore un script d'import de données issues d'un autre système, se référer à la page: [[Developpement script]]

== Le Système de paramétrage ==
Il existe 2 niveaux de paramétrage dans Dolibarr.
* Le global est stocké dans la [[Table llx_const]].
* Le paramétrage propre à un utilisateur est stocké dans la [[Table llx_user_param]]

Voir la page [[Constantes]]

== Le Système de menus ==
Voir la page [[Système de menus]]

== Le Système des thèmes ==
Voir la page [[Themes]]

== Le Système des boites ==
Voir la page [[Système des boites]]

== Le Système d'authentification ==
Voir la page [[Authentification]]

== Le Système des permissions ==
Voir la page [[Permissions]]

== Le Système de traduction ==
Voir la page [[Système de traduction]]

== La Gestion d'erreur ==

Voir la page [[Gestion d'erreur]]

== Les modules de numérotation ==
Pour chaque entité créée dans l'application, Dolibarr attribue une référence. Afin de pouvoir adapter cette référence à toute utilisation, Dolibarr utilise des modules pour définir la règle de génération de cette référence. Des modules sont fournis en standard donc certains sont génériques et permettent de définir le masque de numérotation (nombre sur x caractère, avec ou sans prefix, incluant la date ou pas, etc), ce qui permet de répondre à la plupart des besoins. Toutefois, il existe toujours des cas où le module fourni en standard ne répond pas au besoin. Dans ce cas il est nécessaire de développer son propre module de numérotation.
Plus d'information sur la page [[Créer un module de numérotation]]

== Les modèles et la génération de documents ==
Plus de documentation au sujet de la génération de documents depuis des modèles est disponible sur la page [[Creer un modele de document]]

== Le stockage des fichiers/documents ==
Voir la page [[Document générés]]

== Les exports/imports de masse ==
# [[Imports de masse]]
# [[Exports|Exports de masse]]

== Interfaces et liens avec d'autres applications ==
# [[Interfaces Dolibarr vers exterieur]] (Triggers Dolibarr)
# [[Interfaces Exterieur vers Dolibarr]]
# [[Services Web]]

== FAQ ==
# [[FAQ Développeur]]

Developer FAQ

2009-02-03T18:53:14Z

Mcg: /* Changer mon système de numérotation des factures en cours de route */

{{ToTranslate}}
{{TemplateDocDev}}

== Récupérer/mettre à jour une version CVS développeur ==
'''Effectuer une sauvegarde de ses données et de sa configuration'''

Si vous avez déjà une installation en place, sauvegarder votre fichier htdocs/conf/conf.php au cas où.

'''Récupération dernière version des sources par download'''

Cette méthode permet de récupérer la version CVS de la branche de développement principale (appelée HEAD). L'opération consiste à récupérer la dernière version des fichiers de Dolibarr regroupés toutes les nuits dans un zip.
Pour cela, voir la [http://www.dolibarr.org/index.php?option=com_docman&task=cat_view&gid=64&&Itemid=36 version CVS du jour].
Les nouveaux fichiers doivent écraser les anciens.

'''Récupération dernière version des sources par CVS'''

Pour récupérer la dernière version en cours de développement, vous pouvez aussi directement utiliser [http://savannah.nongnu.org/cvs/?group=dolibarr le serveur CVS en mode anonyme], si vous disposez d'un client CVS (commande CVS sous Linux, ou TortoiseCVS par exemple sous Windows).

La commande permettant de récupérer un snapshot intégral (sans suivi cvs) dans le répertoire courant est:
''
CVSROOT=:pserver:anonymous@cvs.savannah.nongnu.org:/sources/dolibarr
export CVSROOT
cvs -q checkout -r HEAD -d ./ dolibarr/
''
HEAD signifie qu'on veut la dernière version de la version en cours de développement.

La commande permettant de mettre à jour localement une copie de travail CVS qui a déjà été rapatriée:
''Sous linux (script shell):
CVSROOT=:pserver:anonymous@cvs.savannah.nongnu.org:/sources/dolibarr
export CVSROOT
cvs -q update -P -d
Sous Windows avec Tortoise cvs
"C:\Program Files\CVSNT\cvs.exe" -q update -P -d
CVSROOT=:pserver:anonymous@cvs.savannah.nongnu.org:/sources/dolibarr''
Et pour remettre au propre votre copie locale en annulant vos modifications sur les fichiers intégrés au cvs:
"C:\Program Files\CVSNT\cvs.exe" -q update -P -C -d
CVSROOT=:pserver:anonymous@cvs.savannah.nongnu.org:/sources/dolibarr

Si besoin, modifiez les droits de propriétaire des dossiers, pour que le serveur y ait accès.

'''Récupération d'une autre branche par CVS'''

Si vous désirez une version particulière (avec ces patchs), il vous faut suivre la même procédure que ci-dessus mais en remplaçant HEAD par le nom de la branche.
Par exemple DOLIBARR_2_2_BRANCH pour la branche 2.2 ou DOLIBARR_2_4_BRANCH pour la branche 2.4.

'''Restaurer sa configuration'''

Restaurer le fichier de configuration (./htdocs/conf/conf.php) d'après sa sauvegarde si vous l'avez écrasé.

'''Mise a jour de la base'''

La deuxième étape consiste à migrer la base. Pour celà, il suffit d'appeler la page
http://maracinedolibarr/install/
et choisir l'option "Mise à jour".

Cette procédure de migration/mise à jour est conçue pour fonctionner quel que soit l'état de départ et peut être repassée plusieurs fois sans risque.

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

== Comment créer un nouveau thème ==
Voir pour cela la page [[Themes]]

== Comment développer mon propre système de menu ==
Voir pour cela la page [[Système_de_menus]]

== Comment développer mon propre module ==
Voir pour cela la page [[Developpement_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:
<pre>
update llx_facture set facnumber=concat('FA',substr(facnumber,4,4),'-',substr(facnumber,8))
where facnumber like 'F%' and facnumber not like 'FA%';
</pre>

Par exemple, pour passer d'un modèle FAYYMM999 à Terre (FAYYMM-999), vous pouvez exécuter la requête suivante:
<pre>
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 '%-%';
</pre>

== Soumettre un patch, amélioration ou participer au développement ==

* '''Avec accès CVS en écriture '''
A ce jour, les accès en écriture au CVS sont restreints (le nombre de commit étant déjà suffisamment dynamique). Si vous bénéficiez à l'heure actuelle d'un accès CVS en écriture, utilisez-le et à condition que ce qui est commité corresponde bien à votre grade de développeur Dolibarr (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 accès au CVS (vous êtes donc au grade de membre ou chasseur de l'alliance Dolibarr), il est nécessaire de suivre la procédure qui suit...

* '''Sans accès CVS en écriture'''
Sans accès CVS en écriture (sans compte développeur savannah), il est nécessaire de fournir par mail, votre fichier patch.

Sous tout OS:

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 CVS 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/component/option,com_docman/task,cat_view/gid,50/Itemid,36/lang,en/ site officiel de Dolibarr].

- 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] sous Windows) de la manière suivante:
<pre>
diff -Naur --exclude=CVS --exclude=".#*" --exclude="*~" --exclude='*.rej' --exclude='*.orig'
--exclude="*.bak" --exclude=conf.php --exclude=documents ancien_rep nouveau_rep > fichier.patch
</pre>
Envoyer votre patch sur la ML.
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:

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.

Au lieu de rechercher manuellement vos fichiers, si vous avez installé conjointement ''TortoiseCVS'' et ''Winmerge'', vous pouvez vous contenter de votre version modifiée sur votre ordinateur, et de la version CVS en ligne. Sous l'explorateur Windows, faites un clic droit sur le fichier qui doit être patché, et choisissez "CVS comparer" (pas WinMerge qui se trouve quelques lignes plus bas). Tortoise va lui-même lancer WinMerge. Puis reprenez la procédure décrite ci-dessus.

'''Appliquer un patch'''
Si votre patch n'a pas encore été appliqué, mais que vous souhaitez de votre coté l'appliquer sur votre serveur linux fraichement mis à jour depuis la CVS, cela est possible grâce à l'utilitaire patch.
En admettant que vous avez créé votre patch à partir du répertoire htdocs de votre copie locale du cvs modifiée par vos soins, et que vous avez envoyé votre patch (monfichier.patch) sur le serveur dans le dossier patchs situé au meme niveau que votre dossier htdocs distant, la commande suivante devrait faire l'affaire (executée depuis le dossier patchs):
patch -u -p0 -d ../htdocs < monfichier.patch
<nowiki>Pour information: -p0 permet d'utiliser le chemin entier tel que mentionné dans le fichier de patch (-pn en retire les n premiers niveau de l'arborescence)
-d permet de préciser le chemin relatif vers le dossier htdocs à patcher.
< permet de donner le chemin vers le fichier source à utiliser (le patch en mode unifié)
-u permet de préciser que le patch est en mode unifié</nowiki>

== Comment packager/livrer un module pour utilisation ==
Voir la page [[Developpement_module#Cr.C3.A9er_un_package_pour_livrer_et_installer_votre_module|Developpement moduel - Créer un package pour livrer et installer votre module]]

== 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 certains 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 CVS) 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 ces 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 familié 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'attendre ce but. Ne soyez donc pas offensé si, en tant que développeur, vous ne pouvez disposer d'un accès CVS en écriture avant un certain délai.

* '''Membre de l'alliance'''

La première chose qu'une personne désireuse d'aide doit faire et d'abord se familiariser avec les règles et normes de développements.
En lisant toute la [[Documentation Développeur]], vous faites preuve de volonté suffisante pour devenir automatiquement '''Membre''' de l'alliance Dolibarr (Votre grade est au niveau '''Membre'''). Et tout lire, c'est pas le plus facile...

Ce grade s'obtient sans validation supérieure.

* '''Chasseur de l'alliance'''

L'étape suivante consiste à soumettre des patch, en commençant par des simples, soit sur la Mailing List dev (voir [[FAQ_D%C3%A9veloppeur#Soumettre_un_patch.2C_am.C3.A9lioration_ou_participer_au_d.C3.A9veloppement|FAQ Développeur]] pour la procédure), soit sur le forum (Mailing List préférée).

A votre première soumission acceptée (incluse dans le CVS par un Amiral ou Jedi), vous entrez alors automatiquement dans la famille des '''Chasseurs''' de l'alliance Dolibarr.

Le nombre de chasseurs n'est pas limité. Plus, il y en aura, plus on sera fort.
Les chasseurs représentent la force vive principale de l'alliance Dolibarr.

* '''Amiral de l'alliance'''

Ce n'est qu'au bout d'un temps variable (qui peut être très long) au rang de Chasseur, et si la qualité des patch qui ont été envoyés est satisfaisante, qu'un Yoda en place vous offrira un accès CVS direct.
Vous êtes devenu un '''Amiral''' de l'alliance Dolibarr.

Ce titre ne se demande pas, il s'obtient par décision ou proposition d'un '''Jedi''' ou '''Yoda''' qui estime que vous avez soumis suffisamment de patch pour être un sérieux '''Amiral'''.
L'accès CVS d'un '''Amiral''' doit cependant n'être utilisé que pour commiter soit des traductions, soit des corrections de bugs déclarées sur Savannah ou le forum (que ces corrections soit personnelles ou issues d'un patch soumis par un '''Chasseur''').
Tout commit CVS doit ainsi obligatoirement inclure, dans la description (le champ log de commit), le numéro du bug Savannah corrigé OU le titre du message du forum signalant le problème. Seul une traduction échappe à cette contrainte (pas de restrictions pour les traductions). Le non respect de cette contrainte, peut provoquer une rétrogradation au rang de '''Chasseur'''.
Pour la soumission de nouvelles fonctionnalités, il faut donc obligatoirement continuer sur le principe de patchs envoyés sur la ML.

L'obtention du grade d'Amiral est toutefois rare car limité. La qualité de Dolibarr ne pouvant être atteinte que par un nombre d'Amiraux contrôlé, ce qui n'empêche pas d'avoir un nombre de
développeurs (Chasseurs) très important (grâce au système de patch).

* '''Jedi'''

C'est encore au bout d'un temps variable (sûrement le plus long de tous) au rang d'Amiral, et si la qualité des patch qui ont été envoyés est satisfaisante, qu'un Yoda vous signalera que vous êtes autorisé à réaliser des commits sans restrictions de fonctionnalités, à condition d'avoir cependant l'aval de principe d'un Maitre Yoda à qui vous aurez expliquer la fonctionnalité.
Il peut toutefois y avoir une restriction temporaire définie par un Yoda pour raison de release proche.
Vous êtes alors devenu un '''Jedi'''.

Ce titre ne se demande pas, il s'obtient par proposition d'un autre Jedi ou d'un Yoda.

Ce privilège est toutefois exceptionnel. La qualité de Dolibarr ne pouvant être atteinte
que par un nombre de Jedi contrôlé, ce qui n'empêche pas d'avoir un nombre de
développeurs (Chasseurs) très important (grâce au système de patch).

* '''Yoda'''

Au nombre de 1 à 5, être un '''Yoda''', c'est assurer la gestion globale du développement du projet. Ce rang s'obtient par succession, suite au départ d'un Yoda qui se retire, par nomination directe ou vote organisé par le Yoda partant.

...Et Dark Vador alors ?

Il existe. Dans la galaxie Dolibarr, on qualifie de Dark Vador, le parasite qui pollue 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 constructives qui aident à progresser. La mauvaise foi ou le mauvais ton est souvent de rigueur chez les Dark Vador...
Heureusement, statistiquement, on ne constate l'apparition et la mort que d'un seul Dark Vador par an environ...

Voir la page [[Le projet Dolibarr]] pour connaitre la liste des personnes à chaque grade actuellement.

Developer FAQ

2009-02-03T18:52:06Z

Mcg: /* Comment créer un nouveau thème */

{{ToTranslate}}
{{TemplateDocDev}}

== Récupérer/mettre à jour une version CVS développeur ==
'''Effectuer une sauvegarde de ses données et de sa configuration'''

Si vous avez déjà une installation en place, sauvegarder votre fichier htdocs/conf/conf.php au cas où.

'''Récupération dernière version des sources par download'''

Cette méthode permet de récupérer la version CVS de la branche de développement principale (appelée HEAD). L'opération consiste à récupérer la dernière version des fichiers de Dolibarr regroupés toutes les nuits dans un zip.
Pour cela, voir la [http://www.dolibarr.org/index.php?option=com_docman&task=cat_view&gid=64&&Itemid=36 version CVS du jour].
Les nouveaux fichiers doivent écraser les anciens.

'''Récupération dernière version des sources par CVS'''

Pour récupérer la dernière version en cours de développement, vous pouvez aussi directement utiliser [http://savannah.nongnu.org/cvs/?group=dolibarr le serveur CVS en mode anonyme], si vous disposez d'un client CVS (commande CVS sous Linux, ou TortoiseCVS par exemple sous Windows).

La commande permettant de récupérer un snapshot intégral (sans suivi cvs) dans le répertoire courant est:
''
CVSROOT=:pserver:anonymous@cvs.savannah.nongnu.org:/sources/dolibarr
export CVSROOT
cvs -q checkout -r HEAD -d ./ dolibarr/
''
HEAD signifie qu'on veut la dernière version de la version en cours de développement.

La commande permettant de mettre à jour localement une copie de travail CVS qui a déjà été rapatriée:
''Sous linux (script shell):
CVSROOT=:pserver:anonymous@cvs.savannah.nongnu.org:/sources/dolibarr
export CVSROOT
cvs -q update -P -d
Sous Windows avec Tortoise cvs
"C:\Program Files\CVSNT\cvs.exe" -q update -P -d
CVSROOT=:pserver:anonymous@cvs.savannah.nongnu.org:/sources/dolibarr''
Et pour remettre au propre votre copie locale en annulant vos modifications sur les fichiers intégrés au cvs:
"C:\Program Files\CVSNT\cvs.exe" -q update -P -C -d
CVSROOT=:pserver:anonymous@cvs.savannah.nongnu.org:/sources/dolibarr

Si besoin, modifiez les droits de propriétaire des dossiers, pour que le serveur y ait accès.

'''Récupération d'une autre branche par CVS'''

Si vous désirez une version particulière (avec ces patchs), il vous faut suivre la même procédure que ci-dessus mais en remplaçant HEAD par le nom de la branche.
Par exemple DOLIBARR_2_2_BRANCH pour la branche 2.2 ou DOLIBARR_2_4_BRANCH pour la branche 2.4.

'''Restaurer sa configuration'''

Restaurer le fichier de configuration (./htdocs/conf/conf.php) d'après sa sauvegarde si vous l'avez écrasé.

'''Mise a jour de la base'''

La deuxième étape consiste à migrer la base. Pour celà, il suffit d'appeler la page
http://maracinedolibarr/install/
et choisir l'option "Mise à jour".

Cette procédure de migration/mise à jour est conçue pour fonctionner quel que soit l'état de départ et peut être repassée plusieurs fois sans risque.

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

== Comment créer un nouveau thème ==
Voir pour cela la page [[Themes]]

== Comment développer mon propre système de menu ==
Voir pour cela la page [[Système_de_menus]]

== Comment développer mon propre module ==
Voir pour cela la page [[Developpement_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:
<pre>
update llx_facture set facnumber=concat('FA',substr(facnumber,4,4),'-',substr(facnumber,8))
where facnumber like 'F%' and facnumber not like 'FA%';
</pre>

Par exemple, pour passer d'un modele FAYYMM999 à Terre (FAYYMM-999), vous pouvez exécuter la requête suivante:
<pre>
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 '%-%';
</pre>

== Soumettre un patch, amélioration ou participer au développement ==

* '''Avec accès CVS en écriture '''
A ce jour, les accès en écriture au CVS sont restreints (le nombre de commit étant déjà suffisamment dynamique). Si vous bénéficiez à l'heure actuelle d'un accès CVS en écriture, utilisez-le et à condition que ce qui est commité corresponde bien à votre grade de développeur Dolibarr (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 accès au CVS (vous êtes donc au grade de membre ou chasseur de l'alliance Dolibarr), il est nécessaire de suivre la procédure qui suit...

* '''Sans accès CVS en écriture'''
Sans accès CVS en écriture (sans compte développeur savannah), il est nécessaire de fournir par mail, votre fichier patch.

Sous tout OS:

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 CVS 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/component/option,com_docman/task,cat_view/gid,50/Itemid,36/lang,en/ site officiel de Dolibarr].

- 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] sous Windows) de la manière suivante:
<pre>
diff -Naur --exclude=CVS --exclude=".#*" --exclude="*~" --exclude='*.rej' --exclude='*.orig'
--exclude="*.bak" --exclude=conf.php --exclude=documents ancien_rep nouveau_rep > fichier.patch
</pre>
Envoyer votre patch sur la ML.
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:

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.

Au lieu de rechercher manuellement vos fichiers, si vous avez installé conjointement ''TortoiseCVS'' et ''Winmerge'', vous pouvez vous contenter de votre version modifiée sur votre ordinateur, et de la version CVS en ligne. Sous l'explorateur Windows, faites un clic droit sur le fichier qui doit être patché, et choisissez "CVS comparer" (pas WinMerge qui se trouve quelques lignes plus bas). Tortoise va lui-même lancer WinMerge. Puis reprenez la procédure décrite ci-dessus.

'''Appliquer un patch'''
Si votre patch n'a pas encore été appliqué, mais que vous souhaitez de votre coté l'appliquer sur votre serveur linux fraichement mis à jour depuis la CVS, cela est possible grâce à l'utilitaire patch.
En admettant que vous avez créé votre patch à partir du répertoire htdocs de votre copie locale du cvs modifiée par vos soins, et que vous avez envoyé votre patch (monfichier.patch) sur le serveur dans le dossier patchs situé au meme niveau que votre dossier htdocs distant, la commande suivante devrait faire l'affaire (executée depuis le dossier patchs):
patch -u -p0 -d ../htdocs < monfichier.patch
<nowiki>Pour information: -p0 permet d'utiliser le chemin entier tel que mentionné dans le fichier de patch (-pn en retire les n premiers niveau de l'arborescence)
-d permet de préciser le chemin relatif vers le dossier htdocs à patcher.
< permet de donner le chemin vers le fichier source à utiliser (le patch en mode unifié)
-u permet de préciser que le patch est en mode unifié</nowiki>

== Comment packager/livrer un module pour utilisation ==
Voir la page [[Developpement_module#Cr.C3.A9er_un_package_pour_livrer_et_installer_votre_module|Developpement moduel - Créer un package pour livrer et installer votre module]]

== 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 certains 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 CVS) 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 ces 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 familié 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'attendre ce but. Ne soyez donc pas offensé si, en tant que développeur, vous ne pouvez disposer d'un accès CVS en écriture avant un certain délai.

* '''Membre de l'alliance'''

La première chose qu'une personne désireuse d'aide doit faire et d'abord se familiariser avec les règles et normes de développements.
En lisant toute la [[Documentation Développeur]], vous faites preuve de volonté suffisante pour devenir automatiquement '''Membre''' de l'alliance Dolibarr (Votre grade est au niveau '''Membre'''). Et tout lire, c'est pas le plus facile...

Ce grade s'obtient sans validation supérieure.

* '''Chasseur de l'alliance'''

L'étape suivante consiste à soumettre des patch, en commençant par des simples, soit sur la Mailing List dev (voir [[FAQ_D%C3%A9veloppeur#Soumettre_un_patch.2C_am.C3.A9lioration_ou_participer_au_d.C3.A9veloppement|FAQ Développeur]] pour la procédure), soit sur le forum (Mailing List préférée).

A votre première soumission acceptée (incluse dans le CVS par un Amiral ou Jedi), vous entrez alors automatiquement dans la famille des '''Chasseurs''' de l'alliance Dolibarr.

Le nombre de chasseurs n'est pas limité. Plus, il y en aura, plus on sera fort.
Les chasseurs représentent la force vive principale de l'alliance Dolibarr.

* '''Amiral de l'alliance'''

Ce n'est qu'au bout d'un temps variable (qui peut être très long) au rang de Chasseur, et si la qualité des patch qui ont été envoyés est satisfaisante, qu'un Yoda en place vous offrira un accès CVS direct.
Vous êtes devenu un '''Amiral''' de l'alliance Dolibarr.

Ce titre ne se demande pas, il s'obtient par décision ou proposition d'un '''Jedi''' ou '''Yoda''' qui estime que vous avez soumis suffisamment de patch pour être un sérieux '''Amiral'''.
L'accès CVS d'un '''Amiral''' doit cependant n'être utilisé que pour commiter soit des traductions, soit des corrections de bugs déclarées sur Savannah ou le forum (que ces corrections soit personnelles ou issues d'un patch soumis par un '''Chasseur''').
Tout commit CVS doit ainsi obligatoirement inclure, dans la description (le champ log de commit), le numéro du bug Savannah corrigé OU le titre du message du forum signalant le problème. Seul une traduction échappe à cette contrainte (pas de restrictions pour les traductions). Le non respect de cette contrainte, peut provoquer une rétrogradation au rang de '''Chasseur'''.
Pour la soumission de nouvelles fonctionnalités, il faut donc obligatoirement continuer sur le principe de patchs envoyés sur la ML.

L'obtention du grade d'Amiral est toutefois rare car limité. La qualité de Dolibarr ne pouvant être atteinte que par un nombre d'Amiraux contrôlé, ce qui n'empêche pas d'avoir un nombre de
développeurs (Chasseurs) très important (grâce au système de patch).

* '''Jedi'''

C'est encore au bout d'un temps variable (sûrement le plus long de tous) au rang d'Amiral, et si la qualité des patch qui ont été envoyés est satisfaisante, qu'un Yoda vous signalera que vous êtes autorisé à réaliser des commits sans restrictions de fonctionnalités, à condition d'avoir cependant l'aval de principe d'un Maitre Yoda à qui vous aurez expliquer la fonctionnalité.
Il peut toutefois y avoir une restriction temporaire définie par un Yoda pour raison de release proche.
Vous êtes alors devenu un '''Jedi'''.

Ce titre ne se demande pas, il s'obtient par proposition d'un autre Jedi ou d'un Yoda.

Ce privilège est toutefois exceptionnel. La qualité de Dolibarr ne pouvant être atteinte
que par un nombre de Jedi contrôlé, ce qui n'empêche pas d'avoir un nombre de
développeurs (Chasseurs) très important (grâce au système de patch).

* '''Yoda'''

Au nombre de 1 à 5, être un '''Yoda''', c'est assurer la gestion globale du développement du projet. Ce rang s'obtient par succession, suite au départ d'un Yoda qui se retire, par nomination directe ou vote organisé par le Yoda partant.

...Et Dark Vador alors ?

Il existe. Dans la galaxie Dolibarr, on qualifie de Dark Vador, le parasite qui pollue 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 constructives qui aident à progresser. La mauvaise foi ou le mauvais ton est souvent de rigueur chez les Dark Vador...
Heureusement, statistiquement, on ne constate l'apparition et la mort que d'un seul Dark Vador par an environ...

Voir la page [[Le projet Dolibarr]] pour connaitre la liste des personnes à chaque grade actuellement.

Developer FAQ

2009-02-03T18:51:30Z

Mcg: /* Récupérer/mettre à jour une version CVS développeur */

{{ToTranslate}}
{{TemplateDocDev}}

== Récupérer/mettre à jour une version CVS développeur ==
'''Effectuer une sauvegarde de ses données et de sa configuration'''

Si vous avez déjà une installation en place, sauvegarder votre fichier htdocs/conf/conf.php au cas où.

'''Récupération dernière version des sources par download'''

Cette méthode permet de récupérer la version CVS de la branche de développement principale (appelée HEAD). L'opération consiste à récupérer la dernière version des fichiers de Dolibarr regroupés toutes les nuits dans un zip.
Pour cela, voir la [http://www.dolibarr.org/index.php?option=com_docman&task=cat_view&gid=64&&Itemid=36 version CVS du jour].
Les nouveaux fichiers doivent écraser les anciens.

'''Récupération dernière version des sources par CVS'''

Pour récupérer la dernière version en cours de développement, vous pouvez aussi directement utiliser [http://savannah.nongnu.org/cvs/?group=dolibarr le serveur CVS en mode anonyme], si vous disposez d'un client CVS (commande CVS sous Linux, ou TortoiseCVS par exemple sous Windows).

La commande permettant de récupérer un snapshot intégral (sans suivi cvs) dans le répertoire courant est:
''
CVSROOT=:pserver:anonymous@cvs.savannah.nongnu.org:/sources/dolibarr
export CVSROOT
cvs -q checkout -r HEAD -d ./ dolibarr/
''
HEAD signifie qu'on veut la dernière version de la version en cours de développement.

La commande permettant de mettre à jour localement une copie de travail CVS qui a déjà été rapatriée:
''Sous linux (script shell):
CVSROOT=:pserver:anonymous@cvs.savannah.nongnu.org:/sources/dolibarr
export CVSROOT
cvs -q update -P -d
Sous Windows avec Tortoise cvs
"C:\Program Files\CVSNT\cvs.exe" -q update -P -d
CVSROOT=:pserver:anonymous@cvs.savannah.nongnu.org:/sources/dolibarr''
Et pour remettre au propre votre copie locale en annulant vos modifications sur les fichiers intégrés au cvs:
"C:\Program Files\CVSNT\cvs.exe" -q update -P -C -d
CVSROOT=:pserver:anonymous@cvs.savannah.nongnu.org:/sources/dolibarr

Si besoin, modifiez les droits de propriétaire des dossiers, pour que le serveur y ait accès.

'''Récupération d'une autre branche par CVS'''

Si vous désirez une version particulière (avec ces patchs), il vous faut suivre la même procédure que ci-dessus mais en remplaçant HEAD par le nom de la branche.
Par exemple DOLIBARR_2_2_BRANCH pour la branche 2.2 ou DOLIBARR_2_4_BRANCH pour la branche 2.4.

'''Restaurer sa configuration'''

Restaurer le fichier de configuration (./htdocs/conf/conf.php) d'après sa sauvegarde si vous l'avez écrasé.

'''Mise a jour de la base'''

La deuxième étape consiste à migrer la base. Pour celà, il suffit d'appeler la page
http://maracinedolibarr/install/
et choisir l'option "Mise à jour".

Cette procédure de migration/mise à jour est conçue pour fonctionner quel que soit l'état de départ et peut être repassée plusieurs fois sans risque.

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

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

== Comment développer mon propre système de menu ==
Voir pour cela la page [[Système_de_menus]]

== Comment développer mon propre module ==
Voir pour cela la page [[Developpement_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:
<pre>
update llx_facture set facnumber=concat('FA',substr(facnumber,4,4),'-',substr(facnumber,8))
where facnumber like 'F%' and facnumber not like 'FA%';
</pre>

Par exemple, pour passer d'un modele FAYYMM999 à Terre (FAYYMM-999), vous pouvez exécuter la requête suivante:
<pre>
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 '%-%';
</pre>

== Soumettre un patch, amélioration ou participer au développement ==

* '''Avec accès CVS en écriture '''
A ce jour, les accès en écriture au CVS sont restreints (le nombre de commit étant déjà suffisamment dynamique). Si vous bénéficiez à l'heure actuelle d'un accès CVS en écriture, utilisez-le et à condition que ce qui est commité corresponde bien à votre grade de développeur Dolibarr (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 accès au CVS (vous êtes donc au grade de membre ou chasseur de l'alliance Dolibarr), il est nécessaire de suivre la procédure qui suit...

* '''Sans accès CVS en écriture'''
Sans accès CVS en écriture (sans compte développeur savannah), il est nécessaire de fournir par mail, votre fichier patch.

Sous tout OS:

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 CVS 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/component/option,com_docman/task,cat_view/gid,50/Itemid,36/lang,en/ site officiel de Dolibarr].

- 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] sous Windows) de la manière suivante:
<pre>
diff -Naur --exclude=CVS --exclude=".#*" --exclude="*~" --exclude='*.rej' --exclude='*.orig'
--exclude="*.bak" --exclude=conf.php --exclude=documents ancien_rep nouveau_rep > fichier.patch
</pre>
Envoyer votre patch sur la ML.
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:

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.

Au lieu de rechercher manuellement vos fichiers, si vous avez installé conjointement ''TortoiseCVS'' et ''Winmerge'', vous pouvez vous contenter de votre version modifiée sur votre ordinateur, et de la version CVS en ligne. Sous l'explorateur Windows, faites un clic droit sur le fichier qui doit être patché, et choisissez "CVS comparer" (pas WinMerge qui se trouve quelques lignes plus bas). Tortoise va lui-même lancer WinMerge. Puis reprenez la procédure décrite ci-dessus.

'''Appliquer un patch'''
Si votre patch n'a pas encore été appliqué, mais que vous souhaitez de votre coté l'appliquer sur votre serveur linux fraichement mis à jour depuis la CVS, cela est possible grâce à l'utilitaire patch.
En admettant que vous avez créé votre patch à partir du répertoire htdocs de votre copie locale du cvs modifiée par vos soins, et que vous avez envoyé votre patch (monfichier.patch) sur le serveur dans le dossier patchs situé au meme niveau que votre dossier htdocs distant, la commande suivante devrait faire l'affaire (executée depuis le dossier patchs):
patch -u -p0 -d ../htdocs < monfichier.patch
<nowiki>Pour information: -p0 permet d'utiliser le chemin entier tel que mentionné dans le fichier de patch (-pn en retire les n premiers niveau de l'arborescence)
-d permet de préciser le chemin relatif vers le dossier htdocs à patcher.
< permet de donner le chemin vers le fichier source à utiliser (le patch en mode unifié)
-u permet de préciser que le patch est en mode unifié</nowiki>

== Comment packager/livrer un module pour utilisation ==
Voir la page [[Developpement_module#Cr.C3.A9er_un_package_pour_livrer_et_installer_votre_module|Developpement moduel - Créer un package pour livrer et installer votre module]]

== 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 certains 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 CVS) 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 ces 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 familié 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'attendre ce but. Ne soyez donc pas offensé si, en tant que développeur, vous ne pouvez disposer d'un accès CVS en écriture avant un certain délai.

* '''Membre de l'alliance'''

La première chose qu'une personne désireuse d'aide doit faire et d'abord se familiariser avec les règles et normes de développements.
En lisant toute la [[Documentation Développeur]], vous faites preuve de volonté suffisante pour devenir automatiquement '''Membre''' de l'alliance Dolibarr (Votre grade est au niveau '''Membre'''). Et tout lire, c'est pas le plus facile...

Ce grade s'obtient sans validation supérieure.

* '''Chasseur de l'alliance'''

L'étape suivante consiste à soumettre des patch, en commençant par des simples, soit sur la Mailing List dev (voir [[FAQ_D%C3%A9veloppeur#Soumettre_un_patch.2C_am.C3.A9lioration_ou_participer_au_d.C3.A9veloppement|FAQ Développeur]] pour la procédure), soit sur le forum (Mailing List préférée).

A votre première soumission acceptée (incluse dans le CVS par un Amiral ou Jedi), vous entrez alors automatiquement dans la famille des '''Chasseurs''' de l'alliance Dolibarr.

Le nombre de chasseurs n'est pas limité. Plus, il y en aura, plus on sera fort.
Les chasseurs représentent la force vive principale de l'alliance Dolibarr.

* '''Amiral de l'alliance'''

Ce n'est qu'au bout d'un temps variable (qui peut être très long) au rang de Chasseur, et si la qualité des patch qui ont été envoyés est satisfaisante, qu'un Yoda en place vous offrira un accès CVS direct.
Vous êtes devenu un '''Amiral''' de l'alliance Dolibarr.

Ce titre ne se demande pas, il s'obtient par décision ou proposition d'un '''Jedi''' ou '''Yoda''' qui estime que vous avez soumis suffisamment de patch pour être un sérieux '''Amiral'''.
L'accès CVS d'un '''Amiral''' doit cependant n'être utilisé que pour commiter soit des traductions, soit des corrections de bugs déclarées sur Savannah ou le forum (que ces corrections soit personnelles ou issues d'un patch soumis par un '''Chasseur''').
Tout commit CVS doit ainsi obligatoirement inclure, dans la description (le champ log de commit), le numéro du bug Savannah corrigé OU le titre du message du forum signalant le problème. Seul une traduction échappe à cette contrainte (pas de restrictions pour les traductions). Le non respect de cette contrainte, peut provoquer une rétrogradation au rang de '''Chasseur'''.
Pour la soumission de nouvelles fonctionnalités, il faut donc obligatoirement continuer sur le principe de patchs envoyés sur la ML.

L'obtention du grade d'Amiral est toutefois rare car limité. La qualité de Dolibarr ne pouvant être atteinte que par un nombre d'Amiraux contrôlé, ce qui n'empêche pas d'avoir un nombre de
développeurs (Chasseurs) très important (grâce au système de patch).

* '''Jedi'''

C'est encore au bout d'un temps variable (sûrement le plus long de tous) au rang d'Amiral, et si la qualité des patch qui ont été envoyés est satisfaisante, qu'un Yoda vous signalera que vous êtes autorisé à réaliser des commits sans restrictions de fonctionnalités, à condition d'avoir cependant l'aval de principe d'un Maitre Yoda à qui vous aurez expliquer la fonctionnalité.
Il peut toutefois y avoir une restriction temporaire définie par un Yoda pour raison de release proche.
Vous êtes alors devenu un '''Jedi'''.

Ce titre ne se demande pas, il s'obtient par proposition d'un autre Jedi ou d'un Yoda.

Ce privilège est toutefois exceptionnel. La qualité de Dolibarr ne pouvant être atteinte
que par un nombre de Jedi contrôlé, ce qui n'empêche pas d'avoir un nombre de
développeurs (Chasseurs) très important (grâce au système de patch).

* '''Yoda'''

Au nombre de 1 à 5, être un '''Yoda''', c'est assurer la gestion globale du développement du projet. Ce rang s'obtient par succession, suite au départ d'un Yoda qui se retire, par nomination directe ou vote organisé par le Yoda partant.

...Et Dark Vador alors ?

Il existe. Dans la galaxie Dolibarr, on qualifie de Dark Vador, le parasite qui pollue 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 constructives qui aident à progresser. La mauvaise foi ou le mauvais ton est souvent de rigueur chez les Dark Vador...
Heureusement, statistiquement, on ne constate l'apparition et la mort que d'un seul Dark Vador par an environ...

Voir la page [[Le projet Dolibarr]] pour connaitre la liste des personnes à chaque grade actuellement.

Developer FAQ

2009-02-03T18:49:58Z

Mcg: /* Récupérer/mettre à jour une version CVS développeur */

{{ToTranslate}}
{{TemplateDocDev}}

== Récupérer/mettre à jour une version CVS développeur ==
'''Effectuer une sauvegarde de ses données et de sa configuration'''

Si vous avez déjà une installation en place, sauvegarder votre fichier htdocs/conf/conf.php au cas où.

'''Récupération dernière version des sources par download'''

Cette méthode permet de récupérer la version CVS de la branche de développement principale (appelée HEAD). L'opération consiste à récupérer la dernière version des fichiers de Dolibarr regroupés toutes les nuits dans un zip.
Pour cela, voir la [http://www.dolibarr.org/index.php?option=com_docman&task=cat_view&gid=64&&Itemid=36 version CVS du jour].
Les nouveaux fichiers doivent écraser les anciens.

'''Récupération dernière version des sources par CVS'''

Pour récupérer la dernière version en cours de développement, vous pouvez aussi directement utiliser [http://savannah.nongnu.org/cvs/?group=dolibarr le serveur CVS en mode anonyme], si vous disposez d'un client CVS (commande CVS sous Linux, ou TortoiseCVS par exemple sous Windows).

La commande permettant de récupérer un snapshot intégral (sans suivi cvs) dans le répertoire courant est:
''
CVSROOT=:pserver:anonymous@cvs.savannah.nongnu.org:/sources/dolibarr
export CVSROOT
cvs -q checkout -r HEAD -d ./ dolibarr/
''
HEAD signifie qu'on veut la dernière version de la version en cours de développement.

La commande permettant de mettre à jour localement une copie de travail CVS qui a déjà été rappatriée:
''Sous linux (script shell):
CVSROOT=:pserver:anonymous@cvs.savannah.nongnu.org:/sources/dolibarr
export CVSROOT
cvs -q update -P -d
Sous Windows avec Tortoise cvs
"C:\Program Files\CVSNT\cvs.exe" -q update -P -d
CVSROOT=:pserver:anonymous@cvs.savannah.nongnu.org:/sources/dolibarr''
Et pour remettre au propre votre copie locale en annulant vos modifications sur les fichiers intégrés au cvs:
"C:\Program Files\CVSNT\cvs.exe" -q update -P -C -d
CVSROOT=:pserver:anonymous@cvs.savannah.nongnu.org:/sources/dolibarr

Si besoin, modifiez les droits de propriétaire des dossiers, pour que le serveur y ait accès.

'''Récupération d'une autre branche par CVS'''

Si vous désirez une version particulière (avec ces patchs), il vous faut suivre la même procédure que ci-dessus mais en remplaçant HEAD par le nom de la branche.
Par exemple DOLIBARR_2_2_BRANCH pour la branche 2.2 ou DOLIBARR_2_4_BRANCH pour la branche 2.4.

'''Restaurer sa configuration'''

Restaurer le fichier de configuration (./htdocs/conf/conf.php) d'après sa sauvegarde si vous l'avez écrasé.

'''Mise a jour de la base'''

La deuxième étape consiste à migrer la base. Pour celà, il suffit d'appeler la page
http://maracinedolibarr/install/
et choisir l'option "Mise à jour".

Cette procédure de migration/mise à jour est conçue pour fonctionner quel que soit l'état de départ et peut être repassée plusieurs fois sans risque.

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

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

== Comment développer mon propre système de menu ==
Voir pour cela la page [[Système_de_menus]]

== Comment développer mon propre module ==
Voir pour cela la page [[Developpement_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:
<pre>
update llx_facture set facnumber=concat('FA',substr(facnumber,4,4),'-',substr(facnumber,8))
where facnumber like 'F%' and facnumber not like 'FA%';
</pre>

Par exemple, pour passer d'un modele FAYYMM999 à Terre (FAYYMM-999), vous pouvez exécuter la requête suivante:
<pre>
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 '%-%';
</pre>

== Soumettre un patch, amélioration ou participer au développement ==

* '''Avec accès CVS en écriture '''
A ce jour, les accès en écriture au CVS sont restreints (le nombre de commit étant déjà suffisamment dynamique). Si vous bénéficiez à l'heure actuelle d'un accès CVS en écriture, utilisez-le et à condition que ce qui est commité corresponde bien à votre grade de développeur Dolibarr (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 accès au CVS (vous êtes donc au grade de membre ou chasseur de l'alliance Dolibarr), il est nécessaire de suivre la procédure qui suit...

* '''Sans accès CVS en écriture'''
Sans accès CVS en écriture (sans compte développeur savannah), il est nécessaire de fournir par mail, votre fichier patch.

Sous tout OS:

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 CVS 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/component/option,com_docman/task,cat_view/gid,50/Itemid,36/lang,en/ site officiel de Dolibarr].

- 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] sous Windows) de la manière suivante:
<pre>
diff -Naur --exclude=CVS --exclude=".#*" --exclude="*~" --exclude='*.rej' --exclude='*.orig'
--exclude="*.bak" --exclude=conf.php --exclude=documents ancien_rep nouveau_rep > fichier.patch
</pre>
Envoyer votre patch sur la ML.
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:

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.

Au lieu de rechercher manuellement vos fichiers, si vous avez installé conjointement ''TortoiseCVS'' et ''Winmerge'', vous pouvez vous contenter de votre version modifiée sur votre ordinateur, et de la version CVS en ligne. Sous l'explorateur Windows, faites un clic droit sur le fichier qui doit être patché, et choisissez "CVS comparer" (pas WinMerge qui se trouve quelques lignes plus bas). Tortoise va lui-même lancer WinMerge. Puis reprenez la procédure décrite ci-dessus.

'''Appliquer un patch'''
Si votre patch n'a pas encore été appliqué, mais que vous souhaitez de votre coté l'appliquer sur votre serveur linux fraichement mis à jour depuis la CVS, cela est possible grâce à l'utilitaire patch.
En admettant que vous avez créé votre patch à partir du répertoire htdocs de votre copie locale du cvs modifiée par vos soins, et que vous avez envoyé votre patch (monfichier.patch) sur le serveur dans le dossier patchs situé au meme niveau que votre dossier htdocs distant, la commande suivante devrait faire l'affaire (executée depuis le dossier patchs):
patch -u -p0 -d ../htdocs < monfichier.patch
<nowiki>Pour information: -p0 permet d'utiliser le chemin entier tel que mentionné dans le fichier de patch (-pn en retire les n premiers niveau de l'arborescence)
-d permet de préciser le chemin relatif vers le dossier htdocs à patcher.
< permet de donner le chemin vers le fichier source à utiliser (le patch en mode unifié)
-u permet de préciser que le patch est en mode unifié</nowiki>

== Comment packager/livrer un module pour utilisation ==
Voir la page [[Developpement_module#Cr.C3.A9er_un_package_pour_livrer_et_installer_votre_module|Developpement moduel - Créer un package pour livrer et installer votre module]]

== 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 certains 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 CVS) 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 ces 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 familié 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'attendre ce but. Ne soyez donc pas offensé si, en tant que développeur, vous ne pouvez disposer d'un accès CVS en écriture avant un certain délai.

* '''Membre de l'alliance'''

La première chose qu'une personne désireuse d'aide doit faire et d'abord se familiariser avec les règles et normes de développements.
En lisant toute la [[Documentation Développeur]], vous faites preuve de volonté suffisante pour devenir automatiquement '''Membre''' de l'alliance Dolibarr (Votre grade est au niveau '''Membre'''). Et tout lire, c'est pas le plus facile...

Ce grade s'obtient sans validation supérieure.

* '''Chasseur de l'alliance'''

L'étape suivante consiste à soumettre des patch, en commençant par des simples, soit sur la Mailing List dev (voir [[FAQ_D%C3%A9veloppeur#Soumettre_un_patch.2C_am.C3.A9lioration_ou_participer_au_d.C3.A9veloppement|FAQ Développeur]] pour la procédure), soit sur le forum (Mailing List préférée).

A votre première soumission acceptée (incluse dans le CVS par un Amiral ou Jedi), vous entrez alors automatiquement dans la famille des '''Chasseurs''' de l'alliance Dolibarr.

Le nombre de chasseurs n'est pas limité. Plus, il y en aura, plus on sera fort.
Les chasseurs représentent la force vive principale de l'alliance Dolibarr.

* '''Amiral de l'alliance'''

Ce n'est qu'au bout d'un temps variable (qui peut être très long) au rang de Chasseur, et si la qualité des patch qui ont été envoyés est satisfaisante, qu'un Yoda en place vous offrira un accès CVS direct.
Vous êtes devenu un '''Amiral''' de l'alliance Dolibarr.

Ce titre ne se demande pas, il s'obtient par décision ou proposition d'un '''Jedi''' ou '''Yoda''' qui estime que vous avez soumis suffisamment de patch pour être un sérieux '''Amiral'''.
L'accès CVS d'un '''Amiral''' doit cependant n'être utilisé que pour commiter soit des traductions, soit des corrections de bugs déclarées sur Savannah ou le forum (que ces corrections soit personnelles ou issues d'un patch soumis par un '''Chasseur''').
Tout commit CVS doit ainsi obligatoirement inclure, dans la description (le champ log de commit), le numéro du bug Savannah corrigé OU le titre du message du forum signalant le problème. Seul une traduction échappe à cette contrainte (pas de restrictions pour les traductions). Le non respect de cette contrainte, peut provoquer une rétrogradation au rang de '''Chasseur'''.
Pour la soumission de nouvelles fonctionnalités, il faut donc obligatoirement continuer sur le principe de patchs envoyés sur la ML.

L'obtention du grade d'Amiral est toutefois rare car limité. La qualité de Dolibarr ne pouvant être atteinte que par un nombre d'Amiraux contrôlé, ce qui n'empêche pas d'avoir un nombre de
développeurs (Chasseurs) très important (grâce au système de patch).

* '''Jedi'''

C'est encore au bout d'un temps variable (sûrement le plus long de tous) au rang d'Amiral, et si la qualité des patch qui ont été envoyés est satisfaisante, qu'un Yoda vous signalera que vous êtes autorisé à réaliser des commits sans restrictions de fonctionnalités, à condition d'avoir cependant l'aval de principe d'un Maitre Yoda à qui vous aurez expliquer la fonctionnalité.
Il peut toutefois y avoir une restriction temporaire définie par un Yoda pour raison de release proche.
Vous êtes alors devenu un '''Jedi'''.

Ce titre ne se demande pas, il s'obtient par proposition d'un autre Jedi ou d'un Yoda.

Ce privilège est toutefois exceptionnel. La qualité de Dolibarr ne pouvant être atteinte
que par un nombre de Jedi contrôlé, ce qui n'empêche pas d'avoir un nombre de
développeurs (Chasseurs) très important (grâce au système de patch).

* '''Yoda'''

Au nombre de 1 à 5, être un '''Yoda''', c'est assurer la gestion globale du développement du projet. Ce rang s'obtient par succession, suite au départ d'un Yoda qui se retire, par nomination directe ou vote organisé par le Yoda partant.

...Et Dark Vador alors ?

Il existe. Dans la galaxie Dolibarr, on qualifie de Dark Vador, le parasite qui pollue 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 constructives qui aident à progresser. La mauvaise foi ou le mauvais ton est souvent de rigueur chez les Dark Vador...
Heureusement, statistiquement, on ne constate l'apparition et la mort que d'un seul Dark Vador par an environ...

Voir la page [[Le projet Dolibarr]] pour connaitre la liste des personnes à chaque grade actuellement.

Developer FAQ

2009-02-03T18:48:24Z

Mcg:

{{ToTranslate}}
{{TemplateDocDev}}

== Récupérer/mettre à jour une version CVS développeur ==
'''Effectuer une sauvegarde de ses données et de sa configuration'''

Si vous avez déjà une installation en place, sauvegarder votre fichier htdocs/conf/conf.php au cas ou.

'''Récupération dernière version des sources par download'''

Cette méthode permet de récupérer la version CVS de la branche de développement principale (appelée HEAD). L'opération consiste à récupérer la dernière version des fichiers de Dolibarr regroupés toutes les nuits dans un zip.
Pour cela, voir la [http://www.dolibarr.org/index.php?option=com_docman&task=cat_view&gid=64&&Itemid=36 version CVS du jour].
Les nouveaux fichiers doivent écraser les anciens.

'''Récupération dernière version des sources par CVS'''

Pour récupérer la dernière version en cours de développement, vous pouvez aussi directement utiliser [http://savannah.nongnu.org/cvs/?group=dolibarr le serveur CVS en mode anonyme], si vous disposez d'un client CVS (commande CVS sous Linux, ou TortoiseCVS par exemple sous Windows).

La commande permettant de récupérer un snapshot intégral (sans suivi cvs) dans le répertoire courant est:
''
CVSROOT=:pserver:anonymous@cvs.savannah.nongnu.org:/sources/dolibarr
export CVSROOT
cvs -q checkout -r HEAD -d ./ dolibarr/
''
HEAD signifie qu'on veut la dernière version de la version en cours de développement.

La commande permettant de mettre à jour localement une copie de travail CVS qui a déjà été rappatriée:
''Sous linux (script shell):
CVSROOT=:pserver:anonymous@cvs.savannah.nongnu.org:/sources/dolibarr
export CVSROOT
cvs -q update -P -d
Sous Windows avec Tortoise cvs
"C:\Program Files\CVSNT\cvs.exe" -q update -P -d
CVSROOT=:pserver:anonymous@cvs.savannah.nongnu.org:/sources/dolibarr''
Et pour remettre au propre votre copie locale en annulant vos modifications sur les fichiers intégrés au cvs:
"C:\Program Files\CVSNT\cvs.exe" -q update -P -C -d
CVSROOT=:pserver:anonymous@cvs.savannah.nongnu.org:/sources/dolibarr

Si besoin, modifiez les droits de propriétaire des dossiers, pour que le serveur y ait accès.

'''Récupération d'une autre branche par CVS'''

Si vous désirez une version particulière (avec ces patchs), il vous faut suivre la même procédure que ci-dessus mais en remplaçant HEAD par le nom de la branche.
Par exemple DOLIBARR_2_2_BRANCH pour la branche 2.2 ou DOLIBARR_2_4_BRANCH pour la branche 2.4.

'''Restaurer sa configuration'''

Restaurer le fichier de configuration (./htdocs/conf/conf.php) d'après sa sauvegarde si vous l'avez écrasé.

'''Mise a jour de la base'''

La deuxième étape consiste à migrer la base. Pour celà, il suffit d'appeler la page
http://maracinedolibarr/install/
et choisir l'option "Mise à jour".

Cette procédure de migration/mise à jour est conçue pour fonctionner quel que soit l'état de départ et peut être repassée plusieurs fois sans risque.

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

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

== Comment développer mon propre système de menu ==
Voir pour cela la page [[Système_de_menus]]

== Comment développer mon propre module ==
Voir pour cela la page [[Developpement_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:
<pre>
update llx_facture set facnumber=concat('FA',substr(facnumber,4,4),'-',substr(facnumber,8))
where facnumber like 'F%' and facnumber not like 'FA%';
</pre>

Par exemple, pour passer d'un modele FAYYMM999 à Terre (FAYYMM-999), vous pouvez exécuter la requête suivante:
<pre>
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 '%-%';
</pre>

== Soumettre un patch, amélioration ou participer au développement ==

* '''Avec accès CVS en écriture '''
A ce jour, les accès en écriture au CVS sont restreints (le nombre de commit étant déjà suffisamment dynamique). Si vous bénéficiez à l'heure actuelle d'un accès CVS en écriture, utilisez-le et à condition que ce qui est commité corresponde bien à votre grade de développeur Dolibarr (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 accès au CVS (vous êtes donc au grade de membre ou chasseur de l'alliance Dolibarr), il est nécessaire de suivre la procédure qui suit...

* '''Sans accès CVS en écriture'''
Sans accès CVS en écriture (sans compte développeur savannah), il est nécessaire de fournir par mail, votre fichier patch.

Sous tout OS:

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 CVS 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/component/option,com_docman/task,cat_view/gid,50/Itemid,36/lang,en/ site officiel de Dolibarr].

- 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] sous Windows) de la manière suivante:
<pre>
diff -Naur --exclude=CVS --exclude=".#*" --exclude="*~" --exclude='*.rej' --exclude='*.orig'
--exclude="*.bak" --exclude=conf.php --exclude=documents ancien_rep nouveau_rep > fichier.patch
</pre>
Envoyer votre patch sur la ML.
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:

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.

Au lieu de rechercher manuellement vos fichiers, si vous avez installé conjointement ''TortoiseCVS'' et ''Winmerge'', vous pouvez vous contenter de votre version modifiée sur votre ordinateur, et de la version CVS en ligne. Sous l'explorateur Windows, faites un clic droit sur le fichier qui doit être patché, et choisissez "CVS comparer" (pas WinMerge qui se trouve quelques lignes plus bas). Tortoise va lui-même lancer WinMerge. Puis reprenez la procédure décrite ci-dessus.

'''Appliquer un patch'''
Si votre patch n'a pas encore été appliqué, mais que vous souhaitez de votre coté l'appliquer sur votre serveur linux fraichement mis à jour depuis la CVS, cela est possible grâce à l'utilitaire patch.
En admettant que vous avez créé votre patch à partir du répertoire htdocs de votre copie locale du cvs modifiée par vos soins, et que vous avez envoyé votre patch (monfichier.patch) sur le serveur dans le dossier patchs situé au meme niveau que votre dossier htdocs distant, la commande suivante devrait faire l'affaire (executée depuis le dossier patchs):
patch -u -p0 -d ../htdocs < monfichier.patch
<nowiki>Pour information: -p0 permet d'utiliser le chemin entier tel que mentionné dans le fichier de patch (-pn en retire les n premiers niveau de l'arborescence)
-d permet de préciser le chemin relatif vers le dossier htdocs à patcher.
< permet de donner le chemin vers le fichier source à utiliser (le patch en mode unifié)
-u permet de préciser que le patch est en mode unifié</nowiki>

== Comment packager/livrer un module pour utilisation ==
Voir la page [[Developpement_module#Cr.C3.A9er_un_package_pour_livrer_et_installer_votre_module|Developpement moduel - Créer un package pour livrer et installer votre module]]

== 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 certains 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 CVS) 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 ces 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 familié 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'attendre ce but. Ne soyez donc pas offensé si, en tant que développeur, vous ne pouvez disposer d'un accès CVS en écriture avant un certain délai.

* '''Membre de l'alliance'''

La première chose qu'une personne désireuse d'aide doit faire et d'abord se familiariser avec les règles et normes de développements.
En lisant toute la [[Documentation Développeur]], vous faites preuve de volonté suffisante pour devenir automatiquement '''Membre''' de l'alliance Dolibarr (Votre grade est au niveau '''Membre'''). Et tout lire, c'est pas le plus facile...

Ce grade s'obtient sans validation supérieure.

* '''Chasseur de l'alliance'''

L'étape suivante consiste à soumettre des patch, en commençant par des simples, soit sur la Mailing List dev (voir [[FAQ_D%C3%A9veloppeur#Soumettre_un_patch.2C_am.C3.A9lioration_ou_participer_au_d.C3.A9veloppement|FAQ Développeur]] pour la procédure), soit sur le forum (Mailing List préférée).

A votre première soumission acceptée (incluse dans le CVS par un Amiral ou Jedi), vous entrez alors automatiquement dans la famille des '''Chasseurs''' de l'alliance Dolibarr.

Le nombre de chasseurs n'est pas limité. Plus, il y en aura, plus on sera fort.
Les chasseurs représentent la force vive principale de l'alliance Dolibarr.

* '''Amiral de l'alliance'''

Ce n'est qu'au bout d'un temps variable (qui peut être très long) au rang de Chasseur, et si la qualité des patch qui ont été envoyés est satisfaisante, qu'un Yoda en place vous offrira un accès CVS direct.
Vous êtes devenu un '''Amiral''' de l'alliance Dolibarr.

Ce titre ne se demande pas, il s'obtient par décision ou proposition d'un '''Jedi''' ou '''Yoda''' qui estime que vous avez soumis suffisamment de patch pour être un sérieux '''Amiral'''.
L'accès CVS d'un '''Amiral''' doit cependant n'être utilisé que pour commiter soit des traductions, soit des corrections de bugs déclarées sur Savannah ou le forum (que ces corrections soit personnelles ou issues d'un patch soumis par un '''Chasseur''').
Tout commit CVS doit ainsi obligatoirement inclure, dans la description (le champ log de commit), le numéro du bug Savannah corrigé OU le titre du message du forum signalant le problème. Seul une traduction échappe à cette contrainte (pas de restrictions pour les traductions). Le non respect de cette contrainte, peut provoquer une rétrogradation au rang de '''Chasseur'''.
Pour la soumission de nouvelles fonctionnalités, il faut donc obligatoirement continuer sur le principe de patchs envoyés sur la ML.

L'obtention du grade d'Amiral est toutefois rare car limité. La qualité de Dolibarr ne pouvant être atteinte que par un nombre d'Amiraux contrôlé, ce qui n'empêche pas d'avoir un nombre de
développeurs (Chasseurs) très important (grâce au système de patch).

* '''Jedi'''

C'est encore au bout d'un temps variable (sûrement le plus long de tous) au rang d'Amiral, et si la qualité des patch qui ont été envoyés est satisfaisante, qu'un Yoda vous signalera que vous êtes autorisé à réaliser des commits sans restrictions de fonctionnalités, à condition d'avoir cependant l'aval de principe d'un Maitre Yoda à qui vous aurez expliquer la fonctionnalité.
Il peut toutefois y avoir une restriction temporaire définie par un Yoda pour raison de release proche.
Vous êtes alors devenu un '''Jedi'''.

Ce titre ne se demande pas, il s'obtient par proposition d'un autre Jedi ou d'un Yoda.

Ce privilège est toutefois exceptionnel. La qualité de Dolibarr ne pouvant être atteinte
que par un nombre de Jedi contrôlé, ce qui n'empêche pas d'avoir un nombre de
développeurs (Chasseurs) très important (grâce au système de patch).

* '''Yoda'''

Au nombre de 1 à 5, être un '''Yoda''', c'est assurer la gestion globale du développement du projet. Ce rang s'obtient par succession, suite au départ d'un Yoda qui se retire, par nomination directe ou vote organisé par le Yoda partant.

...Et Dark Vador alors ?

Il existe. Dans la galaxie Dolibarr, on qualifie de Dark Vador, le parasite qui pollue 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 constructives qui aident à progresser. La mauvaise foi ou le mauvais ton est souvent de rigueur chez les Dark Vador...
Heureusement, statistiquement, on ne constate l'apparition et la mort que d'un seul Dark Vador par an environ...

Voir la page [[Le projet Dolibarr]] pour connaitre la liste des personnes à chaque grade actuellement.