Hooks system

= Introduction = Hooks is a developer feature, available with Dolibarr 3.2 and more, to allow developer to add personalized code into Dolibarr core code with no need to patch Dolibarr. On the contrary to the triggers (another feature to interact with Dolibarr code) which are by definition linked to a business action, hooks can happen anywhere at anytime, they are entry points into the program.
 * Hooks are enabled or not for a "context" (ie the module, eg: "productcard" for products, "invoicecard" for invoices, etc..). It's easy to find them, just search for "initHooks(" into php files.
 * Hooks are part of code that can be completed or replaced with your own code. You can find all hookable part of code by searching for "executeHooks(".

= Add a hook to allow to insert code = To implement a hook in your own module (so that your module can be hooked by others), you have two steps to follow.

These steps must be followed for every php script of your module where you want to implement hooks.

1- Initialize the HookManager object (put this in the beginning of your script, just after includes):

$hookmanager->initHooks takes 1 parameter (an array of contexts) and activate the hooks management for this script:

- 'context' is a context string. This is simply a indicator that hooking functions can use to detect in which context they are called.

Note: you can set several contexts in the same init (for example if you want to have a common context into several pages and want also a specific context deidcated to your page).

2- Place hooks where you want to allow external code:

$hookmanager->executeHooks takes 4 parameters and add a hook (an entry point in your script for external functions):

- 'hookname' is the hook's name as a string (can be anything you want, or you can follow the Dolibarr's nomenclatura, look at the list of hooks below). eg: 'formObjectOptions'

- $parameters is a custom array to send more custom data to the hook (the hooking function can then process it). Place here anything you want, it can be a file, an array of strings, anything...

eg:

- $object is the object you want to pass onto the hooking function, mainly the current module's data (eg: invoice object if it is invoice module, etc..). This can be anything you want, but remember this will be the main component hooking functions will be using.

- $action is a string indicating the current action (can be set to null or to something sensible like 'create' or 'edit').

Note: You will want to redo this step if you want to add multiple hooks at different places in your script.

Now your module should be hookable, and you can follow the procedure below in Implement a hook to implement a hooking function that will take advantage of your new hooks.

= Implement the Hook =

To use a hook (add or replace a part of code), you first need to already have defined a module descriptor (see Module_development), and then you need to do 2 things:

1- add your module to the list of contexts you want to hook on. This means that when a context you hook will happen, your module hook code will be called. To do that, just edit your /htdocs/yourmodulename/core/modules/modYourModuleName.class.php and edit the $this->module_parts variable with something like this:

Of course change YourModuleName with your own module's name.

Note: you can find the current module's context with print('Module context: '.$object->context); (put this inside the module's php file where the hook resides and that you want to hook).

Be careful: do not forget to DISABLE then ENABLE the module in the admin panel to accept the new context, because these constants are only added to the database when enabling the module.

2- You will overload a hook (a function) with your own.

Create a file /htdocs/yourmodulename/class/actions_yourmodulename.class.php and then put something like this:

Your function should now be called when you access the module/context and you will see the parameters and object and action.

Where:
 * $parameters is an array of meta-data about the datas contained by the hook (eg: the context, always accessible by $parameters['context']).
 * $object is the object that you may work on. Eg: the product if you are in the productcard context.
 * $action is the action if one is conveyed (generally "create", "edit" or "view").
 * $hookmanager is propagated only to allow your hook to call another hook.

Returns: In general, it will be 0. It can be 1, which means that, in some specific cases, your code hook completely replaces what Dolibarr would do without the hook.
 * The return code from a hook is 0 or 1 if success, negative if error.
 * If the method sets the property $this->results with an array, then the array $hookmanager->resArray will automatically be enriched with the contents of this array, which can be reused later.
 * If the method sets the property $this-> resprints with a string, then this string will be displayed by the manager hook (executeHook), immediately after your method exit.
 * Your code can also modify the value of $object and $action.

= List of available Hooks in Dolibarr = How to find a complete list of all available hooks in Dolibarr's nomenclatura ? Just search for "executeHooks(" through the whole sourcecode (generally called "find in files") and you should easily find all the hooked methods calls.

This is however a small list of them (not complete):

...

Note: please note that this list may change in the future as hooks and contexts are added into Dolibarr, so if you really need to find a specific hooks, please search directly in the sourcecode.

= List of available Contexts in Dolibarr = To find the complete list of available modules' context in Dolibarr's nomenclatura, the procedure is similar to finding hooks. Search for "initHooks(" through the whole sourcecode (generally called "find in files") and you should find all the possible contexts.

This is however a small list of them (not complete):

...

Note: please note that this list may change in the future as hooks and contexts are added into Dolibarr, so if you really need to find a specific hooks, please search directly in the sourcecode.

= See also =
 * Triggers
 * Interfaces Dolibarr toward foreign systems
 * Interfaces from foreign systems toward Dolibarr