Bitrix Framework

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.

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.

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

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

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