Hooks system
Hooks is a developer feature, available with Dolibarr 3.2 and more, to allow developer to add personalized code intod 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 work by 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 functions that can be overloaded by your own. You decide if your code is added to standard Dolibarr code or if it replace Dolibarr code. You can find overloadable functions by searching for "executeHooks("
Implementation
To use a hook (add or replace a part of code), you first need to already have defined a module (see the wiki for that), 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/modules/modYourModuleName.class.php and edit the $this->module_parts variable with something like this:
$this->module_parts = array(
'hooks' => array('hookcontext1','hookcontext2') // Set here all hooks context managed by module
);
Of course change YourModuleName with your own module's name.
IMPORTANT: Be careful: do not forget to DISABLE then RENABLE 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:
<?php
class ActionsYourModuleName // extends CommonObject
{
/** Overloading the doActions function : replacing the parent's function with the one below
* @param parameters meta datas of the hook (context, etc...)
* @param object the object you want to process (an invoice if you are in invoice module, a propale in propale's module, etc...)
* @param action current action (if set). Generally create or edit or null
* @return void
*/
function doActions($parameters, $object, $action)
{
print_r($parameters);
echo "action: ".$action;
print_r($object);
if ($parameters->context == 'somecontext')
{
// do something only for the context 'somecontext'
}
}
}
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").
Your function should now be called when you access the module/context and you will see the parameters and object and action.
List of available Hooks
How to find a complete list of all available hooks ? Just search for "executeHooks(" through the code and you should easily find all the hooked methods calls.
This is however a small list of them (not complete): Template:ListOfHooks ...