Dolibarr : comment réussir personnalisation pour réduire les erreurs

Par [Votre Nom] – Expert Dolibarr
Date : 3 novembre 2025

1. Introduction

Dolibarr est un ERP/PGI open‑source particulièrement apprécié pour sa simplicité d’utilisation et sa souplesse d’adaptation.
Cependant, lorsqu’on commence à personnaliser le système (ajout de champs, modification de modèles, automatisation de processus…), les risques d’erreurs augmentent : incohérences de données, conflits de versions, pertes de fonctionnalité, etc.

Cet article passe en revue les bonnes pratiques à suivre pour personnaliser Dolibarr tout en limitant les erreurs fréquentes. Il s’adresse aux administrateurs, développeurs et chefs de projet qui souhaitent garder le contrôle sur leurs adaptations.

2. Principes de base de la personnalisation Dolibarr

Concept Description Pourquoi c’est important
Extension plutôt que modification directe Créez des modules/plugins ou des surcharges de classes plutôt que d’éditer le code du cœur. Garantit que les mises à jour de Dolibarr ne seront pas écrasées.
Utilisation du système de hooks Dolibarr propose des hooks (événements) pour intercepter des points clés (ex. : avant sauvegarde, après génération de facture). Permet d’ajouter du code sans toucher aux fichiers originaux.
Sépare­ment les données de configuration Utilisez les fichiers de configuration (conf/, src/…) pour stocker les paramètres personnalisés. Facilite le débogage et la restauration en cas d’erreur.
Versionnage et tests Placez chaque adaptation dans un dépôt Git et créez des scénarios de test automatisés. Permet de détecter les régressions dès le premier déclenchement.
Documentation interne Rédigez un README ou un wiki décrivant la logique de chaque surcharge. Simplifie la transmission du projet et la remontée d’éventuels bugs.

3. Étapes clés d’une personnalisation sans surprise

3.1. Analyse des besoins et modélisation

  1. Recenser le processus métier : dessinez les flux (ex. : demande d’achat → commande → facturation).

  2. Identifier les points de friction : où les utilisateurs rencontrent-ils des erreurs ou des étapes fastidieuses ?

  3. Définir les objets à modifier : champs supplémentaires, états de workflow, tableaux de bord, etc.

Astuce : Utilisez un tableau (ou un diagramme BPMN) pour visualiser chaque étape et y lier les modules Dolibarr concernés.

3.2. Choix de la méthode de personnalisation

Besoin Méthode recommandée
Ajout d’un champ texte ou numérique Champ personnalisé via fields dans le tableau llx_ ou via le formulaire form.php.
Calcul automatisé (TVA, remise, stock) Hook hookForm / hookHeader ou Plugin qui écoute prodfamilies_get_father ou invoiceprice_get_price.
Modification d’un email de notification Hook email (sendmail) ou Template override (email_client / mailings).
Déviation du statut d’une entité (ex. : passer de « En cours » à « Validé » automatiquement) Hook changeState ou Plugin implémentant changeState dans la classe concernée.

3.3. Mise en place du code

  1. Créer le répertoire du plugin : 
    my_plugin/
    
├─ my_plugin.php           <-- fichier principal
    
├─ manifest.php            <-- métadonnées (version, author, etc.)
    
└─ hooks/
    
   ├─ my_hook_file.php

  2. Déclarer le manifeste (manifest.php) : 
    <?php
    
$mn->name = 'My Plugin – Customisation sans erreur';
    
$mn->version = '1.0.0';
    
$mn->author = 'Votre Nom';
    
$mn->rights = '0';
    
$mn->description = 'Exemple de plugin avec hooks pour éviter les erreurs courantes.';
    
$mn->need = array('user' => '1.0.0'); // version minimale de Dolibarr
    
$mn->scripts = array('js/my_plugin.js');
    
$mn->fields = array(
    
   // champs supplémentaires
    
   'my_field' => array('type'=>'varchar(255)','label'=>'Champ personnalisé','value'=>0)
    
);
    
$mn->hooks = array(
    
   'formpreview' => 'my_hook_file.php'   // écoute l'événement de prévisualisation du formulaire
    
);

  3. Implémenter le hook : 
    <?php
    
if (!defined('DOCTYPE')) die('Access denied');
    
function my_plugin_formpreview($hookname,$module,$ref,$output) {
    
   // Ajoute dynamiquement un champ prérempli pour éviter la saisie manuelle d'une valeur critique
    
   $output .= '<input type="hidden" name="my_field" value="'.dol_htmlentities($ref->my_field).'">';
    
   return $output;
    
}

  4. Activer le plugin depuis l’interface Extensions → Modules.

Bonne pratique : Commencez par un plugin vide qui ne fait qu’enregistrer votre présence. Testez l’activation, puis ajoutez progressivement les hooks nécessaires.

3.4. Tests unitaires et fonctionnels

Type de test Outils / Méthodes
Tests unitaires PHPUnit (exécuter phpunit dans le répertoire du plugin).
Tests d’intégration Scripts Bash/PowerShell qui automatisent le remplissage du formulaire via l’API REST de Dolibarr (/hrir/rest/).
Tests de charge JMeter ou Locust pour s’assurer que les nouveaux hooks n’engendrent pas de latence importante.
Tests de non‑regression Capture d’écran des écrans clés et comparaison avec une baseline (ex. : diff sur le HTML généré).

Tip : Utilisez le mode debug de Dolibarr ($conf->global->debug = 1;) pour obtenir des traces détaillées dès qu’une erreur survient.

3.5. Réduction des erreurs courantes

Erreur fréquente Solution préventive
Conflit de noms (fonction, classe) Prefixer toutes vos fonctions/classes avec le nom du plugin (my_plugin_).
Perte de données après mise à jour Ne jamais modifier les tables du cœur (llx_…). Utilisez des tables dédiées (my_plugin_…) ou un plugin de sauvegarde ($db->execute("ALTER TABLE …")).
Échec de validation de formulaire Toujours revenir à $output via le hook formpreprocess plutôt que d’appeler dol_print.'directement`.
État inattendu dans le workflow Utilisez les fonctions de gestion d’état : changeState($object, $new_state, $message).
Débordement de champs (SQL injection) Toujours passer les valeurs via les méthodes du DB ($this->db->prepare(…)) ou les fonctions addEvent, add_categorie qui escapent les données.
Bug d’affichage dans le thème Utiliser les templates override (theme/mytheme/tpl/...) plutôt que de modifier les fichiers du thème principal.

4. Bonnes pratiques pour maintenir la personnalisation sans régressions

  1. Gestion de version rigoureuse

    • Taguer chaque version du plugin (v1.0.0, v1.1.0).

    • Documenter les changements dans un fichier CHANGELOG.md.

  2. Utilisation d’un environnement de pré‑production

    • Clonez votre base de données et exécutez les mises à jour sur un serveur de test avant le déploiement.

  3. Séparer les jeux de données

    • Stockez les données de référence (ex. : listes de clients, tarifs) dans des fichiers CSV importables via l’interface Import/Export.

  4. Plan de rollback

    • Gardez toujours la version précédente du plugin dans le dépôt Git.

    • Créez un script rollback.php qui remet les tables à leur état initial.

  5. Codestylepartage

    • Respectez le PSR‑2 (ou le standard déjà adopté par Dolibarr).

    • Utilisez des outils comme PHPCS pour automatiser la vérification.

  6. Documentation vivante

    • Décrivez chaque hook utilisé dans le README (usage, parameters, return).

    • Ajoutez des exemples de code pour les cas d’usage les plus fréquents.

5. Exemples concrets

5.1. Ajouter un champ « Numéro de projet interne » à la fiche fournisseur

// Dans my_plugin.php – manifest

$mn->fields = array(

    'supplier_myproj' => array(

        'type' => 'varchar(255)',

        'label' => 'Numéro de projet interne',

        'entity' => 'supplier'

    )

);
// Dans le hook qui se déclenche lors du formulaire fournisseur

function my_plugin_add_supplier_field(&$output) {

    global $conf;

    $output .= '<input type="hidden" name="supplier_myproj" value="'.$_REQUEST['supplier_myproj'].'">';

    return $output;

}

5.2. Calcul automatique de la TVA lors de la création d’une facture

function my_plugin_invoice_price_prepare($hookname, $module, $object, $params) {

    // $object est une facture en cours de création

    $rate = 20; // 20% par défaut

    $priceHT = $object->total;

    $tax   = ($priceHT * $rate) / 100;

    $object->total_tax = $tax;

    $object->total_ttc = $priceHT + $tax;

    return $params; // pas de modification du flux

}

5.3. Redirection automatique vers un tableau de bord après validation d’une commande

function my_plugin_after_save_order($hookname, $module, $object) {

    // $object est la commande créée ou mise à jour

    if ($object->status == 2) { // 2 = "Validée"

        dol_redirect('/my_plugin/board.php');

        exit;

    }

    return;

}

6. Checklist de pré‑déploiement

✔️ Item Description
Code Pas de fonctions réservées ($_GET, $_POST) directement, tout passe par les API Dolibarr.
Sécurité Tous les champs accessibles depuis l’interface sont protégés avec check_multiperm() ou allow_continueinline().
Tests 100 % des hooks ajoutés passent les tests unitaires.
Performance Temps de réponse < 200 ms sur les principaux écrans (mesuré à l’aide de microtime()).
Backup Script de sauvegarde de la base avant le lancement.
Rollback Script rollback.php fonctionnel et testé.
Documentation README à jour, inclusion d’un exemple d’utilisation.
Versioning Tag Git créé et version passée dans le manifeste.

7. Conclusion

La personnalisation de Dolibarr permet d’adapter l’outil aux processus métiers spécifiques, mais elle requiert une approche méthodologique stricte afin de minimiser les erreurs. En suivant les principes présentés :

  1. Travailler par extension (plugins, hooks) plutôt que par modification directe du cœur.

  2. Modéliser soigneusement chaque besoin avant de coder.

  3. Isoler les changements dans des tables ou des fichiers dédiés.

  4. Tester à chaque itération (unitaires, intégration, charge).

  5. Documenter et versionner chaque adaptation.

Vous obtiendrez un système stable, maintenable et évolutif, capable de s’adapter aux futures évolutions de Dolibarr sans engendrer de régressions ni de bugs récurrents.

« La meilleure façon d’éviter les erreurs, c’est de les prévoir et de les tester avant qu’elles n’atteignent la production. »

Bonne personnalisation ! 🚀

Sources : Documentation officielle de Dolibarr (v. 23.x), forums Dolibarr, bonnes pratiques du projet open‑source (GitHub / GitLab).

Publications similaires