触发系统
将您的代码添加到业务事件
为了能够触发自定义代码以响应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->触发器。您的触发器文件应显示在无错误清单中,表明前面的操作已成功完成。
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_MODIFY | 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 |
| TICKET_CREATE | ticket.class.php |
| TICKET_MODIFY | ticket.class.php |
| TICKET_DELETE | ticket.class.php |
| TICKET_ASSIGNED | ticket.class.php |
| TICKET_CLOSE | ticket.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')
...
}
Conclusion
You can in few minutes, add an interface from Dolibarr towards another system (or why not towards Dolibarr itself), with no risk since you don't touch anything to Dolibarr files. You only "added" a new trigger file inside the trigger directory. If this new interface can serve a lot of other users, you can package it into a tgz file (see page Module_development#Create_a_package_to_distribute_and_install_your_module) and submit it on the download area in section external contributions on official Dolibarr web site.