Bitrix Framework

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.

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.

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

// handler registration in /bitrix/php_interface/init.php
AddEventHandler("main", "OnBeforeUserLogin", "MyOnBeforeUserLoginHandler");
function MyOnBeforeUserLoginHandler($arFields)
{
   if(strtolower($arFields["LOGIN"])=="guest")
   {
       global $APPLICATION;
       $APPLICATION->throwException("The user with the login name Guest cannot be authorized.");
       return false;
   }
}

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.

The list and description of events accessible to modules are located in the Documentation for the developers.