Créer un module Dolibarr personnalisé : tutoriel pas à pas
Vous voulez étendre Dolibarr sans toucher au cœur du logiciel ? Suivez ce tutoriel complet pour créer votre propre module, de l'activation du Module Builder jusqu'au premier objet métier enregistré en base de données.
Développement · Dolibarr · PHP • Niveau intermédiaire
Sommaire
1. Pourquoi créer un module Dolibarr personnalisé ?
2. Les prérequis avant de commencer
3. Comprendre l'architecture d'un module
4. Étape 1 : Activer le Module Builder
5. Étape 2 : Générer le squelette du module
6. Étape 3 : Personnaliser le descripteur
7. Étape 4 : Définir les permissions
8. Étape 5 : Ajouter une entrée de menu
9. Étape 6 : Créer un objet métier et sa table
10. Étape 7 : Gérer les traductions
11. Étape 8 : Activer et tester le module
12. Aller plus loin : hooks, déclencheurs et API
13. Bonnes pratiques de développement
14. Déboguer et résoudre les problèmes courants
Dolibarr doit une grande partie de son succès à son architecture modulaire. Plutôt que d'imposer un bloc monolithique, il propose des dizaines de modules que l'on active ou désactive à la demande. Et surtout, il laisse aux développeurs la possibilité d'écrire les leurs. C'est la clé pour adapter l'ERP à des besoins métier très spécifiques, sans jamais modifier le code source d'origine — ce qui garantit des mises à jour sereines.
Dans ce tutoriel pas à pas, vous allez apprendre à créer un module Dolibarr personnalisé de A à Z. Nous nous appuierons sur le Module Builder, l'outil de génération de code intégré à Dolibarr, qui automatise une grande partie du travail fastidieux. À la fin, vous disposerez d'un module fonctionnel, avec son propre menu, ses permissions, un objet métier relié à une table en base de données, et ses traductions.
Ce guide s'adresse à des développeurs ayant des bases en PHP. Pas besoin d'être un expert : nous expliquons chaque concept au fur et à mesure. Prenez votre éditeur de code préféré, lancez votre Dolibarr de développement, et c'est parti.
Pourquoi créer un module Dolibarr personnalisé ?
Avant d'écrire la moindre ligne de code, il est utile de comprendre ce qu'un module vous permet réellement de faire. Un module Dolibarr n'est pas un simple script : c'est une extension à part entière, capable de s'intégrer en profondeur dans l'application.
Concrètement, un module personnalisé peut ajouter de nouvelles tables en base de données, créer ses propres écrans de saisie, insérer des entrées de menu, ajouter des onglets sur les fiches existantes (factures, produits, tiers…), définir de nouvelles permissions, exécuter du code automatiquement lors d'événements grâce aux déclencheurs, ou encore s'injecter dans le code existant via les hooks.
L'avantage majeur tient en une phrase : vous étendez Dolibarr sans toucher au noyau. Vos développements vivent dans un répertoire séparé et survivent aux montées de version. C'est la différence fondamentale entre un module propre et une bidouille dans le code source, qui sauterait à la première mise à jour.
Les prérequis avant de commencer
Un environnement bien préparé vous évitera bien des frustrations. Voici ce dont vous avez besoin.
Les connaissances de base
Une bonne maîtrise de PHP est indispensable, ainsi que des notions de SQL pour les tables de données et un peu de HTML/CSS pour les écrans. La connaissance de l'orienté objet est un plus, car les objets métier de Dolibarr reposent sur des classes.
L'environnement de développement
Installez une instance de Dolibarr dédiée au développement, distincte de votre production. Munissez-vous d'un éditeur de code confortable comme Visual Studio Code ou PhpStorm, et vérifiez que les extensions PHP courantes (pdo, gd, intl…) sont bien présentes sur votre serveur.
Activer le mode développeur
Le Module Builder n'apparaît qu'en mode développeur. Ouvrez votre fichier htdocs/conf/conf.php et passez l'application hors production en ajoutant ou en modifiant cette ligne :
$dolibarr_main_prod = 0;
Pensez à régler le niveau de fonctionnalités sur « développeur » dans la configuration de l'affichage, afin de débloquer les outils avancés. Une fois ces réglages en place, les fonctions de développement deviennent accessibles.
Important : ne travaillez jamais directement sur votre Dolibarr de production. Le mode développeur affiche des informations sensibles et active des outils qui n'ont rien à faire sur un site en exploitation. Réservez ces réglages à un environnement de test.
Comprendre l'architecture d'un module
Un module Dolibarr suit une structure de fichiers bien définie. La connaître vous aidera à vous repérer dans le code généré et à savoir où ajouter vos développements.
L'arborescence des fichiers
Un module externe se place dans le répertoire htdocs/custom/. Voici à quoi ressemble l'arborescence type d'un module nommé monmodule :
htdocs/custom/monmodule/
├── core/
│ └── modules/
│ └── modMonModule.class.php (le descripteur)
├── class/ (les objets métier - classes CRUD)
├── sql/ (les scripts de création des tables)
├── admin/ (la page de configuration)
├── lib/ (les fonctions utilitaires)
├── langs/ (les fichiers de traduction)
│ └── fr_FR/
└── monmodule_index.php (la page principale)
Le fichier descripteur, pièce maîtresse
Le fichier modMonModule.class.php, rangé dans core/modules/, est le cerveau du module. C'est lui que Dolibarr lit pour savoir comment s'appelle votre module, ce qu'il fait, quelles permissions il déclare, quels menus il ajoute et quelles tables il installe. Il étend la classe DolibarrModules. Sans ce fichier, Dolibarr ne reconnaît tout simplement pas votre module.
Étape 1 : Activer le Module Builder
Depuis la version 9 de Dolibarr, la méthode recommandée pour créer un module est d'utiliser le Module Builder, livré en standard. Rendez-vous dans Accueil → Configuration → Modules/Applications, recherchez « Module Builder » dans la liste et activez-le.
Une fois activé, une nouvelle icône (souvent représentée par un petit insecte ou un engrenage) apparaît en haut à droite de l'écran. Elle ouvre l'interface du Module Builder, accessible techniquement à l'adresse de l'outil de génération. C'est depuis cette interface que toute la magie va opérer.
Étape 2 : Générer le squelette du module
Dans l'interface du Module Builder, cliquez sur le bouton de création d'un nouveau module. Une fenêtre vous demande quelques informations de base : le nom du module (par exemple MonModule), sa famille, sa description et son éditeur.
Validez, et le Module Builder fait le plus gros du travail : il copie les fichiers du modèle situé dans htdocs/modulebuilder/template, effectue les remplacements de chaînes nécessaires, et crée l'arborescence complète de votre module dans htdocs/custom/monmodule/. En quelques secondes, vous obtenez un module valide, vide mais immédiatement reconnu par Dolibarr.
Astuce : le Module Builder génère un fichier modulebuilder.txt à la racine du module. Ne le supprimez pas tant que vous développez : c'est lui qui permet à l'outil de continuer à éditer le module via l'interface graphique. Vous le retirerez seulement au moment de la distribution finale.
Étape 3 : Personnaliser le descripteur
Ouvrez le descripteur généré dans votre éditeur. Vous y trouverez de nombreuses propriétés à ajuster. Voici les plus importantes, telles qu'elles apparaissent dans le constructeur de la classe :
public function __construct($db)
{
$this->db = $db;
$this->numero = 500000; // identifiant unique du module
$this->rights_class = 'monmodule'; // préfixe des permissions
$this->family = 'other'; // famille d'affichage
$this->name = 'MonModule';
$this->description = 'Gestion personnalisée pour mon activité';
$this->version = '1.0';
$this->picto = 'generic'; // icône du module
}
Le point de vigilance principal concerne le numero, qui doit être unique pour éviter tout conflit avec un autre module. Le Module Builder attribue généralement un identifiant aléatoire dans une plage réservée aux modules externes. Évitez de le modifier au hasard. La propriété version sert au suivi des mises à jour, et description s'affiche dans la liste des modules.
Étape 4 : Définir les permissions
Les permissions contrôlent qui peut faire quoi dans votre module. Elles se déclarent dans le tableau des droits du descripteur. Chaque entrée définit un identifiant, un libellé et le type d'action concernée (lire, créer, supprimer…).
$this->rights = array();
$r = 0;
$this->rights[$r][0] = 500001; // id unique de la permission
$this->rights[$r][1] = 'Lire les enregistrements';
$this->rights[$r][4] = 'read';
$r++;
$this->rights[$r][0] = 500002;
$this->rights[$r][1] = 'Créer ou modifier';
$this->rights[$r][4] = 'write';
À l'activation du module, ces droits sont automatiquement enregistrés dans la table llx_rights_def. Vous pourrez ensuite les attribuer à vos utilisateurs et groupes depuis l'interface d'administration habituelle. Pensez à vérifier ces permissions dans votre code à chaque action sensible : c'est une bonne pratique de sécurité élémentaire.
Étape 5 : Ajouter une entrée de menu
Pour que votre module soit accessible, il lui faut au moins une entrée de menu. Celle-ci se déclare dans le tableau des menus du descripteur. On précise le type de menu (gauche ou haut), son titre, l'URL cible et la permission requise pour l'afficher.
$this->menu[$r++] = array(
'fk_menu' => 'fk_mainmenu=monmodule',
'type' => 'left',
'titre' => 'Liste des éléments',
'url' => '/custom/monmodule/monmodule_list.php',
'langs' => 'monmodule@monmodule',
'perms' => '$user->rights->monmodule->read',
'position' => 100,
);
Le champ des permissions garantit que seuls les utilisateurs habilités voient l'entrée de menu. Une fois le module réactivé, votre menu apparaît dans la barre latérale, prêt à pointer vers vos écrans.
Étape 6 : Créer un objet métier et sa table
C'est le cœur d'un module qui manipule des données. Le Module Builder permet d'ajouter un « objet » en quelques clics, depuis l'onglet dédié de son interface. Vous définissez le nom de l'objet et la liste de ses champs (texte, nombre, date, lien vers un autre objet…).
À partir de cette définition, l'outil génère plusieurs fichiers d'un coup : la classe DAO/CRUD dans le dossier class/ (avec les méthodes prêtes à l'emploi pour créer, lire, mettre à jour et supprimer un enregistrement), le script SQL de création de la table dans sql/, ainsi que les pages de liste et de fiche. C'est un gain de temps considérable.
Le script SQL généré ressemble à ceci, avec les colonnes correspondant à vos champs :
CREATE TABLE llx_monmodule_element (
rowid INTEGER AUTO_INCREMENT PRIMARY KEY,
ref VARCHAR(128) NOT NULL,
label VARCHAR(255),
datec DATETIME,
fk_user_creat INTEGER,
status INTEGER DEFAULT 0
) ENGINE=innodb;
À retenir : toutes les tables d'un module Dolibarr sont préfixées par llx_ (ou le préfixe défini à l'installation). Respectez cette convention : elle évite les collisions de noms et garantit la cohérence avec le reste de la base.
Étape 7 : Gérer les traductions
Dolibarr est multilingue, et votre module doit l'être aussi. Les libellés se stockent dans des fichiers de langue placés dans langs/fr_FR/. Chaque fichier associe une clé à un texte traduit, sous forme de paires clé = valeur :
# fichier langs/fr_FR/monmodule.lang
ModuleMonModuleName = Mon Module
ModuleMonModuleDesc = Gestion personnalisée pour mon activité
MonModuleList = Liste des éléments
NewElement = Nouvel élément
Dans votre code, vous n'affichez jamais le texte en dur : vous appelez la clé de traduction. Dolibarr se charge alors d'afficher la bonne langue selon les préférences de l'utilisateur. Pensez à créer au minimum les fichiers en français et en anglais pour une diffusion plus large.
Étape 8 : Activer et tester le module
Le moment de vérité. Rendez-vous dans la liste des modules de Dolibarr : votre module y figure désormais. Activez-le. À cet instant, Dolibarr exécute les scripts SQL, crée les tables, enregistre les permissions et installe les menus.
Parcourez ensuite votre nouvelle entrée de menu, créez un premier enregistrement, modifiez-le, supprimez-le. Vérifiez que les données apparaissent bien en base. Si quelque chose cloche, le mode développeur et les journaux de Dolibarr sont vos meilleurs alliés pour diagnostiquer le problème.
Conseil de débogage : en cas d'erreur après une modification du descripteur, désactivez puis réactivez le module pour forcer Dolibarr à relire la configuration et à rejouer les scripts d'installation. Beaucoup de soucis se règlent par ce simple aller-retour.
Aller plus loin : hooks, déclencheurs et API
Une fois les bases acquises, Dolibarr offre des mécanismes puissants pour intégrer votre module en profondeur.
Les hooks
Les hooks sont des points d'injection qui permettent d'ajouter ou de remplacer du code à des endroits précis de Dolibarr, sans modifier le noyau. Vous déclarez les contextes qui vous intéressent dans la propriété module_parts du descripteur :
$this->module_parts = array(
'hooks' => array('invoicecard', 'thirdpartycard')
);
Vous écrivez ensuite une classe de hook dont les méthodes seront appelées automatiquement lorsque Dolibarr atteint ces contextes. C'est idéal pour enrichir des écrans existants avec vos propres informations.
Les déclencheurs (triggers)
Les déclencheurs exécutent du code en réaction à un événement métier : la validation d'une facture, la création d'un tiers, la suppression d'un produit… Votre module peut ainsi réagir automatiquement, par exemple pour synchroniser une donnée avec un système externe ou envoyer une notification.
L'API REST
Si votre objet métier doit être accessible depuis l'extérieur, le Module Builder peut générer une API REST dédiée. Vous exposez ainsi vos données à d'autres applications, dans le respect des permissions définies. C'est un atout majeur pour connecter Dolibarr à votre écosystème logiciel.
Bonnes pratiques de développement
Quelques principes vous éviteront bien des écueils et faciliteront la maintenance de votre module dans le temps :
• Ne modifiez jamais le noyau. Tout votre code reste dans le répertoire custom. C'est la garantie de mises à jour sans douleur.
• Vérifiez les permissions partout. Avant chaque action sensible, contrôlez que l'utilisateur dispose bien du droit correspondant.
• Échappez les données. Nettoyez systématiquement les entrées utilisateur pour prévenir les injections SQL et les failles XSS.
• Versionnez votre code. Utilisez Git dès le départ pour suivre vos modifications et collaborer sereinement.
• Documentez et traduisez. Des libellés clairs et des fichiers de langue complets rendent votre module utilisable par d'autres.
• Testez avant de distribuer. Activez et désactivez votre module sur une instance propre pour valider l'installation et la désinstallation.
Déboguer et résoudre les problèmes courants
Même en suivant scrupuleusement chaque étape, vous rencontrerez tôt ou tard un comportement inattendu. Voici comment garder la main et diagnostiquer efficacement les soucis les plus fréquents.
Premier réflexe : activez les journaux de Dolibarr. En mode développeur, vous pouvez relever le niveau de détail des logs pour voir précisément ce que fait l'application. La plupart des erreurs y laissent une trace explicite, bien plus utile qu'un écran blanc. Pensez aussi à consulter le journal d'erreurs de PHP, qui capture les anomalies non gérées.
Un module qui n'apparaît pas dans la liste signale presque toujours un problème dans le descripteur : une erreur de syntaxe PHP, un nom de classe qui ne correspond pas au nom du fichier, ou un mauvais emplacement dans l'arborescence. Vérifiez que le fichier se nomme bien selon la convention attendue et qu'il se trouve dans le bon sous-répertoire.
Si vos tables ne sont pas créées à l'activation, contrôlez vos scripts SQL : un point-virgule manquant ou une syntaxe non compatible avec votre base suffit à bloquer l'installation. Désactivez puis réactivez le module pour relancer la procédure une fois la correction apportée.
Bonne habitude : travaillez par petites itérations. Modifiez une seule chose à la fois, puis testez. Quand quelque chose casse, vous savez immédiatement quelle modification est en cause — alors qu'un gros lot de changements rend le diagnostic bien plus pénible.
Questions fréquentes
Faut-il obligatoirement utiliser le Module Builder ?
Non, vous pouvez tout écrire à la main en copiant le modèle de descripteur. Mais depuis Dolibarr 9, le Module Builder est la méthode recommandée : il génère un code propre et conforme, vous fait gagner un temps précieux et limite les erreurs. Rien ne vous empêche ensuite d'éditer manuellement les fichiers générés.
Où placer mon module : dans custom ou à la racine ?
Pour un module externe, placez-le toujours dans htdocs/custom/. L'emplacement à la racine est réservé aux modules destinés à devenir des modules officiels du cœur de Dolibarr. Le répertoire custom garantit la séparation avec le noyau.
Mon module survivra-t-il aux mises à jour de Dolibarr ?
Oui, tant que vous respectez la règle d'or : ne jamais modifier le code du noyau. Comme votre module vit dans son propre répertoire et utilise les mécanismes officiels (hooks, déclencheurs, descripteur), il reste compatible à travers les montées de version, sous réserve de suivre l'évolution des API.
Puis-je distribuer ou vendre mon module ?
Tout à fait. De nombreux modules tiers, gratuits ou payants, sont proposés sur la place de marché officielle. Veillez simplement à respecter la licence de Dolibarr et à fournir une documentation claire ainsi que les traductions nécessaires.
Conclusion
Créer un module Dolibarr personnalisé n'a rien d'insurmontable. Grâce au Module Builder, l'essentiel du squelette se génère en quelques clics, et il ne vous reste qu'à personnaliser le descripteur, déclarer vos permissions et vos menus, puis définir vos objets métier. En suivant les étapes de ce tutoriel, vous disposez désormais d'une base solide pour bâtir des extensions sur mesure.
La force de cette approche, c'est qu'elle respecte le logiciel : tout votre travail reste isolé dans le répertoire custom, à l'abri des mises à jour. Vous adaptez Dolibarr à vos besoins les plus pointus sans jamais compromettre sa pérennité.
La meilleure façon de progresser, maintenant, c'est de pratiquer. Lancez votre environnement de développement, générez un premier module, ajoutez-lui un objet et un menu, et explorez peu à peu les hooks, les déclencheurs et l'API. Chaque module que vous construirez vous rendra plus à l'aise avec l'architecture de Dolibarr — et ouvrira la porte à des possibilités quasi infinies.