Table of Contents

  1. Introduction

  2. Understanding Dolibarr’s Modular Architecture

  3. When and Why to Build an External Module

  4. Tools and Environment Setup

  5. Folder Structure and File Naming Conventions

  6. Creating the Module Descriptor File

  7. Implementing Hooks and Triggers

  8. Using Dolibarr's Core Classes and APIs

  9. Integrating with Existing Dolibarr Features

  10. UI/UX Guidelines for Seamless Integration

  11. Managing Permissions and Access Control

  12. Language File Management and Translations

  13. Security Considerations During Development

  14. Handling Upgrades and Compatibility

  15. Testing Your Module: Manual and Automated

  16. Packaging and Distributing Your Module

  17. Contributing to the Dolibarr Ecosystem

  18. 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 and CHANGELOG.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.