Sometimes it is necessary to adjust the execution process of an API function. However, if the function is changed, these changes will be lost after the next update. For these cases, an event system has been developed. During the execution of certain API functions specific function invocations called event handlers are set at specific points.
Note: Event handlers should be handled very carefully. Since the event model in Bitrix Framework is rich enough, hard-to-find errors may appear in the handler’s code without due care. They may seriously unnerve the developer.
Invocation of a handler registering function determines which handler functions must be invoked in a place (in case of which event). At present, there are two such handler registering functions – AddEventHandler and RegisterModuleDependences. The set of events for each module is described in the documentation for each module. Here is, for example, the link to the main module events.
- is a function for the registration of handlers located in modules and used for interaction among system modules. This function must be invoked once during module installation; after that the event handler function will be automatically invoked at a specific time, having connected the module itself first.
It is deleted using UnRegisterModuleDependences during the elimination of a module.
// compression module handler functions are connected twice – at the head and in the foot of each page
RegisterModuleDependences("main", "OnPageStart", "compression", "CCompress", "OnPageStart", 1);
RegisterModuleDependences("main", "OnAfterEpilog", "compression", "CCompress", "OnAfterEpilog");
// empty handler registers advertising module installer
// should an OnBeforeProlog event occur, the advertising module will be simply connected on each page
// which will make it possible to execute its API functions without preliminary connection in a page body
RegisterModuleDependences("main", "OnBeforeProlog", "advertising");
Each module may provide other modules with an interface for implicit interaction – an event set. Such interaction permits making modules independent from one another to the fullest extent. The module knows nothing about the functioning particulars of the other module, but may interact with it through the event interface.
- function is intended for the registration of arbitrary handlers that are not located in modules. This function must be invoked before an event occurs on the pages where such an event must be handled. E.g., if an event must be handled on all pages where it occurs, the function may be invoked in /bitrix/php_interface/init.php
// handler registration in /bitrix/php_interface/init.php
AddEventHandler("main", "OnBeforeUserLogin", "MyOnBeforeUserLoginHandler");
$APPLICATION->throwException("The user with the login name Guest cannot be authorized.");
Differences in the Use of Functions
The actions to be performed using events must be physically written somewhere, and they must be set to respond to a specific event.
RegisterModuleDependences performs registration in the database, and AddEventHandler in the file init.php. I.e. the use of the first function results in an additional load on the database. It should be used in situations when the actions performed must be fixed once and for all precisely in the database.
As a rule, events are divided by place of occurrence and purpose into the following group:
- Those intended for the cancellation of the further execution of a method. E.g., the event OnBeforeUserDelete permits to cancel the elimination of a user subject to specific conditions (availability of critically linked objects), the event OnBeforeUserLogin permits to prohibit a user’s authorization.
- Those permitting execution in specific methods upon the completion of their execution. E.g., OnAfterUserLogin – after verification of login and password, the event OnUserDelete – permits to eliminate linked objects immediately before the elimination of a user from the database.
- Those occurring during the execution of a page in order to enable their code in specific places on a page. For example, OnBeforeProlog (for more details, see procedure for page execution).
The list and description of events accessible to modules are located in the Documentation for the developer.