Erstellung eines benutzerdefinierten Dolibarr-Moduls: Schritt-für-Schritt-Anleitung
Möchten Sie Dolibarr erweitern, ohne den Kern der Software zu verändern? Folgen Sie diesem vollständigen Tutorial, um Ihr eigenes Modul zu erstellen – von der Aktivierung des Modul-Builders bis zum Speichern des ersten Geschäftsobjekts in der Datenbank.
Entwicklung · Dolibarr · PHP • Mittleres Niveau
Zusammenfassung
1. Warum ein benutzerdefiniertes Dolibarr-Modul erstellen?
3. Die Architektur eines Moduls verstehen
4. Schritt 1: Modul-Builder aktivieren
5. Schritt 2: Modulgerüst generieren
6. Schritt 3: Den Deskriptor anpassen
7. Schritt 4: Berechtigungen definieren
8. Schritt 5: Menüeintrag hinzufügen
9. Schritt 6: Erstellen Sie ein Geschäftsobjekt und die zugehörige Tabelle.
10. Schritt 7: Übersetzungen verwalten
11. Schritt 8: Modul aktivieren und testen
12. Weiterführende Informationen: Hooks, Trigger und APIs
13. Gute Entwicklungspraktiken
14. Häufig auftretende Probleme beheben und lösen
Dolibarr verdankt seinen Erfolg maßgeblich seiner modularen Architektur. Anstatt einen monolithischen Block vorzugeben, bietet es Dutzende von Modulen, die je nach Bedarf aktiviert oder deaktiviert werden können. Vor allem aber ermöglicht es Entwicklern, eigene Module zu schreiben. Dies ist der Schlüssel, um das ERP-System an spezifische Geschäftsanforderungen anzupassen, ohne den ursprünglichen Quellcode zu verändern – was nahtlose Updates garantiert.
In diesem Tutorial lernen Sie Schritt für Schritt, wie Sie ein eigenes Dolibarr-Modul von Grund auf erstellen. Wir verwenden dazu den Modul-Builder , das in Dolibarr integrierte Codegenerierungstool, das Ihnen viele mühsame Arbeitsschritte abnimmt. Am Ende verfügen Sie über ein voll funktionsfähiges Modul mit eigenem Menü, Berechtigungen, einem mit einer Datenbanktabelle verknüpften Geschäftsobjekt und Übersetzungen.
Dieser Leitfaden richtet sich an Entwickler mit PHP-Grundkenntnissen. Sie müssen kein Experte sein: Wir erklären jedes Konzept Schritt für Schritt. Schnappen Sie sich Ihren bevorzugten Code-Editor, starten Sie Ihre Dolibarr-Entwicklungsumgebung und los geht's!
Warum ein benutzerdefiniertes Dolibarr-Modul erstellen?
Bevor man auch nur eine Zeile Code schreibt, ist es hilfreich zu verstehen, was ein Modul tatsächlich ermöglicht. Ein Dolibarr-Modul ist kein einfaches Skript, sondern eine vollwertige Erweiterung, die sich tief in die Anwendung integrieren lässt.
Konkret kann ein benutzerdefiniertes Modul neue Datenbanktabellen hinzufügen, eigene Eingabemasken erstellen, Menüeinträge einfügen, Registerkarten zu bestehenden Datensätzen (Rechnungen, Produkte, Drittanbieter usw.) hinzufügen, neue Berechtigungen definieren, Code bei Ereignissen mithilfe von Triggern automatisch ausführen oder sich sogar über Hooks in bestehenden Code einfügen.
Der Hauptvorteil lässt sich in einem Satz zusammenfassen: Sie erweitern Dolibarr, ohne den Kern zu verändern . Ihre Entwicklungen befinden sich in einem separaten Verzeichnis und bleiben auch nach Versionsaktualisierungen erhalten. Dies ist der grundlegende Unterschied zwischen einem sauberen Modul und einem Eingriff in den Quellcode, der mit dem ersten Update verloren ginge.
Voraussetzungen vor Beginn
Eine gut vorbereitete Umgebung erspart Ihnen viel Frust. Hier ist, was Sie benötigen.
Grundkenntnisse
Fundierte PHP-Kenntnisse sind unerlässlich, ebenso wie SQL-Kenntnisse für Datentabellen und Grundkenntnisse in HTML/CSS für die Benutzeroberfläche. Kenntnisse in objektorientierter Programmierung sind von Vorteil, da die Geschäftsobjekte von Dolibarr auf Klassen basieren.
Die Entwicklungsumgebung
Installieren Sie eine separate Dolibarr-Instanz für die Entwicklung, getrennt von Ihrer Produktionsumgebung. Verwenden Sie einen benutzerfreundlichen Code-Editor wie Visual Studio Code oder PhpStorm und stellen Sie sicher, dass gängige PHP-Erweiterungen (pdo, gd, intl usw.) auf Ihrem Server installiert sind.
Entwicklermodus aktivieren
Der Modul-Builder wird nur im Entwicklermodus angezeigt. Öffnen Sie Ihre Datei htdocs/conf/conf.php und nehmen Sie die Anwendung aus dem Produktionsmodus, indem Sie diese Zeile hinzufügen oder ändern:
$dolibarr_main_prod = 0;
Denken Sie daran, in den Anzeigeeinstellungen die Funktionsstufe auf „Entwickler“ zu setzen, um erweiterte Tools freizuschalten. Sobald diese Einstellungen vorgenommen wurden, stehen Ihnen die Entwicklerfunktionen zur Verfügung.
Wichtig: Arbeiten Sie niemals direkt in Ihrer Dolibarr-Produktionsumgebung. Der Entwicklermodus zeigt sensible Informationen an und aktiviert Tools, die auf einer Live-Website nichts zu suchen haben. Verwenden Sie diese Einstellungen ausschließlich für eine Testumgebung.
Die Architektur eines Moduls verstehen
Ein Dolibarr-Modul folgt einer klar definierten Dateistruktur. Das Verständnis dieser Struktur hilft Ihnen, sich im generierten Code zurechtzufinden und zu wissen, wo Sie Ihre Anpassungen vornehmen können.
Der Dateibaum
Ein externes Modul wird im Verzeichnis htdocs/custom/ abgelegt . So sieht die typische Verzeichnisstruktur eines Moduls mit dem Namen mymodule aus :
htdocs/custom/mymodule/
├── core/
│ └── modules/
│ └── modMyModule.class.php (die Beschreibung)
├── class/ (Geschäftsobjekte – CRUD-Klassen)
├── sql/ (Tabellenerstellungsskripte)
├── admin/ (die Konfigurationsseite)
├── lib/ (Hilfsfunktionen)
├── langs/ (Übersetzungsdateien)
│ └── fr_FR/
└── mymodule_index.php (die Hauptseite)
Die Deskriptordatei, die Schlüsselkomponente
Die Datei ` modMonModule.class.php` im Verzeichnis `core/modules/` ist das Herzstück des Moduls. Dolibarr liest diese Datei, um den Namen, die Funktion, die Berechtigungen, die hinzugefügten Menüs und die installierten Tabellen Ihres Moduls zu bestimmen. Sie erweitert die Klasse `DolibarrModules` . Ohne diese Datei erkennt Dolibarr Ihr Modul nicht.
Schritt 1: Aktivieren Sie den Modul-Builder
Seit Dolibarr Version 9 wird die Verwendung des Modul-Builders empfohlen , der standardmäßig enthalten ist. Gehen Sie zu Startseite → Konfiguration → Module/Anwendungen , suchen Sie in der Liste nach „Modul-Builder“ und aktivieren Sie ihn.
Nach der Aktivierung erscheint oben rechts auf dem Bildschirm ein neues Symbol (oft ein kleines Insekt oder ein Zahnrad). Dadurch öffnet sich die Benutzeroberfläche des Modul-Editors, die technisch über die Adresse des Generierungstools erreichbar ist. Über diese Oberfläche findet die eigentliche Bearbeitung statt.
Schritt 2: Modulgerüst generieren
Klicken Sie in der Benutzeroberfläche des Modul-Builders auf die Schaltfläche, um ein neues Modul zu erstellen. Ein Fenster fordert Sie zur Eingabe einiger grundlegender Informationen auf: den Modulnamen (z. B. MeinModul), die Kategorie, die Beschreibung und den Herausgeber.
Nach der Bestätigung erledigt der Modul-Builder den Großteil der Arbeit: Er kopiert die Vorlagendateien aus htdocs/modulebuilder/template , führt die notwendigen Zeichenkettenersetzungen durch und erstellt die vollständige Verzeichnisstruktur Ihres Moduls in htdocs/custom/monmodule/ . Innerhalb weniger Sekunden erhalten Sie ein gültiges Modul – leer, aber sofort von Dolibarr erkannt.
Hinweis: Der Modul-Builder erstellt eine Datei namens „modulebuilder.txt“ im Stammverzeichnis des Moduls. Löschen Sie diese Datei während der Entwicklung nicht, da sie die weitere Bearbeitung des Moduls über die grafische Benutzeroberfläche ermöglicht. Sie muss erst bei der endgültigen Veröffentlichung entfernt werden.
Schritt 3: Den Deskriptor anpassen
Öffnen Sie den generierten Deskriptor in Ihrem Editor. Sie finden dort zahlreiche Eigenschaften, die Sie anpassen können. Hier sind die wichtigsten, so wie sie im Klassenkonstruktor erscheinen:
public function __construct($db)
{
$this->db = $db;
$this->numero = 500000; // eindeutiger Modulbezeichner
$this->rights_class = 'monmodule'; // Berechtigungspräfix
$this->family = 'other'; // Anzeigefamilie
$this->name = 'MonModule';
$this->description = 'Benutzerdefinierte Verwaltung für mein Unternehmen';
$this->version = '1.0';
$this->picto = 'generic'; // Modulsymbol
}
Wichtig ist vor allem die Modulnummer , die eindeutig sein muss , um Konflikte mit anderen Modulen zu vermeiden. Der Modul-Builder vergibt üblicherweise eine zufällige Kennung aus einem für externe Module reservierten Bereich. Ändern Sie diese nicht willkürlich. Die Versionseigenschaft dient zur Nachverfolgung von Aktualisierungen, und die Beschreibung wird in der Modulliste angezeigt.
Schritt 4: Berechtigungen definieren
Berechtigungen steuern, wer in Ihrem Modul welche Aktionen ausführen darf. Sie werden in der Rechtetabelle des Deskriptors deklariert. Jeder Eintrag definiert eine Kennung, eine Bezeichnung und die Art der zulässigen Aktion (Lesen, Erstellen, Löschen usw.).
$this->rights = array();
$r = 0;
$this->rights[$r][0] = 500001; // eindeutige Berechtigungs-ID
$this->rights[$r][1] = 'Datensätze lesen';
$this->rights[$r][4] = 'lesen';
$r++;
$this->rights[$r][0] = 500002;
$this->rights[$r][1] = 'Erstellen oder ändern';
$this->rights[$r][4] = 'schreiben';
Nach der Aktivierung des Moduls werden diese Rechte automatisch in der Tabelle `llx_rights_def` gespeichert . Anschließend können Sie sie über die gewohnte Verwaltungsoberfläche Ihren Benutzern und Gruppen zuweisen. Denken Sie daran, diese Berechtigungen in Ihrem Code für jede sensible Aktion zu überprüfen: Dies ist eine grundlegende Sicherheitsmaßnahme.
Schritt 5: Menüeintrag hinzufügen
Damit Ihr Modul zugänglich ist, benötigt es mindestens einen Menüpunkt. Dieser wird in der Menütabelle des Deskriptors definiert. Sie legen den Menütyp (links oder oben), den Titel, die Ziel-URL und die zum Anzeigen erforderliche Berechtigung fest.
$this->menu[$r++] = array(
'fk_menu' => 'fk_mainmenu=mymodule',
'type' => 'left',
'title' => 'Liste der Elemente',
'url' => '/custom/mymodule/mymodule_list.php',
'langs' => 'mymodule@mymodule',
'perms' => '$user->rights->mymodule->read',
'position' => 100,
);
Das Berechtigungsfeld stellt sicher, dass nur autorisierte Benutzer den Menüeintrag sehen. Sobald das Modul reaktiviert ist, erscheint Ihr Menü in der Seitenleiste und kann mit Ihren Seiten verlinkt werden.
Schritt 6: Erstellen Sie ein Geschäftsobjekt und die zugehörige Tabelle
Dies ist der Kern eines Moduls zur Datenverarbeitung. Mit dem Modul-Builder können Sie über den entsprechenden Tab in der Benutzeroberfläche mit wenigen Klicks ein „Objekt“ hinzufügen. Sie definieren den Namen des Objekts und die Liste seiner Felder (Text, Zahl, Datum, Verknüpfung zu einem anderen Objekt usw.).
Basierend auf dieser Definition generiert das Tool mehrere Dateien gleichzeitig: die DAO/CRUD-Klasse im Ordner „class/ “ (mit sofort einsatzbereiten Methoden zum Erstellen, Lesen, Aktualisieren und Löschen von Datensätzen), das SQL-Skript zum Erstellen der Tabelle im Ordner „sql/“ sowie die Listen- und Datensatzseiten. Dies führt zu einer erheblichen Zeitersparnis.
Das generierte SQL-Skript sieht folgendermaßen aus, wobei die Spalten Ihren Feldern entsprechen:
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;
Wichtiger Hinweis: Alle Tabellen in einem Dolibarr-Modul beginnen mit dem Präfix „llx_“ (oder dem bei der Installation festgelegten Präfix). Halten Sie sich an diese Konvention: Sie verhindert Namenskonflikte und gewährleistet die Konsistenz mit dem Rest der Datenbank.
Schritt 7: Übersetzungen verwalten
Dolibarr ist mehrsprachig, und Ihr Modul muss es auch sein. Die Bezeichnungen werden in Sprachdateien im Verzeichnis langs/fr_FR/ gespeichert . Jede Datei ordnet einem übersetzten Text einen Schlüssel in Form von Schlüssel-Wert-Paaren zu.
# Datei langs/fr_FR/monmodule.lang
ModuleMonModuleName = Mein Modul
ModuleMonModuleDesc = Benutzerdefinierte Verwaltung für meine Aktivität
MonModuleList = Liste der Elemente
NewElement = Neues Element
In Ihrem Code wird der Text nie fest codiert, sondern über den Übersetzungsschlüssel aufgerufen. Dolibarr sorgt dann dafür, dass die richtige Sprache gemäß den Benutzereinstellungen angezeigt wird. Denken Sie daran, mindestens französische und englische Versionen der Dateien zu erstellen, um eine breitere Verbreitung zu ermöglichen.
Schritt 8: Modul aktivieren und testen
Jetzt kommt es darauf an. Rufen Sie die Liste der Dolibarr-Module auf: Ihr Modul wird nun angezeigt. Aktivieren Sie es. Dolibarr führt nun die SQL-Skripte aus, erstellt die Tabellen, speichert die Berechtigungen und installiert die Menüs.
Navigieren Sie anschließend zu Ihrem neuen Menüeintrag, erstellen Sie einen ersten Datensatz, bearbeiten Sie ihn und löschen Sie ihn. Überprüfen Sie, ob die Daten korrekt in der Datenbank angezeigt werden. Sollte etwas nicht stimmen, sind der Entwicklermodus und die Dolibarr-Protokolle Ihre besten Helfer zur Fehlerbehebung.
Tipp zur Fehlerbehebung: Sollte nach der Änderung des Deskriptors ein Fehler auftreten, deaktivieren Sie das Modul und aktivieren Sie es anschließend wieder. Dadurch wird Dolibarr gezwungen, die Konfiguration neu einzulesen und die Installationsskripte erneut auszuführen. Viele Probleme lassen sich mit diesem einfachen Schritt beheben.
Weiterführende Informationen: Hooks, Trigger und APIs
Sobald die Grundlagen erlernt sind, bietet Dolibarr leistungsstarke Mechanismen zur detaillierten Integration Ihres Moduls.
Die Haken
Hooks sind Injektionspunkte, die es Ihnen ermöglichen, Code an bestimmten Stellen in Dolibarr hinzuzufügen oder zu ersetzen, ohne den Kern zu verändern. Sie deklarieren die Kontexte, die Sie interessieren, mithilfe der `module_parts`- Eigenschaft des Deskriptors:
$this->module_parts = array(
'hooks' => array('invoicecard', 'thirdpartycard')
);
Anschließend erstellen Sie eine Hook-Klasse, deren Methoden automatisch aufgerufen werden, sobald Dolibarr diese Kontexte erreicht. Dies ist ideal, um bestehende Bildschirme mit Ihren eigenen Informationen anzureichern.
Auslöser
Trigger führen Code als Reaktion auf ein Geschäftsereignis aus: die Validierung einer Rechnung, die Erstellung eines Drittanbieters, die Löschung eines Produkts… Ihr Modul kann somit automatisch reagieren, beispielsweise um Daten mit einem externen System zu synchronisieren oder eine Benachrichtigung zu senden.
Die REST-API
Wenn Ihr Geschäftsobjekt von außerhalb des Systems zugänglich sein muss, kann der Modul-Builder eine dedizierte REST-API generieren. Dadurch können Sie Ihre Daten anderen Anwendungen zur Verfügung stellen und gleichzeitig die definierten Berechtigungen einhalten. Dies ist ein wesentlicher Vorteil für die Anbindung von Dolibarr an Ihre Software-Umgebung.
Gute Entwicklungspraktiken
Wenn Sie einige wenige Grundsätze befolgen, können Sie viele Fallstricke vermeiden und die Wartung Ihres Moduls im Laufe der Zeit vereinfachen:
• Verändern Sie niemals den Kernel. Ihr gesamter Code verbleibt im benutzerdefinierten Verzeichnis. Dies garantiert problemlose Aktualisierungen.
• Überprüfen Sie überall die Berechtigungen. Stellen Sie vor jeder sensiblen Aktion sicher, dass der Benutzer die entsprechenden Rechte besitzt.
• Daten sichern. Benutzereingaben systematisch bereinigen, um SQL-Injection- und XSS-Schwachstellen zu verhindern.
• Versionieren Sie Ihren Code. Verwenden Sie von Anfang an Git, um Ihre Änderungen nachzuverfolgen und reibungslos zusammenzuarbeiten.
• Dokumentieren und übersetzen. Klare Beschriftungen und umfassende Sprachdateien sorgen dafür, dass Ihr Modul auch von anderen genutzt werden kann.
• Testen Sie Ihr Modul vor der Verteilung. Aktivieren und deaktivieren Sie es auf einer sauberen Instanz, um die Installation und Deinstallation zu validieren.
Fehlerbehebung und Lösung häufiger Probleme
Selbst wenn Sie jeden Schritt sorgfältig befolgen, werden Sie früher oder später unweigerlich auf unerwartetes Verhalten stoßen. Hier erfahren Sie, wie Sie die Kontrolle behalten und die häufigsten Probleme effektiv diagnostizieren können.
Als Erstes sollten Sie die Dolibarr-Protokollierung aktivieren. Im Entwicklermodus können Sie die Protokolldetails erhöhen, um genau zu sehen, was die Anwendung tut. Die meisten Fehler hinterlassen eine klare Spur, die viel hilfreicher ist als ein leerer Bildschirm. Vergessen Sie außerdem nicht, das PHP-Fehlerprotokoll zu überprüfen, das unbehandelte Anomalien erfasst.
Ein Modul, das nicht in der Liste erscheint, deutet fast immer auf ein Problem mit dem Dateideskriptor hin: einen PHP-Syntaxfehler, einen Klassennamen, der nicht mit dem Dateinamen übereinstimmt, oder einen falschen Speicherort in der Verzeichnisstruktur. Überprüfen Sie, ob die Datei der erwarteten Namenskonvention entspricht und sich im richtigen Unterverzeichnis befindet.
Werden Ihre Tabellen nach der Aktivierung nicht erstellt, überprüfen Sie Ihre SQL-Skripte: Ein fehlendes Semikolon oder eine mit Ihrer Datenbank inkompatible Syntax kann die Installation blockieren. Deaktivieren Sie das Modul und aktivieren Sie es anschließend wieder, um den Vorgang nach der Korrektur neu zu starten.
Eine gute Angewohnheit: Arbeiten Sie in kleinen Schritten. Ändern Sie immer nur eine Sache und testen Sie diese anschließend. Wenn etwas nicht mehr funktioniert, wissen Sie sofort, welche Änderung dafür verantwortlich ist – bei einer großen Anzahl von Änderungen wird die Fehlersuche hingegen deutlich erschwert.
Häufig gestellte Fragen
Ist die Verwendung des Modul-Builders zwingend erforderlich?
Nein, Sie können alles manuell schreiben, indem Sie die Deskriptorvorlage kopieren. Seit Dolibarr 9 ist jedoch der Modul-Builder die empfohlene Methode: Er generiert sauberen und konformen Code, spart Ihnen wertvolle Zeit und reduziert Fehler. Anschließend können Sie die generierten Dateien manuell bearbeiten.
Wo soll ich mein Modul platzieren: im benutzerdefinierten Verzeichnis oder im Stammverzeichnis?
Externe Module sollten immer in htdocs/custom/ abgelegt werden . Das Stammverzeichnis ist für Module reserviert, die zu offiziellen Dolibarr-Kernmodulen werden sollen. Das benutzerdefinierte Verzeichnis gewährleistet die Trennung vom Kern.
Wird mein Modul Dolibarr-Updates überstehen?
Ja, solange Sie die goldene Regel beachten: Verändern Sie niemals den Kernel-Code. Da sich Ihr Modul in einem eigenen Verzeichnis befindet und die offiziellen Mechanismen (Hooks, Trigger, Deskriptoren) verwendet, bleibt es auch bei Versionsaktualisierungen kompatibel, vorausgesetzt, Sie halten sich über API-Updates auf dem Laufenden.
Darf ich mein Modul vertreiben oder verkaufen?
Absolut. Viele Drittanbietermodule, sowohl kostenlose als auch kostenpflichtige, sind auf dem offiziellen Marktplatz erhältlich. Achten Sie lediglich darauf, die Dolibarr-Lizenz einzuhalten und eine klare Dokumentation sowie alle notwendigen Übersetzungen bereitzustellen.
Abschluss
Das Erstellen eines benutzerdefinierten Dolibarr-Moduls ist ganz einfach. Dank des Modul-Builders wird die Grundstruktur mit wenigen Klicks generiert. Anschließend können Sie den Deskriptor anpassen, Berechtigungen und Menüs festlegen sowie Ihre Geschäftsobjekte definieren. Mit den Schritten in diesem Tutorial schaffen Sie eine solide Grundlage für die Entwicklung eigener Erweiterungen.
Die Stärke dieses Ansatzes liegt in seinem Respekt vor der Software: Ihre gesamte Arbeit bleibt im benutzerdefinierten Verzeichnis isoliert und ist vor Updates geschützt. Sie können Dolibarr an Ihre anspruchsvollsten Bedürfnisse anpassen, ohne die langfristige Funktionsfähigkeit zu beeinträchtigen.
Der beste Weg, jetzt Fortschritte zu erzielen, ist Übung. Starten Sie Ihre Entwicklungsumgebung, erstellen Sie Ihr erstes Modul, fügen Sie ein Objekt und ein Menü hinzu und erkunden Sie nach und nach Hooks, Trigger und die API. Mit jedem Modul, das Sie entwickeln, werden Sie sich mit der Architektur von Dolibarr vertrauter machen – und Ihnen nahezu unbegrenzte Möglichkeiten eröffnen.