Bitrix Site Manager

Handling events

Sometimes, a developer needs to affect execution of an API function in some aspect. But, if a function is changed manually, these modifications will be lost during the next update session. To enable developers affect the system logic, the events system has been developed. Many API functions call the event handlers during their execution.

To install an appropriate handler function for a specific event, a handler registration function should be called. Currently, the system provides the following two methods: AddEventHandler and RegisterModuleDependences. A set of events for each module is described in the corresponding module help section. For example, the events of the Kernel module can be found in this topic.

The information below highlights upon the handler function registration.

RegisterModuleDependences registers module specific handlers (located in modules) used for the system modules interaction. This function is to be called once when a module is being installed. After calling this function, the event hander will be called automatically; the module will included prior to calling the handler.

Example

// the compression module handlers are registered twice: 
// at the beginning and in the end of each page
RegisterModuleDependences("main", "OnPageStart", "compression", 
                          "CCompress", "OnPageStart", 1);
RegisterModuleDependences("main", "OnAfterEpilog", "compression", 
                          "CCompress", "OnAfterEpilog");

// the advertising module installer registers an empty handler:
// when the event OnBeforeProlog occurs, 
// the advertising module is included for each page, which enables 
// calling its API functions without including it in the page body explicitly
RegisterModuleDependences("main", "OnBeforeProlog", "advertising");

AddEventHandler registers arbitrary handlers which are not located in any module. It is to be called before an event occurs on pages where this event is to be handled. For example, if an event is to be handled on all pages, the function can be called in /bitrix/php_interface/init.php.

Example

// register handler in /bitrix/php_interface/init.php
AddEventHandler("main", 
                "OnBeforeUserLogin", 
                "MyOnBeforeUserLoginHandler");

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

Usually, events are divided into the following groups: according to the location of origin and purpose:

The more detailed information about an event rise locations and possible use can be found in the description of each event.

See Also