Table of Contents
-
Introduction
-
Understanding Dolibarr’s Modular Architecture
-
When and Why to Build an External Module
-
Tools and Environment Setup
-
Folder Structure and File Naming Conventions
-
Creating the Module Descriptor File
-
Implementing Hooks and Triggers
-
Using Dolibarr's Core Classes and APIs
-
Integrating with Existing Dolibarr Features
-
UI/UX Guidelines for Seamless Integration
-
Managing Permissions and Access Control
-
Language File Management and Translations
-
Security Considerations During Development
-
Handling Upgrades and Compatibility
-
Testing Your Module: Manual and Automated
-
Packaging and Distributing Your Module
-
Contributing to the Dolibarr Ecosystem
-
Conclusion
1. Introduction
Dolibarr’s success as an ERP and CRM system is deeply rooted in its modular design. Users can extend or customize Dolibarr’s core functionality through external modules without touching the core codebase. Whether you're developing a vertical industry extension or a feature plugin, this guide presents best practices to develop maintainable, secure, and user-friendly external modules for Dolibarr.
2. Understanding Dolibarr’s Modular Architecture
Dolibarr is designed to be extended. Each module operates within its own namespace and directory under /htdocs/custom/
or /htdocs/module/
.
Key principles:
-
Encapsulation: Modules are self-contained.
-
Non-intrusiveness: Modules should not modify core files.
-
Reusability: Generic logic should be designed for reuse.
This architecture enables safe upgrades and collaborative development.
3. When and Why to Build an External Module
You should consider building a module when:
-
You need custom business logic not found in Dolibarr core.
-
Your features are specific to your company or industry.
-
You plan to share functionality with others via Dolistore.
Advantages:
-
Easier maintenance
-
Version control independence
-
Community adoption potential
4. Tools and Environment Setup
Recommended tools:
-
PHP 7.4+ and MySQL
-
Apache/Nginx with mod_rewrite
-
A local Dolibarr installation for development
-
A version control system (Git)
Set MAIN_MODULE_CUSTOMDIR
in conf.php
to point to /htdocs/custom
if you're placing modules there.
5. Folder Structure and File Naming Conventions
Your module should follow this structure:
/custom/mycustommodule/
├── class/
├── core/
├── lang/
├── modulebuilder.txt
├── modMycustommodule.class.php
├── mycustommodule.php
Naming conventions:
-
Prefix files and classes with your module name
-
Use lowercase filenames with underscores
-
Class files should follow Dolibarr's camel case format
6. Creating the Module Descriptor File
modMycustommodule.class.php
defines metadata:
-
Module name and number
-
Version
-
Dependencies
-
Menus and permissions
-
Triggers and hooks
The init
method handles setup, and remove
handles cleanup.
7. Implementing Hooks and Triggers
Dolibarr allows your module to interact with core events via:
-
Hooks (UI level): Add buttons, tabs, or override displays
-
Triggers (data level): Act on create, update, delete actions
Define hooks in hook/
directory and register them in your module descriptor.
8. Using Dolibarr's Core Classes and APIs
Leverage existing Dolibarr classes to handle:
-
Invoices (
Facture
) -
Third parties (
Societe
) -
Products (
Product
)
For external integrations, use the REST API or create your own custom endpoints.
9. Integrating with Existing Dolibarr Features
Ensure your module plays well with:
-
Multicompany module (check for
conf->entity
) -
Language management (use
langs->trans()
) -
User rights (define clear permissions)
10. UI/UX Guidelines for Seamless Integration
Respect Dolibarr’s visual standards:
-
Use existing CSS classes
-
Integrate tabs into existing entities when possible
-
Avoid jarring design changes or custom fonts
Make it feel native to the system.
11. Managing Permissions and Access Control
Your module should:
-
Define permission keys in the descriptor
-
Check permissions via
user->rights->mycustommodule->access
-
Hide menus and buttons for unauthorized users
Keep control logic centralized and consistent.
12. Language File Management and Translations
Language files should live in:
/langs/en_US/mycustommodule.lang
Use langs->load("mycustommodule")
and reference strings via langs->trans("MyLabel")
This supports multi-language environments and Dolibarr’s translation community.
13. Security Considerations During Development
Security best practices:
-
Sanitize user inputs (
dol_htmlentities
,GETPOST
) -
Use token verification for forms
-
Escape output to prevent XSS
-
Protect internal scripts with access checks (
restrictedarea()
)
Never trust external data sources.
14. Handling Upgrades and Compatibility
Design your module to handle version evolution:
-
Maintain backward compatibility when possible
-
Use
module_version
fields to manage migrations -
Include upgrade scripts in your module
Keep your module compatible with the last 2–3 Dolibarr major versions.
15. Testing Your Module: Manual and Automated
Always test:
-
UI behaviors
-
Trigger execution
-
Database changes
-
Access control
Consider writing PHPUnit tests if applicable. Use separate test environments.
16. Packaging and Distributing Your Module
To publish on Dolistore:
-
Compress your module folder without parent directory
-
Include
README.md
andCHANGELOG.txt
-
Provide screenshots and documentation
Use semantic versioning (1.0.0
, 1.1.0
) and maintain changelogs.
17. Contributing to the Dolibarr Ecosystem
You can:
-
Submit your module to Dolistore
-
Share improvements on GitHub
-
Participate in forums and IRC
-
Submit pull requests for core enhancements
Community feedback improves both your module and Dolibarr itself.
18. Conclusion
Building external modules is the most effective way to tailor Dolibarr to your organization’s needs while preserving upgradeability and stability. Following best practices ensures that your module is clean, secure, and easy to maintain. As Dolibarr continues to grow, well-crafted modules will be key drivers in its evolution and adoption.