Creazione di un modulo Dolibarr personalizzato: tutorial passo passo
Vuoi estendere Dolibarr senza modificare il codice sorgente del software? Segui questo tutorial completo per creare il tuo modulo, dall'attivazione del Module Builder al salvataggio del primo oggetto aziendale nel database.
Sviluppo · Dolibarr · PHP • Livello intermedio
Riepilogo
1. Perché creare un modulo Dolibarr personalizzato?
2. Prerequisiti prima di iniziare
3. Comprendere l'architettura di un modulo
4. Passaggio 1: Attivare il Generatore di moduli
5. Fase 2: Generare lo scheletro del modulo
6. Passaggio 3: Personalizza il descrittore
7. Fase 4: Definire le autorizzazioni
8. Passaggio 5: Aggiungere una voce di menu
9. Passaggio 6: Creare un oggetto aziendale e la relativa tabella
10. Passaggio 7: Gestire le traduzioni
11. Fase 8: Attivare e testare il modulo
12. Andando oltre: hook, trigger e API
13. Buone pratiche di sviluppo
14. Eseguire il debug e risolvere i problemi comuni
Il successo di Dolibarr è in gran parte dovuto alla sua architettura modulare. Anziché imporre un blocco monolitico, offre decine di moduli che possono essere attivati o disattivati a seconda delle necessità. E soprattutto, permette agli sviluppatori di crearne di propri. Questa è la chiave per adattare l'ERP a esigenze aziendali molto specifiche senza mai modificare il codice sorgente originale, garantendo aggiornamenti senza interruzioni.
In questo tutorial passo passo, imparerai come creare un modulo Dolibarr personalizzato da zero. Useremo il Module Builder , lo strumento di generazione del codice integrato in Dolibarr, che automatizza gran parte del lavoro più noioso. Al termine, avrai un modulo completamente funzionante con il suo menu, i permessi, un oggetto business collegato a una tabella del database e le traduzioni.
Questa guida è pensata per sviluppatori con una conoscenza di base di PHP. Non è necessario essere esperti: spiegheremo ogni concetto passo dopo passo. Apri il tuo editor di codice preferito, avvia l'ambiente di sviluppo Dolibarr e iniziamo.
Perché creare un modulo Dolibarr personalizzato?
Prima di scrivere una sola riga di codice, è utile capire cosa permette effettivamente di fare un modulo. Un modulo Dolibarr non è un semplice script: è un'estensione a tutti gli effetti, in grado di integrarsi profondamente nell'applicazione.
In termini concreti, un modulo personalizzato può aggiungere nuove tabelle al database, creare le proprie schermate di input, inserire voci di menu, aggiungere schede ai record esistenti (fatture, prodotti, terze parti...), definire nuove autorizzazioni, eseguire codice automaticamente in risposta a eventi tramite trigger o persino integrarsi nel codice esistente tramite hook.
Il vantaggio principale si può riassumere in una frase: si estende Dolibarr senza toccare il codice sorgente . Le modifiche apportate risiedono in una directory separata e permangono anche dopo gli aggiornamenti di versione. Questa è la differenza fondamentale tra un modulo pulito e una modifica al codice sorgente, che andrebbe persa al primo aggiornamento.
Prerequisiti prima di iniziare
Un ambiente ben preparato vi risparmierà molta frustrazione. Ecco cosa vi serve.
Conoscenze di base
È fondamentale una solida conoscenza di PHP, nonché di SQL per le tabelle dati e di HTML/CSS per le schermate. La conoscenza della programmazione orientata agli oggetti è un vantaggio, poiché gli oggetti di business di Dolibarr sono basati sulle classi.
L'ambiente di sviluppo
Installa un'istanza dedicata di Dolibarr per lo sviluppo, separata dall'ambiente di produzione. Utilizza un editor di codice intuitivo come Visual Studio Code o PhpStorm e assicurati che le estensioni PHP più comuni (pdo, gd, intl, ecc.) siano installate sul tuo server.
Abilita la modalità sviluppatore
Il Generatore di moduli appare solo in modalità sviluppatore. Apri il file htdocs/conf/conf.php e disattiva la modalità di produzione dell'applicazione aggiungendo o modificando questa riga:
$dolibarr_main_prod = 0;
Ricorda di impostare il livello di funzionalità su "sviluppatore" nelle impostazioni di visualizzazione per sbloccare gli strumenti avanzati. Una volta configurate queste impostazioni, le funzioni di sviluppo saranno accessibili.
Importante: non lavorare mai direttamente sul tuo Dolibarr di produzione. La modalità sviluppatore visualizza informazioni sensibili e attiva strumenti che non hanno posto su un sito attivo. Riserva queste impostazioni a un ambiente di test.
Comprendere l'architettura di un modulo
Un modulo Dolibarr segue una struttura di file ben definita. Comprendere questa struttura ti aiuterà a orientarti nel codice generato e a sapere dove aggiungere le tue personalizzazioni.
La struttura ad albero dei file
Un modulo esterno viene posizionato nella directory htdocs/custom/ . Ecco come si presenta la tipica struttura di directory di un modulo chiamato mymodule :
htdocs/custom/mymodule/
├── core/
│ └── modules/
│ └── modMyModule.class.php (il descrittore)
├── class/ (oggetti di business - classi CRUD)
├── sql/ (script per la creazione di tabelle)
├── admin/ (la pagina di configurazione)
├── lib/ (funzioni di utilità)
├── langs/ (file di traduzione)
│ └── fr_FR/
└── mymodule_index.php (la pagina principale)
Il file descrittore, il componente chiave
Il file modMonModule.class.php , situato in core/modules/ , è il cuore del modulo. Dolibarr legge questo file per determinare il nome del modulo, la sua funzione, i permessi, i menu che aggiunge e le tabelle che installa. Estende la classe DolibarrModules . Senza questo file, Dolibarr semplicemente non riconoscerà il modulo.
Passaggio 1: Attiva il Generatore di moduli
Dalla versione 9 di Dolibarr, il metodo consigliato per creare un modulo è utilizzare il Generatore di moduli , incluso di default. Vai su Home → Configurazione → Moduli/Applicazioni , trova "Generatore di moduli" nell'elenco e attivalo.
Una volta attivata, una nuova icona (spesso rappresentata da un piccolo insetto o un ingranaggio) appare nell'angolo in alto a destra dello schermo. Questa apre l'interfaccia di Module Builder, tecnicamente accessibile tramite l'indirizzo dello strumento di generazione. È da questa interfaccia che avviene tutta la magia.
Passaggio 2: Generare lo scheletro del modulo
Nell'interfaccia di Module Builder, fai clic sul pulsante per creare un nuovo modulo. Si aprirà una finestra che ti chiederà alcune informazioni di base: il nome del modulo (ad esempio, MyModule), la sua categoria, la sua descrizione e il suo editore.
Conferma e il Module Builder farà la maggior parte del lavoro: copierà i file modello che si trovano in htdocs/modulebuilder/template , effettuerà le necessarie sostituzioni di stringhe e creerà la struttura completa delle directory del tuo modulo in htdocs/custom/monmodule/ . In pochi secondi, otterrai un modulo valido, vuoto ma immediatamente riconosciuto da Dolibarr.
Suggerimento: Module Builder crea un file modulebuilder.txt nella directory principale del modulo. Non eliminarlo durante lo sviluppo: permette allo strumento di continuare a modificare il modulo tramite l'interfaccia grafica. Dovrai rimuoverlo solo al momento della distribuzione finale.
Passaggio 3: Personalizza il descrittore
Apri il descrittore generato nel tuo editor. Troverai numerose proprietà da modificare. Ecco le più importanti, così come appaiono nel costruttore della classe:
public function __construct($db)
{
$this->db = $db;
$this->numero = 500000; // identificatore univoco del modulo
$this->rights_class = 'monmodule'; // prefisso di autorizzazione
$this->family = 'other'; // famiglia di visualizzazione
$this->name = 'MonModule';
$this->description = 'Gestione personalizzata per la mia attività';
$this->version = '1.0';
$this->picto = 'generic'; // icona del modulo
}
Il punto principale da tenere presente riguarda il numero del modulo , che deve essere univoco per evitare conflitti con altri moduli. Il Generatore di moduli solitamente assegna un identificatore casuale da un intervallo riservato ai moduli esterni. Evitate di modificarlo arbitrariamente. La proprietà "version" viene utilizzata per tenere traccia degli aggiornamenti e la descrizione viene visualizzata nell'elenco dei moduli.
Passaggio 4: Definire le autorizzazioni
I permessi controllano chi può fare cosa nel tuo modulo. Sono dichiarati nella tabella dei diritti del descrittore. Ogni voce definisce un identificatore, un'etichetta e il tipo di azione che consente (lettura, creazione, eliminazione, ecc.).
$this->rights = array();
$r = 0;
$this->rights[$r][0] = 500001; // ID di autorizzazione univoco
$this->rights[$r][1] = 'Leggi record';
$this->rights[$r][4] = 'leggi';
$r++;
$this->rights[$r][0] = 500002;
$this->rights[$r][1] = 'Crea o modifica';
$this->rights[$r][4] = 'scrivi';
Quando il modulo viene attivato, questi diritti vengono salvati automaticamente nella tabella llx_rights_def . È quindi possibile assegnarli a utenti e gruppi tramite la normale interfaccia di amministrazione. Ricordate di verificare questi permessi nel vostro codice per ogni operazione sensibile: si tratta di una buona pratica di sicurezza di base.
Passaggio 5: Aggiungere una voce di menu
Affinché il modulo sia accessibile, deve avere almeno una voce di menu. Questa viene dichiarata nella tabella dei menu del descrittore. È necessario specificare il tipo di menu (a sinistra o in alto), il suo titolo, l'URL di destinazione e l'autorizzazione necessaria per visualizzarlo.
$this->menu[$r++] = array(
'fk_menu' => 'fk_mainmenu=mymodule',
'type' => 'left',
'title' => 'Elenco degli elementi',
'url' => '/custom/mymodule/mymodule_list.php',
'langs' => 'mymodule@mymodule',
'perms' => '$user->rights->mymodule->read',
'position' => 100,
);
Il campo "Autorizzazioni" garantisce che solo gli utenti autorizzati possano visualizzare la voce di menu. Una volta riattivato il modulo, il menu apparirà nella barra laterale, pronto per essere collegato alle schermate.
Passaggio 6: Creare un oggetto aziendale e la relativa tabella
Questo è il cuore di un modulo che manipola i dati. Il Generatore di moduli consente di aggiungere un "oggetto" in pochi clic, dalla scheda dedicata nella sua interfaccia. Si definisce il nome dell'oggetto e l'elenco dei suoi campi (testo, numero, data, collegamento a un altro oggetto, ecc.).
In base a questa definizione, lo strumento genera contemporaneamente diversi file: la classe DAO/CRUD nella cartella class/ (con metodi pronti all'uso per creare, leggere, aggiornare ed eliminare un record), lo script SQL per la creazione della tabella in sql/ , nonché le pagine di elenco e di record. Ciò rappresenta un notevole risparmio di tempo.
Lo script SQL generato ha questo aspetto, con le colonne corrispondenti ai tuoi campi:
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;
Nota importante: tutte le tabelle in un modulo Dolibarr sono precedute dal prefisso llx_ (o dal prefisso definito durante l'installazione). Attenersi a questa convenzione: previene conflitti di nomi e garantisce la coerenza con il resto del database.
Passaggio 7: Gestire le traduzioni
Dolibarr è multilingue e anche il tuo modulo deve esserlo. Le etichette sono memorizzate in file di lingua situati in langs/fr_FR/ . Ogni file associa una chiave a un testo tradotto, sotto forma di coppie chiave = valore:
# file langs/fr_FR/monmodule.lang
ModuleMonModuleName = Il mio modulo
ModuleMonModuleDesc = Gestione personalizzata per la mia attività
MonModuleList = Elenco di elementi
NewElement = Nuovo elemento
Nel tuo codice, non inserire mai il testo direttamente nel codice sorgente: fai riferimento alla chiave di traduzione. Dolibarr si occuperà quindi di visualizzare la lingua corretta in base alle preferenze dell'utente. Ricorda di creare almeno le versioni in francese e in inglese dei file per una distribuzione più ampia.
Passaggio 8: Attivare e testare il modulo
Il momento della verità. Vai all'elenco dei moduli di Dolibarr: il tuo modulo ora è presente. Attivalo. A questo punto, Dolibarr esegue gli script SQL, crea le tabelle, salva i permessi e installa i menu.
Successivamente, accedi alla nuova voce di menu, crea un primo record, modificalo ed eliminalo. Verifica che i dati vengano visualizzati correttamente nel database. Se riscontri problemi, la modalità sviluppatore e i log di Dolibarr sono i tuoi migliori alleati per diagnosticare la causa.
Suggerimento per il debug: se si verifica un errore dopo aver modificato il descrittore, disabilitare e quindi riabilitare il modulo per forzare Dolibarr a rileggere la configurazione e a rieseguire gli script di installazione. Molti problemi si risolvono con questo semplice passaggio.
Andando oltre: hook, trigger e API
Una volta acquisite le nozioni di base, Dolibarr offre potenti meccanismi per integrare a fondo il tuo modulo.
I ganci
Gli hook sono punti di iniezione che consentono di aggiungere o sostituire codice in posizioni specifiche all'interno di Dolibarr, senza modificare il core. I contesti di interesse vengono dichiarati utilizzando la proprietà `module_parts` del descrittore:
$this->module_parts = array(
'hooks' => array('invoicecard', 'thirdpartycard')
);
Successivamente, si scrive una classe hook i cui metodi verranno richiamati automaticamente quando Dolibarr raggiunge questi contesti. Questa soluzione è ideale per arricchire le schermate esistenti con le proprie informazioni.
Fattori scatenanti
I trigger eseguono del codice in risposta a un evento aziendale: la convalida di una fattura, la creazione di un account di terzi, l'eliminazione di un prodotto... Il tuo modulo può quindi reagire automaticamente, ad esempio per sincronizzare i dati con un sistema esterno o inviare una notifica.
L'API REST
Se il tuo oggetto aziendale deve essere accessibile dall'esterno del sistema, il Generatore di moduli può generare un'API REST dedicata. Ciò ti consente di esporre i tuoi dati ad altre applicazioni, nel rispetto delle autorizzazioni definite. Questo rappresenta un vantaggio significativo per connettere Dolibarr al tuo ecosistema software.
Buone pratiche di sviluppo
Seguire alcuni principi vi aiuterà a evitare molti errori e a semplificare la manutenzione del modulo nel tempo:
• Non modificare mai il kernel. Tutto il tuo codice rimane nella directory personalizzata. Questo garantisce aggiornamenti senza problemi.
• Verifica le autorizzazioni ovunque. Prima di ogni operazione delicata, accertati che l'utente disponga dei diritti corrispondenti.
• Proteggi i dati. Sanifica sistematicamente l'input dell'utente per prevenire vulnerabilità di tipo SQL injection e XSS.
• Gestisci le versioni del tuo codice. Usa Git fin dall'inizio per tenere traccia delle modifiche e collaborare senza problemi.
• Documenta e traduci. Etichette chiare e file di lingua completi rendono il tuo modulo utilizzabile da altri.
• Eseguite dei test prima della distribuzione. Attivate e disattivate il modulo su un'istanza pulita per convalidare l'installazione e la disinstallazione.
Debugging e risoluzione dei problemi comuni
Anche seguendo scrupolosamente ogni passaggio, prima o poi vi imbatterete inevitabilmente in comportamenti imprevisti. Ecco come mantenere il controllo e diagnosticare efficacemente i problemi più comuni.
La prima cosa da fare è abilitare i log di Dolibarr. In modalità sviluppatore, è possibile aumentare il livello di dettaglio dei log per vedere esattamente cosa sta facendo l'applicazione. La maggior parte degli errori lascia una traccia chiara, molto più utile di una schermata vuota. Ricordate inoltre di controllare il log degli errori PHP, che registra le anomalie non gestite.
Un modulo che non compare nell'elenco indica quasi sempre un problema con il descrittore di file: un errore di sintassi PHP, un nome di classe che non corrisponde al nome del file o una posizione errata nella struttura delle directory. Verificare che il file sia denominato secondo la convenzione prevista e che si trovi nella sottocartella corretta.
Se le tabelle non vengono create all'attivazione, controlla gli script SQL: un punto e virgola mancante o una sintassi incompatibile con il tuo database possono essere sufficienti a bloccare l'installazione. Disattiva e riattiva il modulo per riavviare la procedura una volta apportata la correzione.
Una buona abitudine: lavorare per piccole iterazioni. Modificare una sola cosa alla volta, poi testarla. Quando qualcosa non funziona, si sa immediatamente quale modifica ne è responsabile, mentre un gran numero di modifiche rende la diagnosi molto più difficile.
Domande frequenti
È obbligatorio utilizzare il Module Builder?
No, puoi scrivere tutto a mano copiando il modello del descrittore. Tuttavia, a partire da Dolibarr 9, il Module Builder è il metodo consigliato: genera codice pulito e conforme, ti fa risparmiare tempo prezioso e riduce gli errori. Puoi poi modificare manualmente i file generati.
Dove devo posizionare il mio modulo: nella directory personalizzata o nella directory principale?
Per un modulo esterno, posizionarlo sempre in htdocs/custom/ . La directory principale è riservata ai moduli destinati a diventare moduli core ufficiali di Dolibarr. La directory custom garantisce la separazione dal core.
Il mio modulo resisterà agli aggiornamenti di Dolibarr?
Sì, a patto che tu rispetti la regola d'oro: non modificare mai il codice del kernel. Poiché il tuo modulo risiede in una directory separata e utilizza i meccanismi ufficiali (hook, trigger, descrittori), rimane compatibile con gli aggiornamenti di versione, a condizione che tu mantenga aggiornate le API.
Posso distribuire o vendere il mio modulo?
Certamente. Molti moduli di terze parti, sia gratuiti che a pagamento, sono disponibili sul marketplace ufficiale. Assicurati solo di rispettare la licenza di Dolibarr e di fornire una documentazione chiara e le traduzioni necessarie.
Conclusione
Creare un modulo Dolibarr personalizzato è semplice. Grazie al Module Builder , la struttura di base viene generata in pochi clic, lasciandoti il compito di personalizzare il descrittore, dichiarare permessi e menu e definire i tuoi oggetti di business. Seguendo i passaggi di questo tutorial, ora disponi di solide basi per la creazione di estensioni personalizzate.
Il punto di forza di questo approccio risiede nel rispetto che riserva al software: tutto il tuo lavoro rimane isolato nella directory personalizzata, protetto dagli aggiornamenti. Puoi adattare Dolibarr alle tue esigenze più complesse senza mai comprometterne la funzionalità a lungo termine.
Il modo migliore per progredire ora è fare pratica. Avvia il tuo ambiente di sviluppo, genera il tuo primo modulo, aggiungi un oggetto e un menu e inizia a esplorare gradualmente hook, trigger e API. Ogni modulo che creerai ti renderà più a tuo agio con l'architettura di Dolibarr e ti aprirà le porte a possibilità pressoché illimitate.