Using Hooks in Dolibarr for Advanced Integration

Table of Contents

1. Introduction

2. What Are Hooks in Dolibarr?

3. Types of Hooks: Interface vs Business Events

4. When Should You Use a Hook?

5. Understanding Dolibarr’s Hook System Architecture

6. Setting Up a Hook in a Custom Module

7. Registering Hook Contexts in the Module Descriptor

8. Hook Method Naming Conventions

9. UI Hooks: Enhancing User Interfaces

10. Data Hooks: Capturing Core Business Logic Events

11. Practical Examples of Useful Hooks

12. Creating a Hook File and Structuring Your Logic

13. Accessing Dolibarr Objects from a Hook

14. Chaining Hooks Across Multiple Modules

15. Performance Considerations and Best Practices

16. Debugging Hooks: Tools and Tips

17. Security Implications of Hook Logic

18. Integrating Third-Party Systems via Hooks

19. Hook Compatibility During Dolibarr Upgrades

20. Final Thoughts

1. Introduction

Dolibarr is built to be flexible, modular, and highly extensible. One of the most powerful tools in its architecture is the hook system. Hooks allow developers to inject their own logic into the application without modifying core code. Whether you're customizing displays, validating data, or synchronizing with external systems, hooks provide a clean and efficient method to achieve deep integration.

2. What Are Hooks in Dolibarr?

Hooks are entry points defined in the Dolibarr core that allow external modules to "hook into" the application and add or modify behavior. They are function calls dynamically triggered during specific events.

There are two main categories:

• Interface Hooks: Affect what the user sees (menus, buttons, pages).

• Business/Event Hooks: Run logic during data changes (create, update, delete).

3. Types of Hooks: Interface vs Business Events

Some hooks are purely visual, others allow operational logic to run on Dolibarr events.

4. When Should You Use a Hook?

Use a hook when you need to:

• Add a custom tab or button to existing Dolibarr pages.

• Inject additional validation when records are saved.

• Log, sync, or react to business object changes.

• Extend the behavior of a core process without altering core code.

Avoid using hooks for logic that is unrelated to Dolibarr core events or when performance is critical and a direct override is more suitable.

5. Understanding Dolibarr’s Hook System Architecture

Dolibarr's hook mechanism is object-oriented. Modules can define hook classes that extend DolibarrHooks and implement methods corresponding to the targeted contexts.

Each module can register a class in the hook/ directory:

/custom/mymodule/hook/interface_99_modmymodule_common.php

6. Setting Up a Hook in a Custom Module

1. Create a new PHP file in your module’s hook/ directory.

2. Define a class that matches the naming convention.

3. In your module descriptor (modMymodule.class.php), register the hook contexts:

$this->hooks = array('invoicecard', 'thirdpartycard');

7. Registering Hook Contexts in the Module Descriptor

Hook contexts tell Dolibarr where your hook should be applied. Common contexts include:

• invoicecard

• ordercard

• thirdpartycard

• propalcard

These correspond to interface screens or object types.

8. Hook Method Naming Conventions

Hooks follow specific method naming patterns. Example:

function formObjectOptions($parameters, &$object, &$action, $hookmanager) {
    // Custom logic here
}

The method name must match the core hook trigger. Dolibarr calls your method if it exists.

9. UI Hooks: Enhancing User Interfaces

Examples include:

• addMoreActionsButtons: Add buttons to the form

• printObjectLine: Inject HTML into a line view

• formObjectOptions: Add new fields to forms

This allows you to extend the UI without overriding templates.

10. Data Hooks: Capturing Core Business Logic Events

You can react to object lifecycle events:

• doActions: Custom action processing

• addMoreTabs: Add new tabs to a card

• beforeObjectSave, afterObjectSave

Use these for validation, logging, or notifications.

11. Practical Examples of Useful Hooks

1. Log every new invoice creation in a custom table

2. Show a warning banner on overdue proposals

3. Add a custom PDF export option to the invoice page

4. Send a webhook to another system when a third party is updated

12. Creating a Hook File and Structuring Your Logic

Structure:

class InterfaceModmymoduleCommon {
    function formObjectOptions($parameters, &$object, &$action, $hookmanager) {
        echo '<tr><td>Custom Field</td><td><input type="text" name="customfield"></td></tr>';
        return 1;
    }
}

Always return 0 or 1 to indicate whether Dolibarr should continue default behavior.

13. Accessing Dolibarr Objects from a Hook

Dolibarr passes the active object (invoice, third party, etc.) via the $object parameter. You can:

• Read data: $object->ref, $object->id

• Modify: $object->note_private = 'new note'

• Validate logic before saving

14. Chaining Hooks Across Multiple Modules

Multiple modules can register the same hook context. Dolibarr executes each in sequence:

1. mymodule

2. customaddon

3. thirdmodule

Avoid side effects that affect shared state (e.g., unset global variables).

15. Performance Considerations and Best Practices

• Keep hook logic efficient

• Minimize database queries

• Cache values if reused multiple times

• Avoid outputting large HTML blocks unless needed

Heavy hooks can impact page load time.

16. Debugging Hooks: Tools and Tips

• Use dol_syslog() to log hook execution

• Check Dolibarr’s debug logs in /documents/admin/system.log

• Temporarily dump variables with var_dump() or print_r()

17. Security Implications of Hook Logic

• Validate all user input within hooks

• Sanitize output before echoing HTML

• Never trust values from $_POST/$_GET without GETPOST()

• Check permissions before performing actions

Hooks can be exploited if they expose sensitive actions.

18. Integrating Third-Party Systems via Hooks

Common patterns:

• Send API requests on afterObjectCreate

• Store data in external systems on afterObjectUpdate

• Push messages to queues (e.g., RabbitMQ)

Use hooks to integrate Dolibarr into microservice architectures or SaaS platforms.

19. Hook Compatibility During Dolibarr Upgrades

When upgrading Dolibarr:

• Review changelogs for hook method changes

• Test your modules on staging environments

• Avoid relying on undocumented hooks or internal objects

Dolibarr maintains backward compatibility but not guaranteed for internal changes.

20. Final Thoughts

Hooks are the foundation of Dolibarr's extensibility. They enable developers to build powerful customizations while keeping the core untouched. Mastering them is essential for advanced module development, third-party integrations, and clean, scalable business logic.

Take advantage of hooks to tailor Dolibarr to your exact needs—and do it the right way.