Views: 621
Last Modified: 25.05.2021

Sometimes, there is a need to affect an API function performance. But, if you change it, these changes will be lost upon a next update. For such cases, an event system was developed. When executing some API functions, other specific functions, the so-called event handlers are called in determined points.

Note: Event handlers must be treated carefully. Due to a significant event model-related content available in Bitrix Framework, elusive errors in developer code can occur. They can significantly inhibit developer's work efficiency.

The specific event handler functions must be called at individual points (and upon which triggered events) - must be indicated by calling the function, that registers the handlers. Presently, there are two available: Bitrix\Main\EventManager::addEventHandler и Bitrix\Main\EventManager::registerEventHandler. The set of events for each module is described in the documentation dedicated to each module. Here's, for example, a link to main module events.

registerEventHandler - function for registering the handlers, located in modules and used for interaction between system modules. This function must be called once when installing the module, after that, handler function will be automatically called at a specific moment, preliminarily connecting the module itself.

Deleted via Bitrix\Main\EventManager::unRegisterEventHandler when deleting the module.

Example

$eventManager = \Bitrix\Main\EventManager::getInstance();

// compression module handler functions are connected twice - at the start and at the end of each page
$eventManager->registerEventHandler("main", "OnPageStart", "compression", "CCompress", "OnPageStart", 1);
$eventManager->registerEventHandler("main", "OnAfterEpilog", "compression", "CCompress", "OnAfterEpilog");

// module installer registers an empty handler
// advertisement module will be directly connecting at each page when the event OnBeforeProlog triggers
// allows to execute its API functions without preliminary connecting in the page body
$eventManager->registerEventHandler("main", "OnBeforeProlog", "advertising");

Each module can provide interface to other modules for indirect communication - in a form of set of events. Such interaction allows making modules maximally independent from each other. Module knows nothing about the other module operation, but will interact with it via event interface.

AddEventHandler - function is designed to register arbitrary handlers that are not located in modules. It must be called before event triggering at the pages, where event handler is processed. For example, when event must be processed on all pages, where it occurs, the function can be called in /bitrix/php_interface/init.php.

Example

// handler registering in /bitrix/php_interface/init.php
$eventManager = \Bitrix\Main\EventManager::getInstance();
$eventManager->addEventHandlerCompatible("main", "OnBeforeUserLogin", "MyOnBeforeUserLoginHandler");

function MyOnBeforeUserLoginHandler($arFields)
{
   if(strtolower($arFields["LOGIN"])=="guest")
   {
       global $APPLICATION;
       $APPLICATION->throwException("User with Guest login name cannot be authorized.");
       return false;
   }
}

Anonymous functions are suitable for "quick and painful solution" approach. To avoid overloading the code by various functions or classes, proceed as follows:

use Bitrix\Main\EventManager;

$eventManager = EventManager::getInstance();

$eventManager->addEventHandlerCompatible("main", "OnAfterUserLogin", function(&$fields) {
// Мой код
});

Differences in functions

Actions that you will perform via the events must be physically written and must be registered to be performing upon triggering of necessary events.

registerEventHandler registers in the database, and AddEventHandler registers in the init.php file. It means that using the first function leads to additional load on the database. It is best used in situations, where executed actions must be registered once and for all specifically in database.


Usually, events are divided into those occurring at a specific location and designation into the following groups:

  • Intended for cancelling further method execution. For example, event OnBeforeUserDelete allows cancelling user deleting upon specified conditions (available associated objects of critical significance), event OnBeforeUserLogin - restrict authorization for a user;
  • Allowed to be executed in specific methods, upon completed method execution. For example, OnAfterUserLogin - after the login name and password check, event OnUserDelete - before direct deletion of user from database; allows deleting associated objects;
  • Occurring during executing a page, to enable custom code into specific locations on the page. For example, OnBeforeProlog, (see details at page execution sequence).
Note for developers:

When it is required to expand an event log with new event types (for example, upon actions with iblocks), use the event handler OnEventLogGetAuditTypes. Array that it will return is added to the standard array in the admin section.

List and description of events, available to individual modules is located in Documentation for developers.


Chapter contents:


Courses developed by Bitrix24