触发系统
将您的代码添加到业务事件
为了能够触发自定义代码以响应Dolibarr事件(创建/修改/删除、公司/发票/产品/用户或其他),Dolibarr提供了一种业务触发机制。例如,此机制允许您自定义工作流,以便Dolibarr的管理事件可以反映到另一个应用程序中。也没有什么可以阻止使用它来改变Dolibarr本身的行为:例如,在验证发票后自动创建合同、在删除记录时填写日志文件...
请注意,触发器是一项开发功能,仅限于CRUD业务事件(创建|读取|更新|删除)。还有另一个功能允许开发人员将自定义代码注入应用程序,名为 Hooks system 。
因此,要添加将由触发器触发的自己的代码,过程如下:
1)htdocs/modulebuilder/template/core/triggers/interface_99_modMyModule_MyModuleTriggers.class.phpu文件复制一份,命名为 interface_99_all_Xxx.class.php 或 interface_99_modMyModule_Xxx.class.php
其中 Xxx 是您选择的以大写字母开头的字符串;99是触发器的优先级号(01是最高优先级);如果您希望触发器仅在 myModule 处于活动状态时才应激活,则MyModule是模块的名称;如果我们希望触发器始终处于活动状态,我们将使用all代替modMyModule。此新文件必须保留在同一目录中。
注意:可用于 modMyModule 的值在目录 htdocs/core/modules 中可见。
警告:所有这些参数都是检测触发器所必需的!例如,如果您忘记了优先级号,将无法检测到该触发器!
例如,我们可以将我们的新触发器命名为 htdocs/core/triggers/interface_99_modFacture_Myworkflow.class.php
通过创建一个名为本例的文件,我们的新触发器将在每个Dolibarr业务事件中触发,前提是发票模块处于活动状态。
注意:使用Dolibarr 3.2+,还可以将触发器文件放置在模块的子文件夹中。例如:如果模块位于htdocs/mymodule/中,则可以将触发器放置在htdocs/mymodule/core/triggers/中。但在这种情况下,必须将触发器声明到模块的描述符文件(如: /mymodule/core/modules/modMyModule.class.php)中,才会找到触发器。
为此,请在数组 module_parts 中添加 'triggers' => 1
// Defined all module parts (triggers, login, substitutions, menus, etc...) (0=disable,1=enable)
$this->module_parts = array('triggers' => 1);
//$this->module_parts = array('triggers' => 1,
// 'login' => 0,
// 'substitutions' => 0,
// 'menus' => 0);
然后停用并重新激活模块。这将在 表llx_const 中添加一行记录,告诉Dolibarr必须在模块的目录 htdocs/mymodule/core/triggers/ 中查找触发器。
2)编辑文件interface_99_modMyModule_Myworkflow.class.php,以便将InterfaceDemo类重命名为InterfaceMyworkflow
然后转到 主页->管理工具->关于Dolibarr->Triggers。您的触发器文件应显示在“可用的触发器”清单中,表明前面的操作已成功完成。
3) 现在返回编辑触发器文件,将代码添加到 run_trigger 函数中。此函数在每个Dolibarr业务事件中调用。根据您希望响应的事件放置代码,每个事件都由一个代码标识(代码列表请参阅下一章),您可以通过判断变量 $action 对给定事件做出反应,也可以不做出反应:
function run_trigger($action,$object,$user,$langs,$conf)
{
// Put here code to execute after an action
// The type of Dolibarr business event is stored into $action
// Data of action are stored into object $object
// Setup, user and language are saved into $conf, $user and $lang
if ($action == 'COMPANY_CREATE')
{
dol_syslog("Trigger for action '$action' launched. id=".$object->id);
}
elseif ($action == 'COMPANY_MODIFY')
{
dol_syslog("Trigger for action '$action' launched. id=".$object->id);
}
elseif ($action == 'COMPANY_DELETE')
...
}
只要 run_trigger 函数根据以下原则返回一个返回代码,您就可以在这段代码中执行任何操作:
<0(如果ko),0(如果没有执行任何操作),>0(如果ok)
此外,在此函数中,您可以使用以下对象:
- $object 是操作所针对的对象(请参阅下一章)
- $user 是执行操作的dolibarr用户的对象
- $langs 是包含dolibarr用户语言的对象
- $conf 是包含整个Dolibarr配置的对象。
4) 代码开发完成后,只需在Dolibarr中触发触发事件即可进行测试。注意,函数 run_trigger 的调用被封装在事务中。如果触发器返回代码是 ko,调用函数可能会回滚事务(这取决于调用函数)。要在函数 run_trigger 中添加日志跟踪,用以确保代码运行良好。如果您愿意,可以使用函数 dol_syslog("my log message", LOG_DEBUG);
管理事件列表
以下是导致触发器被搜索和执行的事件的快速视图。事件的特征在于事件代码 $action 的值,以及在 $object 中接收的对象类型。
注意:日程模块 和 通知模块 使用 表llx c action trigger 作为已知触发器的表。这避免了扫描磁盘以获取此信息,但此表仅包含非常有限的触发器列表。
通常,触发事件代码 $action 以模块名称开头,后跟字符 _ 。
Trigger code ($action) | Type object ($object) |
USER_CREATE | user.class.php |
USER_MODIFY | user.class.php |
USER_DELETE | user.class.php |
USER_LOGIN | user.class.php |
USER_LOGIN_FAILED | user.class.php |
USER_LOGOUT | user.class.php |
USER_ENABLEDISABLE | user.class.php |
USER_NEW_PASSWORD | user.class.php |
USER_SETINGROUP | user.class.php |
USER_REMOVEFROMGROUP | user.class.php |
USERGROUP_CREATE (>= 12.0.0) | usergroup.class.php |
USERGROUP_MODIFY(>= 12.0.0) | usergroup.class.php |
USERGROUP_DELETE(>= 12.0.0) | usergroup.class.php |
GROUP_CREATE | usergroup.class.php |
GROUP_MODIFY | usergroup.class.php |
GROUP_DELETE (>= 3.3.0) | usergroup.class.php |
COMPANY_CREATE | societe.class.php |
COMPANY_MODIFY | societe.class.php |
COMPANY_DELETE | societe.class.php |
COMPANY_SENTBYMAIL (>= 3.5.0) | societe.class.php |
CONTACT_CREATE | contact.class.php |
CONTACT_MODIFY | contact.class.php |
CONTACT_DELETE | contact.class.php |
CONTACT_ENABLEDISABLE (>= 3.5.0) | contact.class.php |
PRODUCT_CREATE | product.class.php |
PRODUCT_MODIFY | product.class.php |
PRODUCT_PRICE_MODIFY | product.class.php |
PRODUCT_DELETE | product.class.php |
SUPPLIER_PRODUCT_BUYPRICE_MODIFY | fournisseur.product.class.php |
SUPPLIER_PRODUCT_BUYPRICE_CREATE | fournisseur.product.class.php |
ORDER_CREATE | commande.class.php |
ORDER_VALIDATE | commande.class.php |
ORDER_SENTBYMAIL | commande.class.php |
ORDER_DELETE | commande.class.php |
ORDER_CLASSIFY_BILLED | commande.class.php |
ORDER_CLONE | commande.class.php |
ORDER_CLOSE | commande.class.php |
ORDER_CANCEL | commande.class.php |
ORDER_REOPEN (>= 3.3.0) | commande.class.php |
ORDER_UNVALIDATE | commande.class.php |
COMMANDE_ADD_CONTACT | commande.class.php |
COMMANDE_DELETE_CONTACT | commande.class.php |
COMMANDE_DELETE_RESOURCE (>= 3.6.0) | commande.class.php |
LINEORDER_INSERT | commande.class.php |
LINEORDER_UPDATE | commande.class.php |
LINEORDER_DELETE | commande.class.php |
LINEORDER_DISPATCH (>= 3.4.0) | commande.class.php |
ORDER_SUPPLIER_CREATE | fournisseur.commande.class.php |
ORDER_SUPPLIER_CLONE | fournisseur.commande.class.php |
ORDER_SUPPLIER_VALIDATE | fournisseur.commande.class.php |
ORDER_SUPPLIER_SENTBYMAIL | fournisseur.commande.class.php |
ORDER_SUPPLIER_APPROVE | fournisseur.commande.class.php |
ORDER_SUPPLIER_REFUSE | fournisseur.commande.class.php |
ORDER_SUPPLIER_CANCEL | fournisseur.commande.class.php |
ORDER_SUPPLIER_DELETE | fournisseur.commande.class.php |
ORDER_SUPPLIER_DISPATCH (>= 3.4.0) | fournisseur.commande.class.php |
ORDER_SUPPLIER_ADD_CONTACT | fournisseur.commande.class.php |
ORDER_SUPPLIER_DELETE_CONTACT | fournisseur.commande.class.php |
ORDER_SUPPLIER_DELETE_RESOURCE (>= 3.6.0) | fournisseur.commande.class.php |
LINEORDER_SUPPLIER_CREATE | fournisseur.commande.class.php |
LINEORDER_SUPPLIER_UPDATE | fournisseur.commande.class.php |
LINEORDER_SUPPLIER_DELETE (>= 3.6.0) | fournisseur.commande.class.php |
PROPAL_CREATE | propal.class.php |
PROPAL_DELETE | propal.class.php |
PROPAL_CLONE | propal.class.php |
PROPAL_REOPEN (>= 3.5.0) | propal.class.php |
PROPAL_VALIDATE | propal.class.php |
PROPAL_CLOSE_SIGNED | propal.class.php |
PROPAL_CLOSE_REFUSED | propal.class.php |
PROPAL_SENTBYMAIL | propal.class.php |
PROPAL_MODIFY | propal.class.php |
PROPAL_ADD_CONTACT | propal.class.php |
PROPAL_DELETE_CONTACT | propal.class.php |
PROPAL_DELETE_RESOURCE (>= 3.6.0) | propal.class.php |
LINEPROPAL_INSERT | propal.class.php |
LINEPROPAL_UPDATE | propal.class.php |
LINEPROPAL_DELETE | propal.class.php |
CONTRACT_CREATE | contrat.class.php |
CONTRACT_VALIDATE | contrat.class.php |
CONTRACT_SERVICE_ACTIVATE | contrat.class.php |
CONTRACT_SERVICE_CLOSE | contrat.class.php |
CONTRACT_DELETE | contrat.class.php |
CONTRAT_ADD_CONTACT | contrat.class.php |
CONTRAT_DELETE_CONTACT | contrat.class.php |
CONTRAT_DELETE_RESOURCE (>= 3.6.0) | contrat.class.php |
LINECONTRACT_INSERT | contrat.class.php |
LINECONTRACT_MODIFY | contrat.class.php |
LINECONTRACT_DELETE | contrat.class.php |
BILL_CREATE | facture.class.php |
BILL_MODIFY | facture.class.php |
BILL_CLONE | facture.class.php |
BILL_VALIDATE | facture.class.php |
BILL_UNVALIDATE (>= 3.4.0) | facture.class.php |
BILL_PAYED | facture.class.php |
BILL_UNPAYED | facture.class.php |
BILL_CANCEL | facture.class.php |
BILL_DELETE | facture.class.php |
BILL_SENTBYMAIL | facture.class.php |
FACTURE_ADD_CONTACT | facture.class.php |
FACTURE_DELETE_CONTACT | facture.class.php |
FACTURE_DELETE_RESOURCE (>= 3.6.0) | facture.class.php |
LINEBILL_INSERT | facture.class.php |
LINEBILL_UPDATE | facture.class.php |
LINEBILL_DELETE | facture.class.php |
BILL_SUPPLIER_CREATE | fournisseur.facture.class.php |
BILL_SUPPLIER_MODIFY | fournisseur.facture.class.php |
BILL_SUPPLIER_DELETE | fournisseur.facture.class.php |
BILL_SUPPLIER_VALIDATE | fournisseur.facture.class.php |
BILL_SUPPLIER_PAYED | fournisseur.facture.class.php |
BILL_SUPPLIER_UNPAYED | fournisseur.facture.class.php |
BILL_SUPPLIER_SENTBYMAIL | fournisseur.facture.class.php |
INVOICE_SUPPLIER_ADD_CONTACT | fournisseur.facture.class.php |
INVOICE_SUPPLIER_DELETE_CONTACT | fournisseur.facture.class.php |
INVOICE_SUPPLIER_DELETE_RESOURCE (>= 3.6.0) | fournisseur.facture.class.php |
LINEBILL_SUPPLIER_CREATE | fournisseur.facture.class.php |
LINEBILL_SUPPLIER_UPDATE | fournisseur.facture.class.php |
LINEBILL_SUPPLIER_DELETE (>= 3.4.0) | fournisseur.facture.class.php |
PAYMENT_CUSTOMER_CREATE | paiement.class.php |
PAYMENT_DELETE (<= 3.8) | paiement.class.php |
PAYMENT_CUSTOMER_DELETE (>= 3.9) | paiement.class.php |
PAYMENT_ADD_TO_BANK | paiement.class.php |
PAYMENT_SUPPLIER_CREATE | paiementfourn.class.php |
PAYMENT_SUPPLIER_DELETE (>= 3.9) | paiement.class.php |
PAYMENT_SALARY_CREATE (>= 3.6.0) | paymentsalary.class.php |
PAYMENT_SALARY_MODIFY (>= 3.6.0) | paymentsalary.class.php |
PAYMENT_SALARY_DELETE (>= 3.6.0) | paymentsalary.class.php |
FICHINTER_CREATE | fichinter.class.php |
FICHINTER_MODIFY | fichinter.class.php |
FICHINTER_DELETE | fichinter.class.php |
FICHINTER_VALIDATE | fichinter.class.php |
FICHINTER_SENTBYMAIL | fichinter.class.php |
FICHINTER_ADD_CONTACT | fichinter.class.php |
FICHINTER_DELETE_CONTACT | fichinter.class.php |
FICHINTER_DELETE_RESOURCE (>= 3.6.0) | fichinter.class.php |
LINEFICHINTER_CREATE (>= 3.5.0) | fichinter.class.php |
LINEFICHINTER_UPDATE (>= 3.5.0) | fichinter.class.php |
LINEFICHINTER_DELETE (>= 3.5.0) | fichinter.class.php |
MEMBER_CREATE | adherent.class.php |
MEMBER_VALIDATE | adherent.class.php |
MEMBER_SUBSCRIPTION | adherent.class.php |
MEMBER_MODIFY | adherent.class.php |
MEMBER_RESILIATE | adherent.class.php |
MEMBER_NEW_PASSWORD | adherent.class.php |
MEMBER_DELETE | adherent.class.php |
CATEGORY_CREATE | category.class.php |
CATEGORY_MODIFY | category.class.php |
CATEGORY_DELETE | category.class.php |
CATEGORY_LINK (>= 3.5.0) | category.class.php |
CATEGORY_UNLINK (>= 3.5.0) | category.class.php |
SHIPPING_CREATE | expedition.class.php |
SHIPPING_VALIDATE | expedition.class.php |
SHIPPING_MODIFY | expedition.class.php |
SHIPPING_DELETE | expedition.class.php |
SHIPPING_SENTBYMAIL | expedition.class.php |
DELIVERY_VALIDATE | livraison.class.php |
DELIVERY_DELETE | livraison.class.php |
ACTION_CREATE | actioncomm.class.php |
ACTION_MODIFY | actioncomm.class.php |
ACTION_DELETE | actioncomm.class.php |
ACTION_ADD_CONTACT | actioncomm.class.php |
ACTION_DELETE_CONTACT | actioncomm.class.php |
ACTION_DELETE_RESOURCE (>= 3.6.0) | actioncomm.class.php |
DEPLACEMENT_CREATE | deplacement.class.php |
DON_CREATE | don.class.php |
DON_MODIFY (>= 3.7.0) | don.class.php |
DON_DELETE (>= 3.7.0) | don.class.php |
LOCALTAX_CREATE | localtax.class.php |
LOCALTAX_MODIFY | localtax.class.php |
LOCALTAX_DELETE | localtax.class.php |
TVA_CREATE | tva.class.php |
TVA_MODIFY | tva.class.php |
TVA_DELETE | tva.class.php |
TVA_ADDPAYMENT | tva.class.php |
PROJECT_CREATE | project.class.php |
PROJECT_MODIFY | project.class.php |
PROJECT_DELETE | project.class.php |
PROJECT_VALIDATE | project.class.php |
PROJECT_CLOSE | project.class.php |
PROJECT_ADD_CONTACT | project.class.php |
PROJECT_DELETE_CONTACT | project.class.php |
PROJECT_DELETE_RESOURCE (>= 3.6.0) | project.class.php |
TASK_CREATE | task.class.php |
TASK_MODIFY | task.class.php |
TASK_DELETE | task.class.php |
TASK_TIMESPENT_CREATE | task.class.php |
TASK_TIMESPENT_MODIFY | task.class.php |
TASK_TIMESPENT_DELETE | task.class.php |
PROJECT_TASK_ADD_CONTACT | task.class.php |
PROJECT_TASK_DELETE_CONTACT | task.class.php |
PROJECT_TASK_DELETE_RESOURCE (>= 3.6.0) | task.class.php |
MYECMDIR_CREATE | ecmdirectory.class.php |
MYECMDIR_MODIFY | ecmdirectory.class.php |
MYECMDIR_DELETE | ecmdirectory.class.php |
STOCK_MOVEMENT | mouvementstock.class.php |
PAYBOX_PAYMENT_OK | |
PAYPAL_PAYMENT_OK | |
LINK_CREATE (>= 3.5.0) | link.class.php |
LINK_MODIFY (>= 3.5.0) | link.class.php |
LINK_DELETE (>= 3.5.0) | link.class.php |
OPENSURVEY_CREATE (>= 3.6.0) | opensurveysondage.class.php |
OPENSURVEY_DELETE (>= 3.6.0) | opensurveysondage.class.php |
此清单可能不完整。
创建新的触发器事件
要处理上述事件之外的其它事件,必须修改 Dolibarr 代码,以便在操作对象类的业务方法中添加以下序列:
// Call trigger
//$this->context = array('paramX'=>$valueX);
$result = $this->call_trigger('XXXXX_YYYYY', $user);
if ($result <0) $error++;
// End call triggers
然后,可以在任何触发器文件的 run_trigger 方法中添加一个 if 来管理该代码。run_trigger 方法的形式如下:
function run_trigger($action,$object,$user,$lang,$conf)
{
// Put here code to execute after an action
// The type of Dolibarr business event is stored into $action
// Data of action are stored into object $object
// Setup, user and language are saved into $conf, $user and $lang
if ($action == 'XXXXX_YYYYY')
{
dol_syslog("Trigger for action '$action' launched. id=".$object->id);
}
elseif ($action == 'COMPANY_CREATE')
{
dol_syslog("Trigger for action '$action' launched. id=".$object->id);
}
elseif ($action == 'COMPANY_MODIFY')
{
dol_syslog("Trigger for action '$action' launched. id=".$object->id);
}
elseif ($action == 'COMPANY_DELETE')
...
}
结论
因此,您可以在几分钟内添加一个Dolibarr到外部系统的接口,而不会有任何风险,因为我们没有接触 Dolibarr 代码,我们只是在触发器目录中放置了一个新的触发器文件。如果此接口对其他人有用,请毫不犹豫地将其打包为tgz文件(请参阅页面 模块开发#创建一个安装包来分发和安装您的模块),并将其提交到Dolibarr官网上的贡献下载空间。