Système de Hooks
Les Hooks sont une fonctionnalité pour les développeurs, disponible à partir de Dolibarr 3.2, leur permettant d'ajouter du code personnalisé aux pages standards de Dolibarr sans avoir à modifier les fichiers du coeur de Dolibarr. Contrairement aux triggers (autre manière d'interagir avec le code de Dolibarr) qui sont liés aux événements de Dolibarr, les Hooks peuvent s'exécuter n'importe ou et à n'importe quel moment. Ce sont des points d'insertion dans le programme.
- Les Hooks agissent selon le contexte (càd le module : par exemple "productcard" pour les produits, "invoicecard" pour les factures...). Pour trouver les Hooks existants faites une recherche pour "initHooks("
- Les Hooks sont des fonctions qui peuvent être surchargées. Vous décidez si votre code s'ajoute à celui de dolibarr ou s'il le remplace. Pour rechercher le code qu'il est possible de surcharger faites une recherche pour "executeHooks("
Implementation
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):
// Initialize technical object to manage hooks of thirdparties. Note that conf->hooks_modules contains array array
include_once(DOL_DOCUMENT_ROOT.'/core/class/hookmanager.class.php');
$hookmanager=new HookManager($db);
$hookmanager->initHooks(array('context'));
$hookmanager->initHooks() takes 1 parameter (an array of contexts) and activate the hooks management for this script:
- 'context' is the module's context as a string. This is simply a indicator that hooking functions can use to detect which modules they want to hook (several different modules can have the same hooks names, but a hooking function may want to hook only one specific module and not the others).
Note: you can set several contexts in the same script (for example if you want to break the functionnalities of your script into smaller parts, or if you are mixing several modules into one, for example when you do a bridge between modules or third-party application).
2- Place hooks wherever you want in your script:
$parameters=array();
$reshook=$hookmanager->executeHooks('hookname',$parameters,$object,$action); // See description below
// Note that $action and $object may have been modified by hook
$hookmanager->executeHooks() takes 4 parameters:
- '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:
$parameters=array('file'=>'my/path/to/a/file', 'customnames'=>array('henry','david','john'));
- $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 Usage to implement a hooking function that will take advantage of your new hooks.
Note2: If your hook can't be accessed, try to DISABLE then RENABLE your module for the hooks to be taken in account by Dolibarr (may not be required).
Utilisation
Pour utiliser un Hook (donc ajouter ou surcharger une partie de code), vous devez d'abord avoir défini un module (voir le wiki sur la création d'un module). Ensuite vous devez suivre les étapes suivantes :
1. Ajouter votre module au contexte où le hook doit d'exécuter.
Ce qui veut dire que lorsqu'on se trouve dans le contexte donné, votre code sera appelé.
Pour cela, éditer le descripteur de votre module (/htdocs/yourmodulename/core/modules/modYourModuleName.class.php) et renseignez la variable $this->module_parts comme sur l'exemple :
$this->module_parts = array(
'hooks' => array('hookcontext1','hookcontext2') // Set here all hooks context managed by module
);
Note: il est possible de trouver le contexte d'un module en rajoutant print('Module context: '.$object->context); (rajoutez ce bout de code dans le fichier php du module que vous voulez hooker et où réside le hook que vous visez).
IMPORTANT: n'oubliez pas de désactiver puis de réactiver votre module pour que la modification soit prise en compte car la sauvegarde des couple modules-hooks à gérer est faite en base, laquelle n'est mise à jour qu'au moment de l'activation du module.
2. Pour remplacer une fonction existante par la votre (surcharge)
Créez /htdocs/yourmodulename/class/actions_yourmodulename.class.php dans votre module avec un code qui contient la méthode appelé par le hook (le nom de cette méthode se voit au moment de l'appel executeHooks). Voici un exemple:
class ActionsYourModuleName
{
/** 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'
}
}
}
Où
- $parameters est un tableau (array) de meta-data regroupant les données du hook (son contexte accessible par $parameters->context mais d'autres information peuvent etre disponible selon le cas)
- $object est l'objet sur lequel vous désirez travailler (par exemple : product pour le contexte productcard)
- $action désigne l'action à exécuter (par exemple "create", "edit" or "view").
Liste des Hooks disponibles dans Dolibarr
Trouver les hooks disponibles dans Dolibarr ? Faites une recherche sur "executeHooks(" dans le code source et vous trouverez facilement toutes les fonctions déjà implémentées.
En voici une liste (non complète): Template:ListOfHooks ...
Note: veuillez noter que cette liste peut changer à tout moment dans le futur au fur et à mesure que les hooks et contextes soient implémentés dans Dolibarr, donc si vous voulez vraiment savoir si un hook ou contexte spécifique existe, veuillez chercher directement dans le code source avec la méthode indiquée ci-dessus.
Liste des Contexts disponibles dans Dolibarr
Pour trouver les contextes disponibles dans Dolibarr, la procédure est similaire aux hooks. Faites une recherche sur "initHooks(" dans le code source et vous trouverez facilement tous les contextes déjà implémentées.
En voici une liste (non complète):
adherents\card.php(111): membercard
adherents\type.php(73): membertypecard
categories\categorie.php(96): categorycard
comm\card.php(72): commcard
comm\propal.php(99): propalcard
comm\action\card.php(85): actioncard
comm\action\index.php(112): agenda
comm\mailing\card.php(55): mailingcard
commande\card.php(93): ordercard
compta\facture.php(105): invoicecard
compta\paiement.php(70): paiementcard
compta\deplacement\card.php(50): tripsandexpensescard
compta\dons\card.php(53): doncard
compta\localtax\clients.php(172): externalbalance
compta\salaries\card.php(47): salarycard
compta\tva\card.php(45): taxvatcard
contact\card.php(77): contactcard
contrat\card.php(70): contractcard
expedition\card.php(85): expeditioncard
fichinter\card.php(80): interventioncard
fourn\card.php(54): suppliercard
fourn\commande\card.php(80): ordersuppliercard
fourn\commande\orderstoinvoice.php(88): orderstoinvoicesupplier
fourn\facture\card.php(72): invoicesuppliercard
fourn\facture\paiement.php(71): paymentsupplier
livraison\card.php(68): deliverycard
product\card.php(91): productcard
product\composition\card.php(55): productcompositioncard
product\fournisseurs.php(62): pricesuppliercard
product\stats\commande.php(45): productstatsorder
product\stats\commande_fournisseur.php(45): productstatssupplyorder
product\stats\contrat.php(45): productstatscontract
product\stats\facture.php(48): productstatsinvoice
product\stats\facture_fournisseur.php(47): productstatssupplyinvoice
product\stats\propal.php(45): productstatspropal
product\stock\card.php(54): warehousecard
projet\card.php(48): projectcard
projet\tasks.php(67): projecttaskcard
resource\card.php(60): resource_card
resource\element_resource.php(58): element_resource
societe\agenda.php(41): agendathirdparty
societe\commerciaux.php(40): salesrepresentativescard
societe\consumption.php(80): consumptionthirdparty
societe\info.php(41): infothirdparty
societe\soc.php(80): thirdpartycard
user\card.php(93): usercard
user\list.php(72): userlist
user\passwordforgotten.php(56): passwordforgottenpage
...
Note: veuillez noter que cette liste peut changer à tout moment dans le futur au fur et à mesure que les hooks et contextes soient implémentés dans Dolibarr, donc si vous voulez vraiment savoir si un hook ou contexte spécifique existe, veuillez chercher directement dans le code source avec la méthode indiquée ci-dessus.