Système de Hooks

Retour index
Documentation développeur

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("

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

Trouver les hooks disponibles ? Faites une recherche sur "executeHooks(" dans le code et vous trouverez facilement toutes les fonctions déjà implémentées.

En voici une liste (non complète): Template:ListOfHooks ...

Voir aussi

• Triggers
• Interfaces Dolibarr toward foreign systems
• Interfaces from foreign systems toward Dolibarr