钩子系统

返回
开发文档

返回
用户手册

返回
首页

简介

Hooks 是一项开发功能，允许开发人员将自定义代码添加到Dolibarr的标准页面，而无需修改Dolibarr的核心文件。与链接到Dolibarr事件的 触发系统（与Dolibarr代码交互的另一种方式）不同，Hooks可以预埋在Dolibarr核心代码的任何时间、任何地点运行。这些是程序中的插入点（被视为代码执行从当前页面“转移”并运行自定义代码，然后返回的点）。

每个Hook都有一个名字，例如，代码：$reshook=$hookmanager->executeHooks（'doActions'，$parameters，$object，$action）中的“doActions”；然而，Hook的名称通常不是唯一的（可能在各种代码模块中重复使用），因此为了准确识别位置，代码模块具有一个“上下文”名称，该名称将被该代码模块位置中的所有Hooks引用。因此，要使用Hooks，您需要知道它的上下文名称（位置）和Hooks名称。

• Hook是否处于活动状态取决于上下文（通常每个模块有一个上下文：例如，产品模块的“productcard”，发票模块的“invoicecard”等等）。要查找现有的Hooks，请在php文件中搜索“initHooks(”。

这将找到诸如“$hookmanager->initHooks(array('thirdpartycomm','globalcard'));”的结果，其中“thirdpartycomm”是上下文名称

• Hooks是用于插入或替换标准代码的函数。要查找可以覆盖的代码，请搜索“executeHooks(”。找不到就可能没有预埋Hook，所以你可以添加自己的Hook（并在Github中提交相应的拉取请求，以便将其包含在未来的版本中）。

这将找到诸如“$reshook = $hookmanager->executeHooks('addMoreBoxStatsCustomer', $parameters, $object, $action);”的结果，其中“addMoreBoxStatsCoustomer”是Hook名称。

添加/预埋hook以允许插入代码

要在您自己的模块中预埋hook（以便您的模块可以被其他模块“挂接”），您需要执行两个步骤。

这些步骤必须为模块中要预埋hook的每个PHP脚本复制。当然，这也是hook在每个核心Dolibarr模块中实现的方式。

1 - 初始化HookManager对象

对于一个页面，将这段代码放在PHP脚本的开头（在 main 的 include 之后）：

// 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() 接受1个参数（上下文数组），并启用此脚本的钩子支持。

- 'context' 是包含执行上下文的字符串。这是一个简单的指示符，钩子函数可以使用它来检测何时调用它们（多个页面/模块可以在不同的位置调用同一个钩子，而一个钩子函数可能只想为一个给定的上下文运行，而不想为其他上下文运行）。

注意：您可以同时放置多个上下文（例如，如果您需要多个页面共享一个上下文，但也需要特定于给定页面的上下文）。

对于方法或函数，可以通过以下方式获取钩子管理器：

global $hookmanager;

2 - 然后将

$parameters=array();
$reshook=$hookmanager->executeHooks('hookname',$parameters,$object,$action); // See description below
// Note that $action and $object may have been modified by hook
if (empty($reshook))
{
   ... // standard code that can be disabled/replaced by hook if return code > 0.
}

调用放置在允许添加代码的位置：

$parameters=array();
$reshook=$hookmanager->executeHooks('hookname',$parameters,$object,$action); // See description below
// Note that $action and $object may have been modified by hook
if (empty($reshook))
{
   ... // standard code that can be disabled/replaced by hook if return code > 0.
}

$hookmanager->executeHooks() 接受4个参数并添加钩子（这是脚本和模块外部函数的脚本入口点）：

- 'hookname' 是将被调用的hook的名称（可以是您想要的任何内容，也可以遵循 Dolibarr 的命名法，查看下面的钩子列表）。例如：“formObjectOptions”

- $parameters 是一个自定义数组，用于向钩子传递更多自定义数据（钩子中的函数可以处理这些数据）。把你想要的放在这里，它可以是一个文件、一个字符串数组、或任何东西...

例如：

$parameters=array('file'=>'my/path/to/a/file', 'customnames'=>array('henry','david','john'));

- $object 是您要传递给钩子函数的对象，通常是当前模块的数据（例如，如果您在发票模块中，则是发票对象等）。它可以是您想要的任何东西，但请记住，它将是钩子函数使用的主要组件。

- $action 是一个指示当前操作的字符串（可以是null或类似于“create”或“edit”的内容）。

注意：如果要在脚本的不同位置添加多个钩子，则需要多次重复此步骤。

现在您的模块应该可以被挂接了，您可以按照下面的实现钩子中的过程来实现一个钩子函数，该函数将利用您刚才添加的hook（还可以测试它是否有效）。

实现钩子

要使用钩子（因此添加或覆盖部分代码），必须首先定义模块描述符（请参阅module development＃create＿module＿descriptor（必需））。然后，您必须遵循以下步骤：

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

1- 将您的模块添加到要钩起的上下文列表中。

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:

$this->module_parts = array(
'hooks' => array('hookcontext1','hookcontext2')  // Set here all hooks context you want to support
);

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/refreshed to the database when re-enabling your module.

2- 你将用自己的一个钩子（一个函数）重载。

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

class ActionsYourModuleName
{ 
	/**
	 * Overloading the doActions function : replacing the parent's function with the one below
	 *
	 * @param   array()         $parameters     Hook metadatas (context, etc...)
	 * @param   CommonObject    &$object        The object to process (an invoice if you are in invoice module, a propale in propale's module, etc...)
	 * @param   string          &$action        Current action (if set). Generally create or edit or null
	 * @param   HookManager     $hookmanager    Hook manager propagated to allow calling another hook
	 * @return  int                             < 0 on error, 0 on success, 1 to replace standard code
	 */
	function doActions($parameters, &$object, &$action, $hookmanager)
	{
		$error = 0; // Error counter
		$myvalue = 'test'; // A result value

		print_r($parameters);
		echo "action: " . $action;
		print_r($object);

		if (in_array('somecontext', explode(':', $parameters['context'])))
		{
		  // do something only for the context 'somecontext'
		}

		if (! $error)
		{
			$this->results = array('myreturn' => $myvalue);
			$this->resprints = 'A text to show';
			return 0; // or return 1 to replace standard code
		}
		else
		{
			$this->errors[] = 'Error message';
			return -1;
		}
	}
}

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:

• The return code from a hook is 0 or 1 if success, negative if error. 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. If return code is negative, you can also set $this->errors[]='Error message to report to user'
• 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 hook manager (method executeHook), immediately after your method exit.
• Your code can also modify the value of $object and $action.

可用钩子列表

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): Template:ListOfHooks ...

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.

可用上下文列表

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):

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: 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.

参考

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