Bitrix Framework

Bitrix24 is a ready-made product that enables the creation of the corporate portal of a company with the possibility to customize standard functionality according to a company’s needs.

Unlike Zend Framework, during the deployment of Bitrix Framework you obtain a set of classes as well as an advanced administrator’s interface.

The basic package includes an extensive set of components that ensures the quick deployment and implementation of projects.

Products based on Bitrix Framework are released in several versions. When studying the system and reviewing lessons you must be sure that your local installation has a module that you experiment with. Module-by-module comparison of versions: for Bitrix Site Manager and for Bitrix24.

Note: the training course will include examples from the tasks that normally have to be solved by developers of various products. The mechanisms that used to solve these tasks may be applied in any other product created on Bitrix Framework. To this extent, the words site and corporate portal used in this course may be considered synonyms.

For Those Who Switched to Bitrix Framework from Other Platforms

The programmers who switched to Bitrix Framework from other platforms and CMS face additional difficulties caused by the “pressure” of previous experience.

In order to learn how to work in Bitrix Framework efficiently, you should try to understand the way other things are implemented in this system rather than compare the things you know from other systems. The “comparative” method is of no use for this course. Omit your old knowledge and study the new system using only your knowledge of PHP and site building rather than comparing ideologies and technologies. This will make it easier for you to grasp. You may indulge in comparison later, after you have mastered Bitrix Framework.

The direct comparison of Bitrix Framework and other systems does not always work. And yet these questions do arise. That is why we will include some opinions given by the partners of Bitrix and programmers working on Bitrix Framework.

Bitrix Framework and Drupal

The main structural unit of CMS Drupal is a node. As a matter of fact, any page of a website on Drupal (except for service) is either a list of node previews or a complete display of one node. Any page may be displayed together with additional blocks, but they are secondary in relation to the node anyway.

In Bitrix Framework the ideology of infoblocks is implemented. Infoblocks are structurally similar to a table in a database. Infoblock is a collection of objects with the same set of properties.

All infoblocks are equal in the sense that any infoblock (or even several infoblocks) may be used for displaying both in the primary area of the page and in additional areas. Thus, a node in CMS Drupal is just a particular case of infoblock, and this system actually has only one infoblock while Bitrix Framework may have an unlimited number of them.

Bitrix Framework and Joomla

The site templates in Bitrix Framework more or less correspond in concept to the site templates in Joomla.
Creation of a site template for Bitrix Framework using a ready-made layout consists in the selection of blocks and the placement of components instead of these blocks. Then, these components are set up for a data source and output templates are edited for them in accordance with the site layout.
Unlike Joomla, the Bitrix Framework site template has no positions for numbered modules. Therefore, a programmer cannot indicate from the administration section as to which model must be allocated to which position simply by changing a number. The placement of components in Bitrix Framework is different.
Modules in Bitrix Framework constitute a backbone for the integration of all the functions necessary for programmers in a single place and their separation by versions. Extensions perform the same function in Joomla.
A module in Joomla is a component in Bitrix Framework. A component obtains data from somewhere and displays them as necessary. A component template is responsible for proper displaying.
One component may have several templates that display information differently. For example, if you need to display news and articles on the site, you should create two folders on the disk, put the News integrated component into each folder, and set them up for a data source. After that, you can revise templates.
Dynamic and static data are separated in Bitrix Framework. There are clearly dynamic blocks, for example a catalog of goods. There are static blocks. And there are mixed blocks. However, in order to display dynamic information, e.g., a catalog of goods, you must build a “house” for it – a folder on the disc where a “catalog” integrated component will be located and process references to dynamic information.

Glossary

Each platform uses its own terminology. In order to find your way around documentation and training courses, when communicating with developers it is advisable to explain your difficulties in a language that is understandable to specialists instead of using lay terms. A glossary of system terms and several general terms extensively used in the system is provided below for your convenience.

Program instance
Portal
Site
Site template
Site section
Component
Update system
Component path
Areas to Be Included
Language
Language file
Page template
Prologue
Epilogue
Page body
Navigation chain (breadcrumbs)

Administrative part
Public part
Revision mode
Index page (file)
User
Group of users
Multilanguage interface
Meta tag
Localization
Host
Domain name (domain)
IP address
Accept-Language
Unix-format time
Rights in Unix systems
Root-related path

Full path
Absolute path
DocumentRoot
Submit
Session
HTML-safe type
Variable binding
Dump
cron
Buffering
Persistent connection
Mail event
Mail event type
Mail template
Customization
API (SDK)

Term	Description
Program instance	A copy of the product consisting of the product’s source code and only one copy of the structure and database tables included in the product and also any product’s instruction for use.

Portal One set of files stored in the directory /bitrix/modules/ and one copy of the base. The portal comprises one or more sites. The following expressions may be used as synonyms of this term: “product instance,” “one system installation,” and “one system copy.”

Site

A set of the following notions:

Database account is created in the Sites administrative menu and includes the following main parameters:
- Identifier – a set of symbols identifying the site;
- Domain name – one or more domain names of the site;
- Site folder – a path to the catalog where the public part of the site will be stored;
- Language of the site;
- Date and time format;
- URL - a default protocol and domain name (for example: http://www.site.com);
- DocumentRoot - if multi-siting is organized on different domains, this parameter must contain a path through the server file system to the site root;
- Template connection conditions – each site may have one or more templates for reflecting scripts of its public part, each of such templates may be connected according to a certain condition;
Public part – is a set of scripts (pages) located in the “site folder” and belonging to this site;
Settings – each module may have a number of settings associated with the site; for example the settings of the Information Blocks module represent the binding of an information block to a certain site, and the settings of the Helpdesk module determine the binding of a status, category, etc. to the site.

Site template

The synonyms are site design and site skin. Several different templates can be used to display one site. A site template includes the following:

a set of files in the directory /bitrix/templates/template_ID/, where template_ID is an ID field in the form of a site template editing. The structure of this directory is as follows:
- /components/ - directory with components belonging to a certain module;
- /lang/ - language files belonging both to this template in general and to separate components;
- /images/ - a directory with images used in this template;
- /page_templates/ - a directory with page templates and their description stored in the file .content.php;
- /include_areas/ - a directory with content files of the areas to be included;
- header.php - is a prologue of this template;
- footer.php - is an epilogue of this template;
- styles.css - CSS styles applied on the site pages when this template is used;
- template_styles.css - CSS styles used in the template itself;
- .menu type.menu_template.php - a template for displaying menu of a relevant type;
- chain_template.php - a default template for display of navigational chain;
- and also a number of other auxiliary random files included in this template.

Site section A directory in the server file system. Site structure in Bitrix Framework is a server file system, which is why the files constitute site pages and, accordingly, directories constitute site sections.

Component

This is a part of a certain module. It represents a logically completed code stored in one file which accepts a number of parameters, performs a number of actions, and displaying a result (for example, in the form of HTML code). It is strongly recommended to use components for the organization of information display both in public and in administrative parts. The term component comprises the following elements:

master file connects using the function CMain::IncludeFile which represents a PHP script implementing the logic of component;
language files - are used in component to display its result in different languages;
description - is a PHP code used by visual editor to manage component and its parameters.

Nowadays, version 2.0 of the components is used. The use of components from 1.0 is not recommended but they are still used on the sites built on earlier versions of the system.

Update system

The technology SiteUpdate permits the following:

Download product updates;
Upload new modules and updates for existing modules to extend their functionality;
Upload language files and install new languages;
Register licenses for additional sites.

The data shall be downloaded from the site of Bitrix, Inc. through the web interface of the administrative section of the product. During the update only core of the product is modified (files contained in the folders /bitrix/modules/, /bitrix/tools/, /bitrix/admin/, and /bitrix/components/bitrix/). The update does not affect the public part of the portal completely eliminating the risk of data loss.

The system is updated in several steps:

The update system automatically requests a license key of the product;
Next, a check of the available updates is performed;
Then, a user is offered to select updates for downloading;
After that, selected updates are downloaded.

All updates and new modules are compressed first and then downloaded to the owner’s site.

Component path

This is used in the function CMain::IncludeFile as a first parameter and represents a path to the master file of a component in respect to one of the following directories (in order of priority):

/bitrix/templates/site_template_ID/;
/bitrix/templates/.default/;
/bitrix/modules/module_ID/install/templates/

Where:
Site_template_ID is an identifier of the current site template,
Module_ID - is an identifier of the module to which the component belongs.

Areas to Be Included This is a specially selected area on a site page that may be edited independently from the primary contents of the page. It is implemented using a special software component.

Language

It is an account in the database that is accessible for editing in the administrative menu on the Interface Languages page with the following fields:

Both in the public and administrative parts, language is primarily used in work with language files.
In the administrative part, the language determines the time and date format and page encoding (in the public part these parameters are determined by the site settings).

Language file This is a PHP script containing translations of language phrases into a certain language. This script consists of a $MESS array with keys that are identifiers of language phrases and values that are translations into a relevant language. For each language there is a certain set of language files which, as a rule, are stored in the directories /lang/.
As a rule, language files are used in the administrative scripts of modules and in components.
The module Localization is intended for work with language files.

Page template

This is a file stored in one of the directories:

/bitrix/templates/site_template_ID/page_templates/
/bitrix/templates/.default/page_templates/

This file represents a blank for a public page. As a rule, it is used for creating a new page in the Site Explorer module. For the creation of the procedure for page template sorting of the file .content.php located in one of the aforementioned directories is used.

Prologue

Generally, this term means the top left part of a page.

For the public part the prologue of the relevant site template is stored in the file /bitrix/templates/site template ID/header.php.

For the administrative part the prologue is stored in the file /bitrix/modules/main/interface/prolog_admin.php.

In its turn, the prologue may be divided into a service and a visual part. In the service part, all the necessary classes are connected, connection with the base is established, and a number of service instances of objects such as $USER, $APPLICATION, etc. are created. In the visual part, top left part of the page is displayed.

If an undivided prologue must be connected in the public part, we use the following code:

require($_SERVER["DOCUMENT_ROOT"]."/bitrix/header.php");

If due to any reasons we have to divide the prologue into a service (prolog_before.php) and a visual (prolog_after.php) part, we use the following codes:

require($_SERVER["DOCUMENT_ROOT"].
"/bitrix/modules/main/include/prolog_before.php");
...
require($_SERVER["DOCUMENT_ROOT"].
"/bitrix/modules/main/include/prolog_after.php");

Epilogue

Generally, this term means the bottom right part of a page.

For the public part, the epilogue of the relevant site template is stored in the file /bitrix/templates/site template ID/footer.php.

For the administrative part, the epilogue is stored in the file /bitrix/modules/main/interface/epilog_admin.php.

In its turn, the epilogue may be divided into a service and a visual part. Some actions like sending mail messages, execution of OnAfterEpilog event handlers, etc. are performed in the service part. In the visual part, the bottom right part of the page is displayed.

If an undivided epilogue must be connected in the public part, we use the following code:

require($_SERVER["DOCUMENT_ROOT"]."/bitrix/footer.php");

If due to any reasons we have to divide the epilogue into a visual (epilog_before.php) and a service (epilog_after.php) part, we use the following codes:

require($_SERVER["DOCUMENT_ROOT"].
"/bitrix/modules/main/include/epilog_before.php");
...
require($_SERVER["DOCUMENT_ROOT"].
"/bitrix/modules/main/include/epilog_after.php");

Page body Page body is a part of the PHP/HTML code located in the script between the connections of the prologue and epilogue. Page body is not a part of the site template and represents the individual contents of a public or administrative page.

Navigation chain (breadcrumbs) It is a design element intended primarily for improving navigation on the site. Navigation chain is displayed in the visual part of the prologue and consist of headers of site sections with relevant links to them. In addition to automatically added section headers you can also add arbitrary points to a navigation chain.

Administrative part

This is a system section containing an interface for managing system modules and structure, contents, visitors, and other components of the site. It consists of numerous scripts in which the administrative prologue and epilogue are connected. Their connection means the following:

This page does not belong to any site;
At the same time it belongs to a module;
It has a strictly determined administrative interface;
All localization parameters of this page depend on a selected current language;
Additional verification of rights established in the settings of a relevant module is used on this page.

Public part

This is a system section available for displaying to site visitors. Generally, this term means numerous scripts in which the prologue and epilogue of one of the site templates are connected. Their connection means the following:

This page belongs to a site;
It has an interface of a current site template;
All localization parameters of this page depend on the current site.

Revision mode A mode when the current page of the public section is displayed in a special form: the components used, areas to be included, areas to be revised, etc. are marked. Each such area has a set of buttons to quickly switch to the editing of this page element.

Index page (file)

This is a file name to be used by web server if the requested URL ends with a slash and contains no file name. There are different ways to establish the index page search order for different web servers, for example:

Apache - in the file httpd.conf, parameter DirectoryIndex;
IIS - in site properties, tab Documents > Enable default content page;

Unfortunately, the value of this parameter is unavailable in PHP. That is why the function GetDirIndex must be used to determine the index page in the code.

User

An entry in the database containing parameters of a registered user with such mandatory fields as:

Login;
Password;
E-Mail,

and also a number of additional fields containing a user’s personal information, information about a user’s work, and administrative notes.

Registration data (login and password) indicated by the user during registration or obtained by the user automatically (e.g., after importing) will be used for authorization in the system. Following registration, the user is allocated to a specific group and receives the right to access portal resources in accordance with the rights granted to such group.

Group of users A number of portal users having certain rights to access and manage portal resources (e.g., users of the Moderators group have the right to read and edit forum messages). Groups of users are managed on the page Group of users in the administrative section (Control Panel > Settings > Manage users > User groups).

Multilanguage interface

The functionality is implemented by using language files containing a translation of the phrases into the relevant languages for the following:

Administrative section;
Error messages;
Visual components;
Relevant areas in the portal template;
etc.

Necessary language files are connected in accordance with the current interface language. As a result, messages are displayed to the user in a language selected by the user. Switching between the languages of the administrative interface is possible using relevant buttons on the administrative panel.

Meta tag A meta tag is one of the HTML elements that permit you to set information about a page. For example, to indicate page encoding, its keywords, author, and to give a short description of the page. As a rule, the contents of meta tags are used for service purposes, for example by web crawlers indexing the site. Meta tag is determined inside the tag <head>.

Localization Means provision of information translated into a relevant language, in the appropriate encoding of this language, and using appropriate data format characteristic for such a language (e.g., date, time, monetary units, numbers, etc.).

Host This is applicable to functions of the main module, this term means a domain name or IP address that may be used to access a site.

Domain name (domain) Strictly speaking, it is one of the fields of the DNS (domain name service) table that contains a strongly structured name of the Internet site given according to specific rules. The principal task of the DNS table is the association of domain names with the site's IP addresses. An example of a domain name: bitrixsoft.com.

IP address It is a “name” of the computer in the network given according to the rules of TCP/IP protocols. IP address consists of 4 octets. One part of these octets identifies the subnet where the computer is located, and another part identifies this computer directly within a relevant subnet. An example of an IP address: 198.63.210.79.

Accept-Language A set of languages installed in a browser of a site’s visitor. For example, in MS Internet Explorer they may be installed in the menu Tools > Internet Options > General > Languages. In Mozilla Firefox: Tools > Options > General > Languages.

Unix-format time A number of seconds passed since January 1, 1970, accurate up to a microsecond. Nowadays, the Unix-format time may be fixed only up to the year 2038.

Rights in Unix systems

Three types of rights – read, write, and execute are supported in the operating systems similar to Unix (which are presently predominate for Internet servers). These rights are allocated to each file or directory. The rights are repeated thrice: for the file owner, for the users’ group to which the owner belongs, and for all other users. As a rule, the rights are indicated in numerical format:

4 - read;
2 - write;
1 - execute.

The sum of these numbers gives a final set of rights; e.g. 6 is read and write but without execute; 7 – all rights; 5 – read and execute.

Thus, e.g., the right 764 will mean: 7 – all rights for the file owner, 6 – read and write for the users’ group to which the file owner belongs, and 4 – read for all other users.

In PHP, all rights are indicated as octal numbers, and they must be given indicating prefix 0 without fail. Example: 0755.

Root-related path A path to a file starting from the catalog indicated in the parameter DocumentRoot in the web server settings established according to the rules of forming URL addresses. Example: /en/about/index.php.

Full path Includes protocol, domain, port, and a root-related path to a page (catalog). Example: http://www.bitrixsoft.com/en/about/index.php.

Absolute path An absolute path to a file includes a DocumentRoot and a root-related path.

DocumentRoot

A path to the site root in the server file system. It shall be set in the web server settings, for example:

for Apache – in the file httpd.conf, parameter DocumentRoot;
for IIS – in the site properties; tab Home Directory > Local Path.

Submit Submission of HTML form data to server.

Session This term shall mean a PHP session. The session may open at the time of visiting the site and close when the browser window is closed. Also, a new session opens once a user has gone through authorization, and closes when a user terminates the authorization session (logs off). One “site visit” can be considered a synonym for the “session” term.

HTML-safe type

As a rule, this term shall apply to the text where the following replacements have been made:

Source	Result
<	<
>	>
"	"
&	&

Such replacements permit to display text inside HTML code without the risk that it will be interpreted by a browser as part of such HTML code.

Variable binding As applicable to SQL requests, this term means the binding of variable names (or table fields) with their values. As a rule, such technology is used for the BLOB, CLOB, LONG, etc. type fields intended for storage of big volumes of data.

Dump As applicable to the data base, this term means the downloading of contents and, possibly, the table structure into a file in a specific format for their further upload back to the same or any other base. Each base has its own utilities for dumping. For example, in MySQL the mysqldump utility permits downloading in the format of regular SQL requests.
As applicable to variables, dump means displaying the structure and contents of a variable as a text.

cron In operating systems similar to Unix, the cron utility permits to arrange for script execution according to a clearly established schedule.

Buffering This term in PHP means such a mode that all outgoing data flow from PHP script (e.g., HTML code) is tentatively stored in memory without being submitted to the user’s browser. Buffering in PHP may be activated using the function ob_start. Later on, buffering may be deactivated e.g. by using the function ob_end_flush; in this case, all accumulated data will be sent to the browser. Buffering permits you to arbitrarily manipulate outgoing data flow and serves as a basis for the deferred function technology.

Persistent connection When the connection with the base is created, a descriptor is set up in the memory for this connection. If the connection is normal, then after the execution of a script this descriptor is eliminated; and if the connection is persistent, the descriptor remains and can be used by other processes, if necessary. The advantage of a persistent connection is that it normally works faster. But there is also a drawback: the number of opened persistent connections is limited in the database settings and in case this limit is exceeded the visitor will not be able to enter the site until new connections are released.

Mail event This is a mail message that has its own type and is sent using relevant mail template. Mail event initiates fields of mail event type with specific values. The procedure for layout of these fields in a letter and also text of the letter is determined by mail template.
The class CEvent is intended for the creation of a mail event. It is used in the mail system.

Mail template This determines text of mail message and also procedure for layout of fields (placeholders) set in the type of mail event.
Mail templates are available in the administrative section on the page E-mail templates (Control Panel > System settings > Email Events > E-Mail templates).
The class CEventMessage is intended for manipulation of mail templates. It is used in the mail system.

Mail event type Determines a set of special fields (placeholders) that may be used in a mail template. At the time of the creation of a mail event these fields will be initiated with specific values.
The class CEventType is intended for the manipulation of mail events. It is used in the mail system.

Customization Change of behavior of a component or component template according to specific tasks.

API (SDK) Each system module contains a set of high-level functions for data retrieval in the public section of the site and a set of classes with low-level methods for more specialized work with module data. Detailed information on the API of each module is presented in the documentation for developers.

When specifying the PHP condition for choosing the site template, it should be considered that the use of section properties is allowed, while page properties are not allowed. This is because the section properties are stored in a separate file .section.php, and the page properties are specified usually in a page body, after the including the prologue service section.

Page Structure

A site page is formed dynamically based on the page template used, data retrieved by the components, and the statistic information located on the page. The creation of site templates and the allocation of components in them are taken care of by site developers.

Top and bottom parts of the design are formed based on the site design template. I.e. the information displayed in these areas is determined by the parameters of the site template.

Thanks to the technology of deferred functions a part of visual elements displayed in the prolog may be set in the page body. These are such elements as:

The key feature of this technology consists in its possibility to defer the performance of certain functions by performing them in the epilog, with the results of their performance substituted to the aforementioned code.

A number of tasks cannot be resolved using the technology of deferred functions, for example when certain actions must be performed in the Prolog with values that in the previous example would be set in the page body (for example, page properties). In this case, the prolog must be divided into a service and a visual part, and the values must be set between them.

The service part of the prolog has a particularity that it does not display any data (does not send the header to the browser).

In the visual part of the prolog the file /bitrix/templates/site template ID/header.php is connected, where site template ID is the identifier of the current site template. This file stores top left part of the current site template.

In the visual part of the epilog the file /bitrix/templates/site template ID/footer.php is connected, where site template ID is the identifier of the current site template. This file stores bottom right part of the current site template. In addition to this, a number of invisible IFRAMEs used by the technology of redirection of visitors is displayed.

Tasks often occur when there is no need to connect visual parts of the prolog and epilog. In this case, the connection of service parts of the prolog and epilog will suffice.

For the correct operating of the system, the service parts of the prolog and epilog must be connected.

Templates

Each such catalog may contain the proper page template files and also the service file .content.php of which the principal task is to store descriptions and the procedure for sorting page templates. This information is stored in the $TEMPLATE array of which its structure is presented below:

The following algorithm is used during the formation of the list of page templates:

Properties

The section properties are stored in the file .section.php of the relevant catalog (site section). The page properties are set, as a rule, either in the page body or between the service and visual parts of the prolog.

The section properties are automatically inherited by all subsections and pages of this section. If necessary, you can edit the properties of any separate page of the section by correcting its parameters as needed.

CMain::ShowProperty - displays a page or section property using technology of deferred functions.

CMain::GetDirPropertyList - returns array of section properties collected recursively up to the site root.

Page and section properties are used to work with meta tags. The following functions are used to work with them:

CMain::ShowMeta - displays a page property or a section property with an HTML tag frame using a deferred function feature.

CMain::GetMeta - returns a page property or a section property with an HTML tag frame:

Parameters

Page parameters are intended to translate parameters into module functions in order to change their standard behavior. E.g., if it is necessary to deactivate the memorization of the last page in a session (when using a page by page navigation) or to change a standard data display mode in the functions of the Information Blocks module.

Page parameters are accessible only within a page. They cannot be saved either in the database or in a session.

Execution Procedure

Component and template parameters can be accessed from the component and template program modules as $arParams array. The result of work of the component program module is $arResult array submitted to the component template entry. The regular echo operator streams the resulting HTML code (and it gets incorporated into a proper place within the page).

During the work on a component and template it is possible to use the functionality of Bitrix Framework modules which, in their turn, may access the product database.

Page Execution Procedure

Page is a PHP file, consisting of a prolog, page body (main work area) and epilog:

Page has a certain structure, properties and parameters. It can use its own templates.

Language and Language Files

Both in the public and in the administrative parts the language is used first of all in order to select a specific language file.

Language determines the time and date format and page encoding in the administrative part. In the public part, these parameters are determined by the site settings.

Language Files

This script contains $MESS arrays containing language phrase identifiers with values that are translations to a relevant language.

Each language has its own set of language files stored in subcatalogs /lang/ of the system or module file structure.

As a rule, language files are used in the administrative scripts of modules or in components and are connected accordingly using one of the following functions:

For the sake of search convenience and the further modification of language phrases, the page parameter show_lang_files=Y may be used, which allows to quickly find and correct any language phrase using the module of Localization.

Examples

In order to obtain the name of the month in 2 cases instead of its sequence number:

The same procedure is applicable to the days of the week, names of the countries, etc.

Processing Techniques

Here, the general information on processing techniques and principles fed into the system is provided. The course describes those of them that are most frequently used. For information about other processing techniques and principles, please refer to the documentation.

Bitrix Framework Processing Techniques:

Control Panel toolbar

The panel is connected using the function of CMain::ShowPanel. This function applies a processing technique of deferred functions that permits you to add buttons to the panel directly in the page body.

A button may be added to the panel using the function of CMain::AddPanelButton. The same function may be used in the script /bitrix/php_interface/include/add_top_panel.php that will be automatically connected upon the invocation of the panel.

Agents

The system automatically checks the agent's availability, requiring to be launched and executes it (if required) at the end of each page upload, after passing content to a browser.

In order for an agent to be executed at a set time, it must be registered in the system using the method of CAgent::AddAgent. An agent’s registration may be deleted using the function of CAgent::RemoveAgent.

If the agent function belongs to a module, this module will be automatically connected before the execution of such an agent function. Namely, the file /bitrix/modules/module ID/include.php will be connected. In this case, you have to make sure that the agent function will be available after the connection of this file.

If an agent function doesn't belong to any module, it must be located in the file /bitrix/php_interface/init.php. This file is automatically connected in the prologue.

The particularity of agent function creation is that the agent function must return a PHP code as function's return value that will be used during the next execution of this function.

List of agents, employed in the system is available at the Agents page (Settings > System Settings > Agents).

Periodic and non-periodic agents

Historically, agents are called "periodic" and "non-periodic" which also can be named as "recurring" and "non-recurring".

The user interface within the admin panel for the agent settings likewise has remained the same:

Type of agent depends on the software developer who wrote the agent's code. This developer can create an agent that could repeat an infinite amount of times. Or only 2-3 times depending on set conditions. Example of agent function recurring infinitely:

Type of agent is defined by the method for calculating time of the next agent start:

Limits

Examples of agents

Example for creating an agent

In case when you need to dynamically add specific agents, use the agent API. Be advised, that it's easier to add one or two agents manually.

Go to the page Settings > Product Settings > Agents and click Add an Agent button on the context panel:

To activate the agent, execute the following code in the admin section PHP console:

In case of a new email, the agent is triggered and you can add you own function.

Simple agent examples

Currency rates

Practical example: Update a currency rate at the site. It's recommended to assign an agent to cron.

Specified code is added to the file /bitrix/php_interface/init.php. Do not forget to add the agent AgentGetCurrencyRate(); at the page Settings > System Settings > Agents.

Items without prices

Caching

Caching is a technology which enables to cache the results of rarely updated and resource consuming code areas (for example, those handling the database).

Performance

In case of a large database, a performance problem may occur due to the following reasons:

Multilevel caching is used precisely to relieve the most loaded places in terms of resources and time. Each caching technique may be used for each component separately by choosing an optimal option for a specific case.

If we take an Internet store as an example, then for each item of goods a file in cache memory will be created so that the server will not have to send requests to the database in case of any future queries of the buyer.

Caching

Main caching settings are located on the page Caching settings (Control Panel > Settings > System settings > Cache Settings).

Blocking mode for caching system

What is caching "blocking mode"

In some cases such approach significantly reduces load - see the load test example below.

"Blocking mode" operation time

Blocking mode is automatically triggered if at least a single condition is satisfied:

Caching mechanism operation

Files

// bitrix/.settings.php
return [
//...        
    'session' => [
        'value' => [
            'mode' => 'default',
            'handlers' => [
                'general' => [
                    'type' => 'file',       
                ]           
            ],

        ]                   
    ] 
];

Setting for divided session:

// bitrix/.settings.php
return [
//...        
    'session' => [
        'value' => [
            'lifetime' => 14400, // +
            'mode' => 'separated',  // +
            'handlers' => [
                'kernel' => 'encrypted_cookies',  // +           
                'general' => [
                    'type' => 'file',       
                ],
            ],

        ]                   
    ] 
];

Redis

// bitrix/.settings.php
return [
//...        
   'session' => [
       'value' => [
           'mode' => 'default',
           'handlers' => [
               'general' => [
                   'type' => 'redis',  
                   'servers' => [
                       [
                           'port' => 6379,
                           'host' => '127.0.0.1',
                       ],
                       [
                           'port' => 6379,
                           'host' => '127.0.0.2',
                       ],
                       [
                           'port' => 6379,
                           'host' => '127.0.0.3',
                       ],
                   ],
                   'serializer' => \Redis::SERIALIZER_IGBINARY,
                   'persistent' => false,
                   'failover' => \RedisCluster::FAILOVER_DISTRIBUTE,
                   'timeout' => null,
                   'read_timeout' => null,    
               ],          
           ],
       ]                  
   ]
];

Cluster storage of session data

Difference from standard configuration: servers have additional options: serializer, persistent, failover, timeout, read_timeout. You can find detailed information about then in the official documentation.

// bitrix/.settings.php
return [
//...        
    'session' => [
        'value' => [
            'mode' => 'default',
            'handlers' => [
                'general' => [
                    'type' => 'redis',   
                    'servers' => [
                        [
                            'port' => 6379,
                            'host' => '127.0.0.1',
                        ],
                        [
                            'port' => 6379,
                            'host' => '127.0.0.2',
                        ],
                        [
                            'port' => 6379,
                            'host' => '127.0.0.3',
                        ],
                        'serializer' => \Redis::SERIALIZER_IGBINARY,
                        'persistent' => false,
                        'failover' => \RedisCluster::FAILOVER_DISTRIBUTE,
                        'timeout' => null,
                        'read_timeout' => null,
                    ],
                ],           
            ],
        ]                   
    ] 
];

Setting for separate session:

// bitrix/.settings.php
return [
//...        
    'session' => [
        'value' => [
            'lifetime' => 14400, // +
            'mode' => 'separated', // +
            'handlers' => [
                'kernel' => 'encrypted_cookies',  // +  
                'general' => [
                    'type' => 'redis',   
    		    'port' => '6379',
    		    'host' => '127.0.0.1',
                ],           
            ],

        ]                   
    ] 
];

Memcache

// bitrix/.settings.php
return [
//...        
    'session' => [
        'value' => [
            'mode' => 'default',
            'handlers' => [
                'general' => [
                    'type' => 'memcache',   
    		    'port' => '11211',
    		    'host' => '127.0.0.1',
                ],           
            ],

        ]                   
    ] 
];

Cluster storage for session data

When you need to create a cluster from server memcache, you just need to add the servers settings.

// bitrix/.settings.php
return [
//...        
    'session' => [
        'value' => [
            'mode' => 'default',
            'handlers' => [
                'general' => [
                    'type' => 'memcache',   
                    'servers' => [
                        [
                            'port' => 11211,
                            'host' => '127.0.0.1',
                            'weight' => 1, //read more about the weight settings in the memcahe-related documentation
                        ],
                        [
                            'port' => 11211,
                            'host' => '127.0.0.2',
                        ],
                    ],
                ],           
            ],
        
        ]                   
    ] 
];

Setting for separated session:

// bitrix/.settings.php
return [
//...        
    'session' => [
        'value' => [
            'lifetime' => 14400, // +
            'mode' => 'separated', // +
            'handlers' => [
                'kernel' => 'encrypted_cookies',  // +  
                'general' => [
                    'type' => 'memcache',   
    		    'port' => '11211',
    		    'host' => '127.0.0.1',
                ],           
            ],

        ]                   
    ] 
];

Mysql

Data is stored in the table b_user_session

// bitrix/.settings.php
return [
//...        
    'session' => [
        'value' => [
            'mode' => 'default',
            'handlers' => [
                'general' => [
                    'type' => 'database',       
                ]           
            ],         
        ]                   
    ] 
];

Setting for separate session:

// bitrix/.settings.php
return [
//...        
    'session' => [
        'value' => [
            'lifetime' => 14400, // +
            'mode' => 'separated', // +
            'handlers' => [
                'kernel' => 'encrypted_cookies',  // +  
                'general' => [
                    'type' => 'database',       
                ]           
            ],         
        ]                   
    ] 
];

Handling the sessions

Bitrix24 allows handling sessions as follows:

Session storage in memcached

You need to set the following constants to enable session storage in memcached in the old core/kernel's file /bitrix/php_interface/dbconn.php:

define('BX_SECURITY_SESSION_MEMCACHE_HOST', 'localhost');
define('BX_SECURITY_SESSION_MEMCACHE_PORT', 11211);

Or when using unix-socket:

define('BX_SECURITY_SESSION_MEMCACHE_HOST', 'unix:///path/to/memcached.sock');
define('BX_SECURITY_SESSION_MEMCACHE_PORT', 0);

Then, enable session storage in the database in the proactive protection module. As a result, we get kernel-enabled session storage in memcached.

This method of session storage provides the following advantages:

no need to track the number of old sessions on the highly-loaded project;
option to individuate sessions between servers in cluster;
option to use session that's not waiting for blocking;
option to use virtual sessions.

Session storage in the database has the same advantages as the session storage in memcached. However, database storage is significantly slower. That's why we recommend using memcached for this purpose instead of database.

Non-blocking sessions

One of issues encountered in large-scale projects with multiple ajax queries is the frequently blocked hits of a single user for standby of blocked session. This is especially applicable for Bitrix24 On premise, where in many locations, files attached to entities are passed to user, after checking access permissions for PHP. That's why, a sort of "sequence" can be built due to standby for blocked session. You can enable a non-blocking session by specifying the constant,before connecting the kernel:

define('BX_SECURITY_SESSION_READONLY', true);

After this action, the session is read from memcached or database without waiting for blocking. For example, this feature is used when passing files.

Important: the session won't be recorded when using this constant upon a completed hit. This can cause possible data loss saved within a hit in session.

Virtual sessions

Non-blocking sessions are sufficient for majority of cases. However, in some cases, when we do not need the session altogether, its overly excessive to use a non-blocking session - due to an extra session being created if unavailable. As the result, a large of "trash" sessions are created in case of large amount of unassociated hits. Example of such hits are REST hits.

Virtual session was added to resolve this issue. It works as follows: a session is created in the memory, doesn't wait for blockings and is not saved. To enable it, set the constant, before connecting the kernel .

define('BX_SECURITY_SESSION_VIRTUAL', true);

Please remember that this session type is not saved anywhere. It is used when processing REST queries.

Note: If you have a Bitrix24 On premise, a project with a large number of ajax queries or a high number of files - is passed with access permission check (for example, in blogs, social network, forum). It's better to use session storage in kernel-enabled memcached.

Encrypted cookies

Encrypted [ds]cookies[/ds][di] Cookie - is a text string of information, sent to a browser by a site visitor and which is saved in file on the site visitor device. Usually, a cookie is used to determine a user unique status, last visit time, personal settings, shopping cart unique ID and etc.
[/di] (\Bitrix\Main\Web\CryptoCookie) allows sending data to user, without disclosing contents and without allowing to modify data inside. Available from main 20.5.400.

Configuration

For the kernel to be capable to encrypt the data, indicate crypto_key in the settings /bitrix/.settings.php . By default, it's generated automatically in new distribution packages.

If it's unavailable, add it manually to kernel settings file:

<?php
return [
    //...
    'crypto' => [
        'value' => [
            'crypto_key' => 'mysupersecretphrase',
            //we recommend to set 32-character string from a-z0-9,
        ],
        'readonly' => true,
    ]

    //...
];

Examples

Setting a Cookie

To set an encrypted cookie, just create an object as in the snippet below, into a desired Response:

$cookie = new \Bitrix\Main\Web\CryptoCookie('someName', 'secret value');
\Bitrix\Main\Context::getCurrent()->getResponse()->addCookie($cookie);

Because the cookie is limited in length and data is encrypted and packaged in base64, to avoid data loss, the kernel can create several cookies with encrypted value.

As the result, http response will contain cookie someName with the value -crpt-someName_0. And cookie someName_0 with already encrypted value such as DRMg6jrwXO1aUxTvdyBYyT-3_bCqomI9MMN_enurA5abplMm2OiSlNdu_1zgjbkKT_3D3uT8366.

Reading a Cookie

To get access to encrypted cookies value, it's sufficient to use standard kernel API for cookie handling

$httpRequest = \Bitrix\Main\Context::getCurrent()->getRequest();

echo $httpRequest->getCookie('someName');
//secret value

Kernel automatically determines that cookie is encrypted or not encrypted, unpackages the value and decrypts it. In case the value cannot be decrypted, gets an empty value.

External Authorization

Sometimes it may be necessary to use special checking algorithms and/or external user storage databases for the user’s authorization (verification of login and password). E.g., there is a user database and they must have the possibility to undergo authorization on a CMS managed site. In these cases, all users sometimes may be moved to the CMS database using API functions, but often it is impossible because of the following two reasons:

First. Users’ passwords in the external database are not stored in the open form, only their hash is stored; that is why after migration the users will not be able to undergo authorization due to password inconsistency.
Second. Sometimes a common user database is necessary, with users’ passwords stored on the same remote server and used for verification in several places, including CMS.

In order to resolve such tasks, Bitrix Framework provides for an option to add own external authorization to the standard incorporated authorization system. It takes several steps that we will cover in detail taking an external authorization as an example and using users’ database of a popular forum PHP BB.

For a start, let us create a file, for example, /bitrix/php_interface/scripts/phpbb.php. A class with an external handler will be located in this class, let us call it __PHPBB2Auth:

class __PHPBB2Auth
{
}

In order to have our function invoked during an authorization attempt it is necessary to set the OnUserLoginExternal event handler that will be invoked automatically each time a user enters their login and password, before the built-in check. For this, let us use the AddEventHandler function in the file /bitrix/php_interface/init.php:

AddEventHandler(
     "main", 
     "OnUserLoginExternal", 
     Array("__PHPBB2Auth", "OnUserLoginExternal"), 
     100, 
     $_SERVER['DOCUMENT_ROOT'].'/bitrix/php_interface/scripts/phpbb.php'
);

We have specified our class method __PHPBB2Auth::OnUserLoginExternal as a handler. The OnUserLoginExternal event handler accepts as a parameter a link to an array with fields for the check:

define("PHPBB2_TABLE_PREFIX", "phpbb_");
function OnUserLoginExternal(&$arArgs)
{
    $table_user = PHPBB2_TABLE_PREFIX."users";
    $table_user_group = PHPBB2_TABLE_PREFIX."user_group";
    extract($arArgs);

    global $DB, $USER, $APPLICATION;

    $strSql = "SELECT * FROM ".
              $table_user.
              " WHERE username='".
              $DB->ForSQL($login).
              "' AND user_password='".
              $DB->ForSql(md5($password))."'";
    $dbRes = $DB->Query($strSql);
    if($arRes = $dbRes->Fetch())
    {
        if($arRes['user_active']!='0')
        {
            // user’s name and password are correct
        }
    }
}

Having verified the login and password according to the PHPBB algorithm, an external user must be created in the internal database so that internal objects (news, votes, etc.) could be linked to it. To do so, let us use the method CUser::GetList() with a filter by login and external source code. If there is no such user we will create it, and if such a user exists we will update information about it.

$arFields = Array(
    "LOGIN" => $login,
    "NAME" => $login,
    "PASSWORD" => $password,
    "EMAIL" => $arRes['user_email'],
    "ACTIVE" => "Y",
    "EXTERNAL_AUTH_ID"=>"PHPBB2",
    "LID" => SITE_ID
    );
$oUser = new CUser;
$res = CUser::GetList($O, $B, Array("LOGIN_EQUAL_EXACT"=>$login, "EXTERNAL_AUTH_ID"=>"PHPBB2"));
if(!($ar_res = $res->Fetch()))
    $ID = $oUser->Add($arFields);
else
{
    $ID = $ar_res["ID"];
    $oUser->Update($ID, $arFields);
}
if($ID>0)
{
   // authorization is permitted
   return $ID;
}

Now we have a user ID in our database and it can be recovered from the handler function to make this user authorized by the system, but a new user will be anonymous, because it is not bound to any group. Let us use the binding in the PHPBB database to transfer it to our database before authorization.

$USER->SetParam("PHPBB2_USER_ID", $arRes['user_id']);
$groups_map = Array(
    /*'PhpBB2 Group ID' => 'Local Group ID',*/
     '2' => '1'
    );

$user_groups = Array();
$dbUserGroup = $DB->Query('SELECT * FROM '.$table_user_group.' WHERE user_id='.$arRes['user_id']);
while($arUserGroup = $dbUserGroup->Fetch())
    $user_groups[] = $arUserGroup['group_id'];

if(count($user_groups)>0)
{
    $arUserGroups = CUser::GetUserGroup($ID);
    foreach($groups_map as $ext_group_id => $group_id)
    {
        if(in_array($ext_group_id, $user_groups))
            $arUserGroups[] = $group_id;
        else
        {
            $arUserGroupsTmp = Array();
            foreach($arUserGroups as $grid)
                if($grid != $group_id)
                    $arUserGroupsTmp[] = $grid;
            $arUserGroups = $arUserGroupsTmp;
        }
    }
    CUser::SetUserGroup($ID, $arUserGroups);
}

That is all. Now the local user account is consistent with the remote one, a user’s code may be recovered, and it will be authorized. Let us tentatively switch off the function "remember me on this computer” if the user has enabled the checkbox, because in this case we will not be able to correctly check the access rights:

$arArgs["store_password"] = "N";
return $ID;

In order to register a new external system authorization check, the event OnExternalAuthList must be handled. Let us add a relevant invocation in the file /bitrix/php_interface/init.php:

AddEventHandler(
     "main", 
     "OnExternalAuthList", 
     Array("__PHPBB2Auth", "OnExternalAuthList"), 
     100, 
     $_SERVER['DOCUMENT_ROOT'].'/bitrix/php_interface/scripts/phpbb.php'
     );

Handler function must return the array from a set of handlers with the fields ID and NAME.

function OnExternalAuthList()
{
    return Array(
        Array("ID"=>"PHPBB2", "NAME"=>"PhpBB2")
        );
}

Now on the user editing page a drop-down list indicating external authorization sources appears. We provide the entire text of the file /bitrix/php_interface/scripts/phpbb.php below. A reverse mechanism is additionally implemented in it: once authorized in our system, a user is automatically authorized in the forum.

<?
define("PHPBB2_TABLE_PREFIX", "phpbb_");

class __PHPBB2Auth
{
    function OnUserLoginExternal(&$arArgs)
    {
        ////////// <settings> ////////////
        $table_user = PHPBB2_TABLE_PREFIX."users";
        $table_user_group = PHPBB2_TABLE_PREFIX."user_group";
        $groups_map = Array(
            /*'PhpBB2 Group ID' => 'Local Group ID',*/
            '2' => '1'
            );
        ////////// </settings> ////////////
        extract($arArgs);

        global $DB, $USER, $APPLICATION;

        $strSql = "SELECT * FROM ".
                  $table_user.
                  " WHERE username='".
                  $DB->ForSQL($login).
                  "' AND user_password='".
                  $DB->ForSql(md5($password))."'";
        $dbRes = $DB->Query($strSql);
        if($arRes = $dbRes->Fetch())
        {
            if($arRes['user_active']!='0')
            {
                $arFields = Array(
                    "LOGIN" => $login,
                    "NAME" => $login,
                    "PASSWORD" => $password,
                    "EMAIL" => $arRes['user_email'],
                    "ACTIVE" => "Y",
                    "EXTERNAL_AUTH_ID"=>"PHPBB2",
                    "LID" => SITE_ID
                    );
                $oUser = new CUser;
                $res = CUser::GetList($O, $B, 
                                      Array("LOGIN_EQUAL_EXACT"=>$login, 
                                            "EXTERNAL_AUTH_ID"=>"PHPBB2"));
                if(!($ar_res = $res->Fetch()))
                    $ID = $oUser->Add($arFields);
                else
                {
                    $ID = $ar_res["ID"];
                    $oUser->Update($ID, $arFields);
                }

                if($ID>0)
                {
                    $USER->SetParam("PHPBB2_USER_ID", $arRes['user_id']);

                    $user_groups = Array();
                    $dbUserGroup = $DB->Query('SELECT * FROM '.
                                              $table_user_group.
                                              ' WHERE user_id='.$arRes['user_id']);
                    while($arUserGroup = $dbUserGroup->Fetch())
                        $user_groups[] = $arUserGroup['group_id'];

                    if(count($user_groups)>0)
                    {
                        $arUserGroups = CUser::GetUserGroup($ID);
                        foreach($groups_map as $ext_group_id => $group_id)
                        {
                            if(in_array($ext_group_id, $user_groups))
                                $arUserGroups[] = $group_id;
                            else
                            {
                                $arUserGroupsTmp = Array();
                                foreach($arUserGroups as $grid)
                                    if($grid != $group_id)
                                        $arUserGroupsTmp[] = $grid;
                                $arUserGroups = $arUserGroupsTmp;
                            }
                        }
                        CUser::SetUserGroup($ID, $arUserGroups);
                    }
                    $arArgs["store_password"] = "N";

                    return $ID;
                }
            }
        }
    }

    function OnExternalAuthList()
    {
        return Array(
            Array("ID"=>"PHPBB2", "NAME"=>"PhpBB2 Board")
            );
    }

    function OnAuthorize(&$arArgs)
    {
        extract($arArgs);

        global $DB, $APPLICATION, $USER;
        $user_id = $USER->GetParam("PHPBB2_USER_ID");
        if($user_id<=0)
            return;
        $table_user = PHPBB2_TABLE_PREFIX."users";
        $table_sessions = PHPBB2_TABLE_PREFIX."sessions";
        $table_config = PHPBB2_TABLE_PREFIX."config";

        $dbConfig = $DB->Query("SELECT * FROM ".
                               $table_config.
                               " WHERE config_name
                                 IN ('cookie_name', 'cookie_path', 'cookie_domain', 'cookie_secure')");
        while($arConfig = $dbConfig->Fetch())
            ${$arConfig['config_name']} = $arConfig['config_value'];

        if (isset($HTTP_COOKIE_VARS[$cookie_name . '_sid']) || 
            isset($HTTP_COOKIE_VARS[$cookie_name . '_data']))
            $session_id = isset($HTTP_COOKIE_VARS[$cookie_name . '_sid']) ? 
                               $HTTP_COOKIE_VARS[$cookie_name . '_sid'] : '';

        $ip_sep = explode('.', $_SERVER['REMOTE_ADDR']);
        $user_ip = sprintf('%02x%02x%02x%02x', $ip_sep[0], $ip_sep[1], $ip_sep[2], $ip_sep[3]);
        $current_time = time();
        $sql =
            "UPDATE ".$table_sessions." SET ".
            "    session_user_id = ".$user_id.", ".
            "    session_start = ".$current_time.", ".
            "    session_time = ".$current_time.", ".
            "    session_page = 0, ".
            "    session_logged_in = 1 ".
            "WHERE session_id = '".$DB->ForSQL($session_id)."' ".
            "    AND session_ip = '".$user_ip."'";

        $r = $DB->Query($sql);
        if($r->AffectedRowsCount()<=0)
        {
            $session_id = md5(uniqid($user_ip));
            $sql =
                "INSERT INTO ".
                $table_sessions.
                "(session_id, session_user_id, session_start, session_time, session_ip, session_page, session_logged_in)".
                "VALUES ('".$session_id."', ".$user_id.", ".$current_time.", ".$current_time.", '".$user_ip."', 0, 1)";
            $DB->Query($sql);
        }

        $sql =
            "UPDATE ".$table_user." SET ".
            "    user_session_time = ".$current_time.", ".
            "    user_session_page = 0, ".
            "    user_lastvisit = ".$current_time." ".
            "WHERE user_id = ".$user_id;

        $DB->Query($sql);

        $sessiondata = Array('userid' => $user_id);

        setcookie($cookie_name.'_data', 
                  serialize($sessiondata), 
                  $current_time + 31536000, 
                  $cookie_path, 
                  $cookie_domain, $cookie_secure);
        setcookie($cookie_name.'_sid',
                  $session_id, 0, $cookie_path, 
                  $cookie_domain, $cookie_secure);
    }
}
?>

The following lines must be added to /bitrix/php_interface/init.php:

<?
AddEventHandler(
    "main", 
    "OnUserLoginExternal", 
    Array("__PHPBB2Auth", "OnUserLoginExternal"),
    100, 
    $_SERVER['DOCUMENT_ROOT'].'/bitrix/php_interface/scripts/phpbb.php'
    );

AddEventHandler(
    "main", 
    "OnExternalAuthList", 
    Array("__PHPBB2Auth", "OnExternalAuthList"),
    100,
    $_SERVER['DOCUMENT_ROOT'].'/bitrix/php_interface/scripts/phpbb.php'
    );

AddEventHandler(
    "main", 
    "OnAfterUserAuthorize", 
    Array("__PHPBB2Auth", "OnAuthorize"),
    100
    );
?>

As an example, here is another script for external authorization – for the Invision Power Board forum:

<?
define("IPB_TABLE_PREFIX", "ibf_");
define("IPB_VERSION", "2");

AddEventHandler("main", "OnUserLoginExternal", Array("__IPBAuth", "OnUserLoginExternal"));
AddEventHandler("main", "OnExternalAuthList", Array("__IPBAuth", "OnExternalAuthList"));

class __IPBAuth
{
    function OnUserLoginExternal(&$arArgs)
    {
        extract($arArgs);

        ////////// <settings> ////////////
        $table_user = IPB_TABLE_PREFIX."members";
        $table_converge = IPB_TABLE_PREFIX."members_converge";
        $groups_map = Array(
            /*'IPB Group ID' => 'Local Group ID',*/
            '4' => '1'
            );
        ////////// </settings> ////////////

        global $DB, $USER, $APPLICATION;

        if(IPB_VERSION == '1')
        {
            $strSql = "SELECT * FROM ".$table_user." WHERE name='".$DB->ForSql($login)."' AND password='".md5($password)."'";
        }
        else
        {
            $strSql =
                "SELECT t1.* ".
                "FROM ".$table_user." t1, ".$table_converge." t2 ".
                "WHERE t1.name='".$DB->ForSql($login)."' ".
                "    AND t1.email = t2.converge_email ".
                "    AND t2.converge_pass_hash = MD5(CONCAT(MD5(t2.converge_pass_salt), '".md5($password)."'))";
        }

        $dbAuthRes = $DB->Query($strSql);
        if($arAuthRes = $dbAuthRes->Fetch())
        {
            $arFields = Array(
                "LOGIN" => $login,
                "NAME" => $arAuthRes['title'],
                "PASSWORD" => $password,
                "EMAIL" => $arAuthRes['email'],
                "ACTIVE" => "Y",
                "EXTERNAL_AUTH_ID"=>"IPB",
                "LID" => SITE_ID
                );

            $oUser = new CUser;
            $res = CUser::GetList($O, $B, Array("LOGIN_EQUAL_EXACT"=>$login, "EXTERNAL_AUTH_ID"=>"IPB"));
            if(!($ar_res = $res->Fetch()))
                $ID = $oUser->Add($arFields);
            else
            {
                $ID = $ar_res["ID"];
                $oUser->Update($ID, $arFields);
            }

            if($ID>0)
            {
                $USER->SetParam("IPB_USER_ID", $arAuthRes['id']);

                $user_group = $arAuthRes['mgroup'];
                $arUserGroups = CUser::GetUserGroup($ID);
                foreach($groups_map as $ext_group_id => $group_id)
                {
                    if($ext_group_id==$user_group)
                        $arUserGroups[] = $group_id;
                    else
                    {
                        $arUserGroupsTmp = Array();
                        foreach($arUserGroups as $grid)
                            if($grid != $group_id)
                                $arUserGroupsTmp[] = $grid;
                        $arUserGroups = $arUserGroupsTmp;
                    }
                }
                CUser::SetUserGroup($ID, $arUserGroups);
                $arArgs["store_password"] = "N";

                return $ID;
            }
        }
    }

    function OnExternalAuthList()
    {
        return Array(
            Array("ID"=>"IPB", "NAME"=>"Invision Power Board")
            );
    }
}
?>

This script must be connected in /bitrix/php_interface/init.php to become operable.

Mail subsystem

Mail subsystem is the technology used to handle e-mail messages within a site.

The mail system operation includes the following stages:

Creating a mail event type. A mail event type can be created using the function CEventType::Add only.
Creating a mail template. Can be accomplished in the administrative menu Mail templates, as well as using the CEventMessage::Add function.
Creating a mail event. A mail event can be created using the function CEvent::Send only.

When a page finishes execution, the function CEvent::CheckEvents is called automatically. This function is used to accomplish the following main tasks:

select unprocessed mail events from the table b_event;
use the above selected events to generate e-mail messages;
send these messages;
write one of the following values as the send result to the table b_event in the field SUCCESS_EXEC:

CEvent::CheckEvents

Developers can affect sending messages by modifying the following settings of the Main (Kernel) module:

Convert Unix new line symbols to Windows format during email sending
Convert 8-bit characters in the message header
One or comma-separated list of E-mail addresses to receive copies of all the outcoming messages
E-mail address in caption
Send email event and template identifiers in message

Besides the above parameters, the constant ONLY_EMAIL can be used. If initialized, it allows sending all messages only to the specified address or group of addresses.

Example of creating the mail event type:

Add(array(
    "EVENT_NAME"    => "ADV_BANNER_STATUS_CHANGE",
    "NAME"          => "Banner status changed",
    "SITE_ID"       => "en",
    "DESCRIPTION"   => "
        #ID# - banner ID
        #CONTRACT_ID# - contract ID
        #TYPE_SID# - type ID
        "
    ));
?>

Example of creating the mail template:

Add($arr);
?>

Example of creating the mail event:

 124,
    "CONTRACT_ID" => 1,
    "TYPE_SID"    => "LEFT"
    );
CEvent::Send("ADV_BANNER_STATUS_CHANGE", 
             array("de", "en"), $arFields);
?>

Balancing queries in cluser

Starting from the main module version 24.0.0 the query balancing system in cluster has been [dw]improved significantly[/dw][di] The previous balancing system system version had any query update interrupting the conveyor process and all queries were submitted to the main (master) database. [/di], optimizing load between servers.

Main updates

The system functions in a standard mode before the first query for data update.
In case of an update query, list of modified tables is registered.
Upon subsequent retrieving queries, the updated tables are checked. If no tables were modified, queries will continue to be processed via slave servers.

Tests demonstrate significant increase of queries, processed by slave servers and minimized errors when handling cluster configuration. This allows for better distribution of queries between servers and reduced load on master server.

Load balancing

Legacy (standard) variant: Master 30 la, Slave 3 la.
New variant: Master 1 la, Slave 50 la.

Now cluster settings allow to redirect 100% of load to slave servers, which significantly increases system performance and effectiveness.

Core D7

Development Purpose is the creation of a new software core at a new technology level while eliminating “layers” of outdated technology.

The compatibility principle to which Bitrix, Inc. must adhere to made it necessary to perform a large scope of work not directly intended to develop Bitrix Framework. It immediately affected the speed and quality of development of the platform itself and implicitly affected the distribution of the company’s products in the market.

Actually, the new core is a new development method. At the same time, all old API continues working in the product. And a new API is added for development in a new style. Gradually the old API must become something like an adaptor that ensures compatibility. And all logic with relevant refactoring must move to a new core.

Technical Requirements

The minimal technical requirements for the product version 18.5.400 (with core D7):

PHP version 7.1.
MySQL version 5.6.

Main Differences from the Old Core

Database
- The following databases are supported: MySQL and NoSQL.
- Abandoning the inefficient driver MSSQL ODBC, only native driver is supported.
- ORM (query builder) with noSQL is used.
Object-Oriented Programming (OOP)
- Strong engagement. All code belonging to a certain area must be concentrated in a single place, in the same class, and in the same class set.
- Components with OOP (class.php) have the possibility to write a more structured component code and a possibility of inheritance.
Development
- Consistent code. All equal queries have the same name, the same sets of parameters, and return unified data. I.e. GetList of users does not differ from GetList of groups of users.
- Support of name spaces.
- New uniform rules of code formatting with strict control at the level of development.
- Abandoning of global variables.
- Support of exceptions.
- Support of new types: date, time, and files. Classes with methods replace unformatted data. The values of these types are objects with formatting methods, etc.
- Class library.
- Unified events. A possibility of modification and integration using handlers.
- Autoload. All system entities are located in previously determined places; accordingly, an autoload is supported without additional actions on the part of the developer.
- Specialized handlers (classes, entities) for different situations – types of applications (http, cli).
- Deferred load of language files. Files from /lang files are not connected simultaneously with a component connection; they are loaded after the first query of a language phrase.
- Object providers for main operations (cache, log).o Object providers for main operations (cache, log).

Core Parameter Setup

Special file

Bitrix Framework has several specific core settings that do not have an edit interface. Such design choice is due to occurrences when settings update or error in them can easily lead to rendering the whole system inoperable (due to database connection setting, caching settings and etc.).

Settings in a Core D7 are entered in the file /bitrix/.settings.php. Please be advised, that in the old core/kernel similar settings were made in the file \bitrix\php_interface\dbconn.php. The file .settings.php differs significantly from the former dbconn.php in terms of structure.

Note: due to the fact that the system uses 2 cores in parallel - old kernel and the new D7, both settings files are used simultaneously. That's is why you must configure both files.

Even if you are using the old kernel's code, the file .settings.php is still must be created. A situation is possible when upon installing the updates, some of the in-built system mechanisms will be re-written to the new core. If this file is not configured correctly, it could lead to system inoperability.

In some cases, the .settings.php file is missing. It can be created automatically, via executing it in [dw]command line[/dw][di]PHP Command line - system tool, allowing to launch arbitrary code on PHP with function calls. [/di]: Bitrix\Main\Config\Configuration::wnc();.

Parameters can be edited via the Configuration class (Bitrix\Main\Config\Configuration).

Note: Some sections of the setting file contain the readonly parameter. This parameter means that these settings will not be amended through API.

In addition, these settings can be specified in the file .settings_extra.php. Basic settings file contains invariable settings, with available API. File .settings_extra.php can contain arbitrary code that changes settings dynamically. Accordingly, it doesn't have API functions.

Parameter description

Below are parameters that can be modified:

Parameters that may be changed are described below:

cache section

exception_handling section

connections section

root section

pull section

http_client_options section

services section

Cache Section

Responsible for caching settings and permits to set the caching method and its parameters.

Before version 18.5.200, the old record format was as follows:
'cache' => array ( 'value' => array ( 'type' => 'files', ), 'readonly' => false, ),

In the version 18.5.200 the record format was updated simultaneously with the option to use Redis in caching. Presently, both formats are operational, however vendor strongly recommends to use new record format.

Examples of new record format for various caching methods.

Parameter Value

type

The following can be set as values:

memcache
eaccelerator
apc
xcache
files
[dw]redis[/dw][di]From version 18.5.200.[/di]
none

or indicate arrays with values:

class_name - a class implementing ICacheEngine interface,
required_file - an add-on file with a path starting from bitrix or local (if required),
required_remote_file - an add-on file with an absolute path (if required).
extension - attempts to connect extension via extension_loaded. Only when successful, then connects already specified class.

cache_flags

Restriction on caching or updating the ttl. Set keys that include table name and suffixes:

'cache_flags'=>   array(
      'value'=> array(
         "b_group_max_ttl" => 200,
         "b_group_min_ttl" => 100,
      )
   ),

By setting the b_group_max_ttl = 0, administrator restricts caching for this entity. By setting the b_group_min_ttl = 86400, admin expands our TTL for up to 24 hours (if the code contains 3600).

Note: In addition to type there may be additional parameters if a specific caching class requires them.

Note: The memcache settings may also be set in the file /bitrix/.settings_extra.php.

Sample file /bitrix/.settings_extra.php

Base file .settings.php contains invariable settings that have API functions. The file .settings_extra.php may contain arbitrary code that updates settings depending on various factors. Accordingly, this file doesn't contain API for setting updates. Naturally, array with the same base file structure will be returned upon executing this arbitrary code.

Section exception_handling

Responsible for exception handling.

  'exception_handling' => array (
    'value' => array (
      'debug' => false,
      'handled_errors_types' => E_ALL & ~E_NOTICE & ~E_STRICT & ~E_USER_NOTICE,
      'exception_errors_types' => E_ALL & ~E_NOTICE & ~E_WARNING & ~E_STRICT & ~E_USER_WARNING & ~E_USER_NOTICE & ~E_COMPILE_WARNING & ~E_DEPRECATED,
      'ignore_silence' => false,
      'assertion_throws_exception' => true,
      'assertion_error_type' => 256,
      'log' => array (
        'settings' => array (
          'file' => 'bitrix/modules/error.log',
          'log_size' => 1000000,
        ),
      ),
    ),
    'readonly' => false,
  ),

Parameter	Value
debug	The key is responsible for displaying an error on a browser page. Errors should be displayed only at the development or debugging stage. Otherwise, there is a potential risk of information disclosure.
handled_errors_types	This key is intended for setting error types to be caught by the system (not ignored).
exception_errors_types	The key sets error types for which the system gives an exception.
ignore_silence	The key cancels action of the error management operator (@).
log	The key sets error logging parameters. If there is no key, there will be no logging. If set as in the example: 'log' => array ( 'settings' => array ( 'file' => 'bitrix/modules/error.log', 'log_size' => 1000000, ), ), the logging will be made into a file with limited size. If site root contains the file error.php and error printing on screen is enabled, this file will be connected in case of unprocessed exception. If set in a general case, logging can be made to anywhere: 'log' => array( 'class_name' => 'MyLog', // custom log class, must extends ExceptionHandlerLog; // can be omited, in this case default Diag\FileExceptionHandlerLog will be used 'extension' => 'MyLogExt', // php extension, is used only with 'class_name' 'required_file' => 'modules/mylog.module/mylog.php' // included file, is used only with 'class_name' 'settings' => array( // any settings for 'class_name' ), ), The provided example: class_name - custom class, descendant from `\ExceptionHandlerLog`. May not be specified. In this case, uses `\Bitrix\Main\Diag\FileExceptionHandlerLog`. extension - PHP extension, use only jointly with class_name. required_file - enabled file. Used only jointly with class_name. settings - settings for class, specified in class_name
assertion_throws_exception	Enabling support for command `assert`.
assertion_error_type	The key specifies only error types for which the incorrect `assert` throws exception.

Error type must be passed in handled_errors_types, exception_errors_types, assertion_error_type. Error type is a numerical code. For example, parameter exception_errors_types. And what does such record means: E_ALL & ~E_NOTICE & ~E_WARNING & ~E_STRICT & ~E_USER_WARNING & ~E_USER_NOTICE & ~E_COMPILE_WARNING?

First, let's refer to levels of PHP error interpreter. There are specific values and determined constants matching them. In our case, this record means that E_ALL (constant value 2047), is bit-wise and not E_NOTICE, and not E_WARNING and not E_STRICT and not E_USER_WARNING and not E_USER_NOTICE and not E_COMPILE_WARNING. That is E_ALL with exception of previosuly specified constants that define one or the other PHP interpreter error level.

Connections section

Database and other data source connection parameters. The class name and connection parameters are specified.

'connections' => array (
        'value' => array (
            'default' => array (
                'className' => '\\Bitrix\\Main\\DB\\MysqlConnection',
                'host' => 'localhost:31006',
                'database' => 'admin_bus',
                'login' => 'admin_bus',
                'password' => 'admin_bus',
                'options' => 2,
                'handlersocket' => array (
                    'read' => 'handlersocket',
                ),
            ),
            'handlersocket' => array (
                'className' => '\\Bitrix\\Main\\Data\\HsphpReadConnection',
                'host' => 'localhost',
                'port' => '9998',
            ),
        ),
        'readonly' => true,
    ),

Attention: The mysqli extension can be used starting from core version 14.5.2 and higher

'className' => '\\Bitrix\\Main\\DB\\MysqliConnection'.

Also, for this purpose, mysqli extension can be installed via PHP. Additional checks for extension availability are not performed! Mysqli can be enabled separately for the old (dbconn.php) and the new (.settings.php) core D7.

Parameter	Value
options	Checkboxes of persistent connection and deferred connection with the database. Example: Connection::PERSISTENT == 1 Connection::DEFERRED == 2 Their combinations can be recorded via bit operations. Example 3 - both PERSISTENT and DEFERRED.
handlersocket	The key specifies which connection must be used for read (read key). Connection must be created, where class, host and port are specified. The example of code above, 'read' parameter is specified with the handlersocket value. Below is the description for the handlersocket connection.
className	Class name, that receives the result of handling the specific database type.
host	host name, where the database is located; can be specified with the port
database	database name
login	database user login
password	database user password

Note:
Several databases can be handled within the ORM.
To use the handlersocket connection, the HSPHP - PHP HandlerSocket client library must be installed

Root section

General settings are located in the root section.

Parameter	Value
disable_iconv	Restricts the use of iconv library. Equivalent of the BX_ICONV_DISABLE constant in the old core
logger	Loggers, implementing PSR-3 interface. Details.

Pull section

This section is specifically required only for hosting partners (for deployment automation). For the rest, its recommended to use the setup via administrative control panel interface.

'pull' => Array(
       'value' =>  array(
           'path_to_listener' => "http://#DOMAIN#/bitrix/sub/";,
           'path_to_listener_secure' => "https://#DOMAIN#/bitrix/sub/";,
           'path_to_modern_listener' => "http://#DOMAIN#/bitrix/sub/";,
           'path_to_modern_listener_secure' => "https://#DOMAIN#/bitrix/sub/";,
           'path_to_mobile_listener' => "http://#DOMAIN#:8893/bitrix/sub/";,
           'path_to_mobile_listener_secure' => "https://#DOMAIN#:8894/bitrix/sub/";,
           'path_to_websocket' => "ws://#DOMAIN#/bitrix/subws/",
           'path_to_websocket_secure' => "wss://#DOMAIN#/bitrix/subws/",
           'path_to_publish' => 'http://127.0.0.1:8895/bitrix/pub/',
           'nginx_version' => '3',
           'nginx_command_per_hit' => '100',
           'nginx' => 'Y',
           'nginx_headers' => 'N',
           'push' => 'Y',
           'websocket' => 'Y',
           'signature_key' => '1111111111',
           'signature_algo' => 'sha1',
           'guest' => 'N',
       ),
   ),

Example of section code and parameters table

Parameter	Value
path_to_listener	path to connect to server (http) to receive commands
path_to_listener_secure	path to connect to server (https) to receive commands
path_to_modern_listener	path to connect to server for modern web browsers (http) to receive command
path_to_modern_listener_secure	path to connect to server for modern browsers (https) to receive commands
path_to_websocket	path to connect to server for modern browsers with socket support (http) to receive commands
path_to_websocket_secure	path to connect to server for modern browsers with web-socket support (https) to receive commands
path_to_publish	path to publish commands from the server
path_to_publish_web	path to publish commands from the web browser (http)
path_to_publish_web_secure	path to publish commands from the web browser (https)
nginx_version	queue server version
nginx_command_per_hit	number of channels to his which the same data will be sent per hit
nginx	enables the queue server
nginx_headers	allows to send special headers
push	enables the queue server
websocket	activates the web-sockets
signature_key	secret signature key for messages
signature_algo	signature encryption algorithm
guest	enables module active status for guests
enable_protobuf	enables new format for messages
limit_max_payload	maximum size of a message in bytes
limit_max_messages_per_request	maximum number of messages per hit
limit_max_channels_per_request	maximum number of channels per hit

Http_client_options section

This section specifies options by default for the Bitrix\Main\Web\HttpClient.

[ICO_NEW data-adding-timestamp="1706700990"]

Starting from main 23.0.0 HttpClient now supports PSR-18. In addition to PSR, client works in legacy mode, supports queues with asynchronous queries and CURL.

[/ICO_NEW]

Parameter	Value
redirect	true by default, execute redirect
redirectMax	maximum number of such redirects (by default: 5)
waitResponse	if true - wait for response (by default), otherwise - return the response immediately
socketTimeout	response timeout period in seconds (by default: 30)
streamTimeout	stream timeout in seconds (by default: 60)
version	version http - 1.0 or 1.1 (by default: 1.0)
proxyHost / proxyPort / proxyUser / proxyPassword	parameter group to setup a proxy
compress	if true, sends Accept-Encoding: gzip
charset	encoding for the object body (is used in the header field for the Content-Type request for POST and PUT)
disableSslVerification	if true, ssl certificates verification will not be performed

Config example:

  'http_client_options' =>
   array (
     'value' =>
        array (
         'redirect' => true,//execute redirects, if required
         'redirectMax' => 10,//but not more than 10
         'version' => '1.1'//work via the http 1.1 protocol 
        ),
     'readonly' => false,
   ),

You can check if your settings are correct as follows:

use Bitrix\Main\Config\Configuration;
print_r(Configuration::getValue("http_client_options"));

Your array should be displayed.

services section

This section is intended for registering services. Find more details in the lesson [ds]Service Locator[/ds][di]Service locator is a design template for convenient handling of application services. Instead of creating specific services directly (via new) service locator is responsible for creating and finding services.

Learn more ...[/di]

Connection to Redis, Memcache

Add a titled connection into connections section to create a connection inside bitrix/.settings.php settings file.

Redis

Ensure that you have installed Redis extension for working via PHP.

Standard connection:

 'connections' => [
    'value' => [
      'default' => [
        'className' => \Bitrix\Main\DB\MysqliConnection::class,
        //... config for existing database connection
      ],
      'custom.redis' => [
        'className' => \Bitrix\Main\Data\RedisConnection::class,
        'port' => 6379,
        'host' => '127.0.0.1',
        'serializer' => \Redis::SERIALIZER_IGBINARY,
      ],
      'custom2.redis' => [
        'className' => \Bitrix\Main\Data\RedisConnection::class,
        'port' => 6379,
        'host' => '127.0.0.4',
        'serializer' => \Redis::SERIALIZER_IGBINARY,
      ],
    ],
    'readonly' => true,
  ]

You can find additional information about serializer config variants in the official documentation.

Cluster

When creating cluster from redis servers, just add servers config.

'connections' => [
    'value' => [
      'default' => [
        'className' => \Bitrix\Main\DB\MysqliConnection::class,
        //... config for existing database connection
      ],
      'custom.redis' => [
        'className' => \Bitrix\Main\Data\RedisConnection::class,
        'servers' => [
            [
                'port' => 6379,
                'host' => '127.0.0.1',
            ],
            [
                'port' => 6379,
                'host' => '127.0.0.2',
            ],
            [
                'port' => 6379,
                'host' => '127.0.0.3',
            ],
        ],
        'serializer' => \Redis::SERIALIZER_IGBINARY,
        'persistent' => false,
        'failover' => \RedisCluster::FAILOVER_DISTRIBUTE,
        'timeout' => null,
        'read_timeout' => null,
      ],
    ],
    'readonly' => true,
  ]

Additional information about configurations for variants serializer, persistent, failover, timeout, read_timeout can be found in the official documentation.

Use

To get a connection instance, you may query the connection name using the method \Bitrix\Main\Application::getConnection.

/** @var \Redis $redisConnection **/
$redisConnection = \Bitrix\Main\Application::getConnection('custom.redis')->getResource();
$redisConnection->setnx('foo', 'bar');

Memcache

Ensure that you have installed Memcache extension for working via PHP.

Standard connection

'connections' => [
    'value' => [
      'default' => [
        'className' => \Bitrix\Main\DB\MysqliConnection::class,
        //... config for existing database connection
      ],
      'custom.memcache' => [
        'className' => \Bitrix\Main\Data\MemcacheConnection::class,
        'port' => 11211,
        'host' => '127.0.0.1',
      ],
      'custom42.memcache' => [
        'className' => \Bitrix\Main\Data\MemcacheConnection::class,
        'port' => 6379,
        'host' => '127.0.0.4',
      ],
    ],
    'readonly' => true,
  ]

Cluster

When creating cluster from memcache servers, just add servers config.

'connections' => [
    'value' => [
      'default' => [
        'className' => \Bitrix\Main\DB\MysqliConnection::class,
        //... config for existing database connection
      ],
      'custom.memcache' => [
        'className' => \Bitrix\Main\Data\MemcacheConnection::class,
        'servers' => [
            [
                'port' => 11211,
                'host' => '127.0.0.1',
                'weight' => 1, //read more about weight config in the memcahe documenation
            ],
            [
                'port' => 11211,
                'host' => '127.0.0.2',
                'weight' => 1, //read more about weight config in the memcahe documenation
            ],
        ],
      ],
    ],
    'readonly' => true,
  ]

Use

To get a connection instance, query connection name using the method \Bitrix\Main\Application::getConnection.

/** @var \Memcache $memcacheConnection **/
$memcacheConnection = \Bitrix\Main\Application::getConnection('custom.memcache')->getResource();
$memcacheConnection->set('foo', 'bar');

SMTP server local settings

Bitrix24 On-premise editions Main module version 21.900.0 has a new SMTP option allowing to organize dedicated email streams.

General information

How emails are sent fr om site/instance

For Bitrix24 On-premise, user calls a global function bxmail, triggering standard PHP mail function, wrapping an email with headers. After that, mail function queries your internal infrastructure (depending on your [ds]configuration[/ds][di] Bitrix Framework requires setup for sending and receiving emails. There are three options for sending emails:

- via local sendmail or postfix (when site uses Linux);

- via third-party SMTP server without authentication (for Windows);

- via third-party server with authentication by replacing email sender function.[/di]: postfix, sendmail or any custom solution, operating based on queues, sending all emails via mail function).

All emails (email campaigns and single emails, CRM emails, password restoration emails, workflows, etc.) are included into a single stream.

Using new local SMTP server settings you can configure dedicated streams as per custom requirements.

Advantages of sender's SMTP server

dedicated streams;
use of [dw]aliases[/dw][di] Aliases are additional mailbox names. They are used to assign additional names to a single mailbox located at your domain. For example, you have a mailbox mysite@example.com. You can add an alias marketing<mysite@example.com> for marketing department. After this action, users receiving an email from marketing department will see only marketing as a sender.

When users respond to this email, their reply is sent to an actual mailbox mysite@example.com. [/di] (alias);
simple setup;
debugging option;
option to send on hits;
option to maintain open connection (useful for bulk mail).

Enabling SMTP server

To enable sender's SMTP server in Bitrix24 On-premise editions, you need to edit the file [ds]/bitrix/.settings.php[/ds][di] Bitrix Framework has a variety of kernel/core settings that do not have visual UI for editing. This is due to updated settings or an error can easily cause the complete system to malfunction (database connection settings, cache settings and etc.).

Learn more...[/di], by adding the corresponding code:

return [
	//…
	'smtp' => [
		'value' => [
			'enabled' => true,
			'debug' => true, //optional
			'log_file' => '/var/mailer.log' //optional
		]	 
	]
];

Important! Extra caution is advised when editing the .settings.php file: a single error can easily cause the complete system to malfunction.

Settings parameters:

enabled – enabling the SMTP server for the sender;
debug – optional parameter (disabled by default). Enable it if you want to see the complete interaction process with SMTP servers;
log_file – optional parameter. Can indicate a file for collection of logs, by entering full path to file (this file requires access). By default, project/site directory already contains the file mailer.log with all logs incoming logs.

SMTP connection setup

SMTP connection can be configured by two methods:

When creating new email message, [dw]add a sender[/dw][di] [/di], click on the link [dw]SMTP server[/dw][di] [/di] and complete the displayed config fields for connecting an SMTP server:
- enter name and email;
- indicate SMTP server sender's visibility: for you only or visible for all users;
  Note: Each employee can connect a dedicated SMTP server.
- indicate email server;
- enter a port (mostly three values are used: 25, 465, 587);
- indicate [dw]maximum daily message limits[/dw][di] Various email services (Google, Yahoo, etc.) have different limits on the number of sent emails (most frequently its the lim it on the number of emails sent per 24 hours). With this option enabled, Bitrix24 will maintain statistics on the number of dispatched emails and issue errors, when limits are reached. [/di];
- enter login and password for connected SMTP server.
Similar form for connecting SMTP server can be completed at the site's Control panel at Settings > System settings > Email and SMS events > SMTP settings, by clicking on the button Add SMTP connection:

Note: Currently, daily message limits config is not available for SMTP connections added inside the Control panel.

Are the settings described above connected with SMTP settings at the Bitrix24 Virtual Appliance?

SMTP server settings described in this lesson are not associated with [ds]BitrixVM SMTP settings[/ds][di] Complete the following actions to configure SMTP client:

1. Go to the main menu 6. Configure pool sites > 4. Change e-mail settings on site and enter email host name

Learn more...[/di].

Example: BitrixVM site has a configured Gmail [ds]via BitrixVM menu[/ds][di] This lesson contains some examples of email services employed at BitrixVM.

Learn more...[/di]. Add new SMTP connection for Yahoo.com via site administrative section. Now, the From field in a new email or email campaign has a selection of two email services: Gmail and Yahoo. Depending on which service is selected, system sends emails either using Bitrix Virtual Appliance or Bitrix24 core.

Can there be conflicting email duplication in case SMTP has been configured both locally and on the virtual appliance?

No, settings won't clash or emails won't duplicate. When sending an email the system checks, if there is an active smtp parameter in the file /bitrix/.settings.php:

if such such parameter exists, email will be sent via local SMTP;
if such parameter doesn't exist, an email will be sent using server functionality via [ds]msmtp[/ds][di]For SMTP client setup, execute the following:

1. At the main menu, go to 6. Configure pool sites > 4. Change e-mail settings on site and enter the host name to configure email dispatch

Learn more...[/di].

Name Spaces

Name spaces

The notion of name spaces permits giving system elements clearer names, getting rid of numerous name prefixes, and also avoiding potential conflicts. All classes delivered in a standard installation package must be located in the Bitrix name space that does not overlap either with PHP or with partner implementations. Each standard module determines its subspace in the Bitrix name space which coincides with the module name. For example, for the forum module Bitrix\Forum will be the name space, and for the main module – Bitrix\Main.

Note. For partner classes, the namespace can be as follows:

namespace Asd\Metrika;  
 
class CountersTable extends Entity\DataManager  
{  
   ....

This means that this class (in /lib/) belongs to the module asd.metrika and it can be addressed as follows (after the indicated module is connected):

\Asd\Metrika\CountersTable::update();

The class itself is located in the file asd.metrika/lib/counters.php.

If necessary, a module may organize subspaces inside its name space. For example, Bitrix\Main\IO, Bitrix\Forum\Somename\Somename2. But this option should be used only if it is justified for the organization of a correct architecture of this module.

Naming Rules

Name spaces must be named in “UpperCamelCase.”
Names cannot contain any symbols but for Latin letters.
Class name must be a noun. Unnecessary acronyms and abbreviations should be avoided.

Examples:

namespace Bitrix\Main\Localization;
namespace Bitrix\Main\Entity\Validator;

Abbreviations that are not generally accepted (in Bitrix Framework) cannot be used.

Attention! The examples that are provided does do not mention name spaces. It make the text more readable and easier to comprehend. Prior using the examples provided in the documentation, a name space must be added.

It ca be done as follows:

By using PHPdoc;
By using IDE;
additionally, the documentation context usually clarifies which class is described.

Full address line can be abridged. Instead \Bitrix\Main\Class::Function() you can specify Main\Class::Function().

Synonyms also can be used instead of long name spaces. To do it, use is inserted. For example, the following long structure is available:

\Bitrix\Main\Localization\Loc::getMessage("NAME");

To abridge it, declare a synonym at the start of the file and use an abridged variant of the call afterwards:

use \Bitrix\Main\Localization\Loc;
...
Loc::getMessage("NAME");

Modules in D7

System modules (both standard and downloaded from Bitrix24 Marketplace) are located in the bitrix/modules system folder. User modules can be located in the folder /local/modules (Third-party developer modules may be located in different folders)]. Such difference allows developers to conveniently organize version control for their development products and maintain continuous updates using the standard update system.

Module's API (classes, logic) are located in the module's subfolder [dw]/lib[/dw][di]This folder is optional if your class doesn't have its own methods.[/di]. For example, Main module path can be as follows: bitrix/modules/main/lib. The same folder is used for connecting API when specific rules are satisfied:

Class files must be titled in lower case, with class name equal to file name. For example: /lib/myclass.php.
Files must contain a correct namespace. Example: when module is connected as follows:
Loader::includeModule('company.shotname');
the class must have a namespace: namespace Company\Shotname.
Corresponding method must be connected where such module classes are used in the Control Panel.

Exceptions

The new core uses the mechanism of exceptions.

Exception case (when an exception may be given) is an atypical situation when it makes no sense to continue the performance of the basic algorithm.

Examples

If a user has sent a form with an empty Name field, it is not an exception case. It is a regular expected case that must be handled appropriately.

But if in case of API method invocation in order to change an infoblock element an empty element id was specified, it is an exception case. It is unexpected and it makes no sense to continue changing the element.

If the method is waiting for the user id and you transmit a line, it is an exception, because the method does not know what to do with the line in this case.

If the GetList method accepts the timestamp filter, and developer has written “tymestamp,” it will be an exception.

Exception Hierarchy

Available exceptions have a hierarchy. It handles exceptions, shows the activated exceptions, which allows to take appropriate actions. The general hierarchy logic is as follows:

\Exception
   Bitrix\Main\SystemException         - basic class of all system exceptions
      Bitrix\Main\IO\IoException         - basic class of all exceptions of file input-output
         Bitrix\Main\IO\FileDeleteException   - exception in case of file deletion
         Bitrix\Main\IO\FileNotFoundException   - absence of a required file
         Bitrix\Main\IO\FileOpenException   - exception in case of file opening
         Bitrix\Main\IO\InvalidPathException   - invalid path
         Bitrix\Main\IO\FileNotOpenedException - file not opened 
      Bitrix\Main\Config\ConfigurationException   - configuration error
      Bitrix\Main\Security\SecurityException      - security error
      Bitrix\Main\Security\Sign\BadSignatureException  - signature error exception.
      Bitrix\Main\ArgumentException      - basic class of exceptions associated with incoming parameters of methods
         Bitrix\Main\ArgumentNullException   - parameter must not be left empty
         Bitrix\Main\ArgumentOutOfRangeException   - parameter outside a permitted range
         Bitrix\Main\ArgumentTypeException   - inadmissible type parameter
      Bitrix\Main\DB\DbException      - basic class for database exceptions
         Bitrix\Main\DB\ConnectionException   - exception during connection
         Bitrix\Main\DB\SqlException      - exception during performance of a query
      Bitrix\Main\NotSupportedException   - is invoked if the functionality is not supported
      Bitrix\Main\NotImplementedException   - is invoked if the functionality must be supported but is not implemented so far
 Bitrix\Main\ObjectPropertyException - is invoked when the object properties are invalid
 Bitrix\Main\ObjectNotFoundException - is invoked when object does not exist 
 Bitrix\Main\ObjectException - is invoked if object cannot be created.  
 Bitrix\Main\LoaderException      - exception in loader

Bitrix\Main\SystemException is the basic class for all system exceptions; all the rest of exceptions are inherited from it. This class re-defines the constructor for the \Exception system class. If the system class receives the message and error code on input:

<?php
public function __construct($message = null, $code = 0, Exception $previous = null);

the constructor Main\SystemException additionally receives the file with a thrown exception and a number of string:

<?php
public function __construct($message = "", $code = 0, $file = "", $line = 0, \Exception $previous = null);

Thrown exception must have the most suitable type possible.

If your method creates an exception, it must be described in the method phpDoc.

In Bitrix Framework, it is done as follows:

 /**
     * Searches connection parameters (type, host, db, login and password) by connection name
     *
     * @param string $name Connection name
     * @return array|null
     * @throws \Bitrix\Main\ArgumentTypeException
     * @throws \Bitrix\Main\ArgumentNullException
     */
    protected function getConnectionParameters($name) {}

Ignoring exceptions

Sometimes, an occurred error must not interrupt execution of a script. Such situation can be exemplified by the operation of CDN module administration page.

If the CDN module is enabled, the traffic data is displayed at the top of the page. Its code looks as follows:

$cdn_config = CBitrixCloudCDNConfig::getInstance()->loadFromOptions();
$APPLICATION->SetTitle(GetMessage("BCL_TITLE"));
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/prolog_admin_after.php");
if (is_object($message))
	echo $message->Show();

if (CBitrixCloudCDN::IsActive())
{
	try
	{
		if ($cdn_config->getQuota()->isExpired())
			$cdn_config->updateQuota();

		$cdn_quota = $cdn_config->getQuota();
		if ($cdn_quota->getAllowedSize() > 0.0 || $cdn_quota->getTrafficSize() > 0.0)
		{
			CAdminMessage::ShowMessage(array(
				"TYPE" => "PROGRESS",
				"DETAILS" => ''.GetMessage("BCL_CDN_USAGE", array(
					"#TRAFFIC#" => CFile::FormatSize($cdn_quota->getTrafficSize()),
					"#ALLOWED#" => CFile::FormatSize($cdn_quota->getAllowedSize()),
				)).'#PROGRESS_BAR#',
				"HTML" => true,
				"PROGRESS_TOTAL" => $cdn_quota->getAllowedSize(),
				"PROGRESS_VALUE" => $cdn_quota->getTrafficSize(),
			));
		}
	}
	catch (Exception $e)
	{
		CAdminMessage::ShowMessage($e->getMessage());
	}
}

The code above shows that if CDN is active, the progress bar with the displayed traffic data is created. However, if an error occurs during execution of this code, an exception will be thrown. This exception will be caught, because all the code is located in try and the branch will be executed after catch, where the error message is displayed via the standard function. The script execution will not be interrupted.

Code Writing Rules

The quality of a program begins with the quality of the source code. The fundamental factor for quality of source code is its readability and clarity. Formalized rules are necessary to write code which will be readable and understandable.

The rules for formatting code must be uniform throughout the entire project. It is highly desirable for the rules to be similar from project to project.

Note: The code formatting rules for core D7 are somewhat different from the code formatting rules for old core.

Source Code Formatting
Naming Conventions
Comments
- PHPDoc
Other
- Magic numbers
- Automatic formatting tools
  - php_beautifier

1. Source Code Formatting

1.1. Text Structure Rules

1.1.1. Line Length

Avoid typing lines whose length exceeds 120 characters. If a line spans beyond that limit, use the line wrapping rules described below.

1.1.2. Line Wrapping Rules

If a line length exceeds 120 characters, the following wrapping rules apply:

wrap lines after the comma or before the operator;
the wrapped line must be indented by one tab;
use UNIX line ends.

Example 1: The code

$arAuthResult = $USER->ChangePassword($USER_LOGIN, $USER_CHECKWORD, $USER_PASSWORD, $USER_CONFIRM_PASSWORD, $USER_LID);

needs to be wrapped as follows:

$arAuthResult = $USER->ChangePassword($USER_LOGIN, $USER_CHECKWORD,
     $USER_PASSWORD, $USER_CONFIRM_PASSWORD, $USER_LID);

Example 2: The code

if(COption::GetOptionString("main", "new_user_registration", "N")=="Y" && $_SERVER['REQUEST_METHOD']=='POST' &&$TYPE=="REGISTRATION" && (!defined("ADMIN_SECTION") || ADMIN_SECTION!==true))

needs to be wrapped as follows

if (COption::GetOptionString("main", "new_user_registration", "N") == "Y")
     && $_SERVER['REQUEST_METHOD'] == 'POST' && $TYPE == "REGISTRATION"
     && (!defined("ADMIN_SECTION") || ADMIN_SECTION !== true)

1.1.3. Spaces And Tabs

Use tabs for indentation. Using spaces for indentation is forbidden for the following reasons:

with tabs, any developer can configure his or her text editor to show the desired tab length;
using tabs makes file size smaller;
if both tabs and spaces are used for indentation, the originally intended text formatting is likely to be damaged if a different tab size is used in a text editor.

1.1.4. Scopes And Code Blocks

The code block contents must be indented by one tab. The code block contents must not be on the same line as the controlling statement.

Example:

function func()
{
     if (condition)
     {
          while (condition2)
          {

          }
      }
}

1.1.5.Rules for placing braces

Opening braces must be place under a corresponding operator and on the same indent with it. Closing braces must be placed under the corresponding opening braces.

Example:

if ($condition)
{
   ...
}

1.1.6. Using the ternary operator "?:"

Conditions must be enclosed in parentheses, and thus separated from the rest of the code. As much as possible, actions that occur under these conditions should be simple functions. If an entire branched block reads poorly, then it is worth replacing it with if/else.

Example:

(condition ? funct1() : func2());

1.2. Expressions And Statements

1.2.1. Expressions

One line must contain only one expression.

Example. This expression is formatted incorrectly:

$a = $b; $b = $c; $c = $a;

Rewrite it like this:

$a = $b;
$b = $c;
$c = $a;

1.2.2. The statements if, else, while etc.

Use one of the following two formatting rules depending on the statement length.

if a controlled code block contains only one statement, use the following form:

if (expression)
     statement 1;
else
     statement 2;

if at least one controlled code block contains multiple statements, use braces:

if (expression)
{
     statement 1;
}
else
{
      statement 2; 
      statement 3;
}

The rule Scopes And Code Blocks must be obeyed when writing multiple statements: they must be indented by one tab off the controlling statement. The braces must exist on new lines on the same level as the controlling statement.

Example. This code:

if ($a == 0) $a = 10;
else{
$a = 5;
$b = 10;}

must be reformatted like this:

if ($a == 0)
{
  $a = 10;
}
else
{
  $a = 5;
  $b = 10;
}

1.2.3. Compound Expressions

Compound expressions must be split in multiple lines according to rules described in “The statements if, else, while etc.”.

For example, consider the following code:

 if(COption::GetOptionString("main", "new_user_registration", "N")=="Y" && $_SERVER['REQUEST_METHOD']=='POST' &&
     $TYPE=="REGISTRATION" && (!defined("ADMIN_SECTION") || ADMIN_SECTION!==true))

Make it readable by sticking to the formatting rules:

if (COption::GetOptionString("main", "new_user_registration", "N") == "Y"
     && $_SERVER['REQUEST_METHOD'] == 'POST' && $TYPE == "REGISTRATION"
     && (!defined("ADMIN_SECTION") || ADMIN_SECTION !== true))
{
}

It is recommended that you split an extremely complex expression into several simple lines of code.

For example, the code

if((!(defined("STATISTIC_ONLY") && STATISTIC_ONLY && substr($APPLICATION->GetCurPage(), 0,
     strlen(BX_ROOT."/admin/"))!=BX_ROOT."/admin/")) && COption::GetOptionString("main", "include_charset", "Y")=="Y"
     && strlen(LANG_CHARSET)>0)

is definitely more readable when written like this:

$publicStatisticOnly = False;
if (defined("STATISTIC_ONLY")
  && STATISTIC_ONLY
  && substr($APPLICATION->GetCurPage(), 0, strlen(BX_ROOT."/admin/")) != BX_ROOT."/admin/")
{
     $publicStatisticOnly = True;
}
if (!$publicStatisticOnly && strlen(LANG_CHARSET) > 0
     && COption::GetOptionString("main", "include_charset", "Y") == "Y")
{
}

or like this:

if (!defined("STATISTIC_ONLY") || ! STATISTIC_ONLY
  || substr($APPLICATION->GetCurPage(), 0, strlen(BX_ROOT."/admin/")) == BX_ROOT."/admin/")
{
  if (strlen(LANG_CHARSET) > 0 && COption::GetOptionString("main", "include_charset", "Y") == "Y")
  {
  }
}

1.2.4. Arrays

The arrays consisting of multiple lines of code should be formatted like this:

$arFilter = array(
  "key1" => "value1",
  "key2" => array(
      "key21" => "value21",
      "key22" => "value22",
  )
);

1.3. Empty Lines And Spaces

1.3.1. Empty Lines

Use empty lines to logically divide your source code. Use multiple empty lines to divide the source code into logical or functional sections in one file. Use a single empty line to separate methods, as well as expressions and statements within a method for better readability.

It is recommended to add a comment before a logical or functional section (see Comments).

1.3.2. Spaces

The comma must be followed by the space. The semicolon must be followed by the space unless it is the last character on the line (for example, in a complex “for” statement). No spaces before the comma or semicolon is allowed. Tabs must not be used instead of spaces in such cases.

Use Cases

The following example shows how a space is used after the commas, but not before the parenthesis:
```
TestMethod($a, $b, $c);
```
These two code fragments are formatted incorrectly:
```
TestMethod($a,$b,$c);
```
and
```
TestMethod( $a, $b, $c );
```
The following example shows to use spaces to properly separate the operators:
```
$a = $b * $c / $d;
```
as opposed to the same code formatted incorrectly:
```
$a=$b*$c/$d;
```
Use spaces to format the “for” statements:
```
for ($i = 0; $i < 10; $i++)
```
Do not merge operators and expressions like this:
```
for($i=0;$i<10;$i++)
```
Note that using tabs to format expressions inside statements is not allowed.
The following formatting should not be made a common practice:
```
$arArray = array(
  "key1" => "value1",
  "key2" => "value2",
);
```
There is no special rule regarding the use of the space, or lack thereof, after the “if” statement.

1.4. Other regulations

Use parentheses to group operators in complex expressions regardless of operator precedence for better readability.

$r = $a + ($b * $c);

2. Naming Conventions

2.1. General Provisions

Do not use underscores in the identifier names because it makes them longer and less readable. Use such names that can describe the identifier purpose and meaning in an unambiguous fashion.

At the same time, try to make your identifier shorter (but they still must be well readable).

If a name contains an abbreviation, it’s better to use a single capital letter for the first letter of the abbreviation than to use capitals for the entire abbreviation. So it would be better to assign a name like getHtmlStatistic than getHTMLStatistic.

2.2. Variable Names

Start with a lowercase character and use uppercase character as separators (camelCase). Variable names can have prefixes if there is a clear need to show the type of variable: ar – for arrays, db – for data sets from databases, etc.

For example: $testCounter, $userPassword.

2.3. Method Names

Clarity in action names, which will execute a function or method.
Use of prefixes: is (indicates a question), get (to get a variable), set (set value).

Example: isFileWriteable()

2.4. Class Names

The name should signify an entity described by the class.
The name should not consist of more than 3 words.
The underscore symbol (‘_’) cannot be used.
To separate words in the name, the first letter of each word can be capitalized.

Example: class SaleAffiliateAccount

3. Comments

Commentary must be in English and contain relevant information

3.1. PHPDoc

All classes and their public methods must be described in PHPDoc style.

Example:

/**
 * Gets a value that indicates whether a directory exists in the file system
 *
 * @param string $path - Path to the directory
 * @return bool - True if the directory exists, false - otherwise
 */

4. Other

4.1. Magic numbers

Code should not contain magic numbers. Here is an example of bad code:

$task->Update($taskId, array('STATUS' => 3), 1);

Proper code:

$task->Update($taskId, array('STATUS' => CTaskStatus::New), TASK_PERMISSIONS_WRITE);

4.2. Automatic formatting tools

4.2.1. php_beautifier

1. Install the php_beautifier (ubuntu) pack:

sudo aptitude install php_beautifier or sudo aptitude install php-pear и sudo pear install PHP_Beautifier-0.1.15
cd
hg clone http://hg.max/repos/Bitrix_php_beautifier
sudo ln -s Bitrix_php_beautifier/Bitrix.filter.php /usr/share/php/PHP/Beautifier/Filter/Bitrix.filter.php

Configure the editor:

Select the menu point Settings - Configure Kate...
Select the setting Plugins and place a check next to Text Filter
Click OK
Now the Tools menu will have a point called Filter Text

Use:

Select a text excerpt (or Ctrl-A for all the text)
Tools - Filter Text
Enter (or select from history): php_beautifier -t -f - -l 'Lowercase Bitrix'
Click OK.

Applications and Context

Application is an object responsible for core initialization.

Application is the entry base point (router) for query to (kernel) core global entities: connection with data sources, managed cache, etc. Also, the application contains global data that belongs to the site itself and do not depend on a specific hit. I.e. the application is an unaltered part not dependent on a specific hit.

Any specific class of application is a successor of the abstract class Bitrix\Main\Application.

The specific class Bitrix\Main\HttpApplication is responsible for a regular http hit on the site.

The application supports the Singleton template. I.e. as a part of the hit there is only one copy of a specific type of application. It can be obtained using the instruction:

$application = Application::getInstance();

Context is an object responsible for a specific hit. It contains a query of a current hit, response to it, and also the server parameters of the current hit. I.e. it is a variable part that depends on the current hit.

Any specific class of a context is a successor of the abstract class Bitrix\Main\Context. Two specific classes of the context are supported – Bitrix\Main\HttpContext and Bitrix\Main\CliContext. The specific class Bitrix\Main\HttpContext is responsible for a regular http hit on the site.

The following code may be used in order to obtain a context of the current hit execution:

$context = Application::getInstance()->getContext();

If the application of the Bitrix\Main\HttpApplication type was initiated, this call will bring an instance of the Bitrix\Main\HttpContext context type.

The context contains a query of the current hit. In order to receive the query the following code may be used:

$context = Application::getInstance()->getContext();
$request = $context->getRequest();

Note: In all the examples, a full form of record is used (sometimes without indicating name spaces) that permits you to obtain the result from any code point. However, short forms may exist for this specific code point in order to access the result.

A request is a class instance that is a successor of the Bitrix\Main\Request class. In case of a normal http request the request will be a class instance of Bitrix\Main\HttpRequest that extends Bitrix\Main\Request. This class is a dictionary providing access to “key-value” pairs of incoming parameters.

The following code may be used in order to access an incoming parameter transmitted by the GET or POST methods:

$value = $request->get("some_name");
$value = $request["some_name"];

Note: Code $value = $request["some_name"]; returns string processed by the security module filters. However, this doesn't signify about its security, all depends on how it will be used further.

Other useful query methods:

$value = $request->getQuery("some_name");   // receive GET parameter
$value = $request->getPost("some_name");   // receive POST parameter
$value = $request->getFile("some_name");   // receive downloaded file
$value = $request->getCookie("some_name");   // receive cookie value
$uri = $request->getRequestUri();   // receive an address requested
$method = $request->getRequestMethod();   // receive a request method
$flag = $request->isPost();      // true - POST-request, otherwise false

Errors

In the old core, API tried to interpret for a user/developer and was overlooking errors and inaccuracies. As a result, errors that are difficult to catch may occur. In addition, such an approach causes a lot of implicit agreements that must be taken into account.

For example, a user/developer selects entries for deletion using a filter. In this case, they incidentally make a writing error in the filter name. A typical API of the old core will ignore this filter and return all the entries. The next instruction will successfully delete all of these entries.

The method changes in the new core D7. API does not have to guess anything for a user. API must respond appropriately if it meets an unexpected situation, such as an unknown filter, no id transmitted, lack of value, excessive value, must not be invoked in this mode, etc.

When an error is displayed on the screen (if the debugging mode is available), connects the file /error.php (The file /error.php is located in site root. It can contain, for example, error message print).

Example of error.php

You can print error in the site design inside this file, as well as specify HTTP status code (for example, "500 Internal Server Error").

API

Module API (classes) is not divided by databases. ORM takes care of all the twists and turns of work with a specific database.

No prefixes or suffixes shall be used in class names.

Each module API class may be located in a separate file with a name that coincides with the class name written in lower case. The classes located in the root of module namespace must be based in the files of the /lib module folder root. The classes located in subspaces inside the module namespace must be based in the files of the relevant subfolders of the /lib module folder.

For example, the Bitrix\Main\Application class must be located in the file /lib/application.php in respect of the main module root folder; the Bitrix\Main\IO\File class must be located in the file /lib/io/file.php in respect of the main module root folder; and the Bitrix\Forum\Message class must be located in the file /lib/message.php in respect of the root folder of the forum module.

If these naming rules are complied with, once a module is connected, its classes are uploaded automatically upon first call. No additional actions are needed for the registration and connection of files with classes.

Note: However, for performance reasons, additional registration and connection are recommended for classes that are used often.

Classes of the ORM entities (successors of the class Bitrix\Main\Entity\DataManager) constitute an exception from the class and file naming rules. The names of such classes are generated with the Table suffix. E.g., CultureTable, LanguageTable. But file names do not contain the table suffix. Such classes are also connected automatically.

Note: There is a possibility to register a class in the autoload system using the following method:

void Loader::registerAutoLoadClasses(
	$moduleName,
	array $arClasses
)

It can be used in order to merge small classes in one file.

Non-standard classes (partner’s classes) must be located in their own namespaces that coincide with the names of relevant partners. Each partner’s module determines its own subspace in the partner’s namespace that coincides with the module name without the partner’s name. E.g., for the module mycompany.catalog of the partner "Mycompany", the namespace will be MyCompany\Catalog. Other rules are the same as for standard modules.

The following instruction is used in order to connect a module in a new core:

mixed Loader::includeModule($moduleName);

Naming Rules

Classes

Classes must be named in UpperCamelCase.
Their name cannot contain any other symbols but for Latin letters.
Class name must be a noun. Unnecessary acronyms and abbreviations should be avoided.

Examples:

class User;
class UserInformation;

Methods

The methods, including class methods, must be named in lowerCamelCase.
Their name cannot contain any other symbols but for Latin letters.
Numbers may be used, provided that the name cannot be formed otherwise. E.g.: encodeBase64, getSha1Key.
The method name must start with a verb.
The name length must contain at least 3 characters.

Examples:

run();
setImage();
getName();

Pure data

Pure data, including class pure data, must be written in UPPER_REGISTER_WITH_A_FLATWORM_SEPARATOR.
May contain Latin letters, flatworm character, and numbers (except for the first position).

Examples:

DATE_TIME_FORMAT
LEVEL_7

Class Members, Method Parameters, and Variables

Must be named in a lowerCamelCase.
May not contain prefixes meaning membership in class, appurtenance to parameters, type, and other insignificant things. Example of unnecessary prefixes: $this->mAge, function setName($pName), $arrArray.
May contain Latin letters and numbers (but for the first position).

Examples:

$firstName = '';
$counter = 0;

Generally Acceptable Abbreviations of the Names of Variables and Methods

Abbreviations in the first position must be written in lower case letters, abbreviations in other positions must start with a capital letter, with all other letters being written in lowercase.
Class names should start with a upper case letter, with all other letters being written in lower case.

Example:

$xmlDocument
$mainXmlDocument
HttpParser

Abbreviations that are not generally acceptable (in Bitrix) cannot be used.

Working with the Database

General architecture of API classes for working with databases:

The connection pool Bitrix\Main\DB\ConnectionPool contains information about connections of applications. There are default connections (main connections) and there may be a set of named connections to connect elsewhere, including to another database of a different type.
Specific connection classes inheriting the abstract class Bitrix\Main\DB\Connection ensure low-level operations with the database. They are divided into classes by databases.
Specific classes of forming SQL queries inheriting Bitrix\Main\DB\SqlHelper that help to form a query without going into the syntax of a specific database.
Specific classes for work with query execution result inheriting Bitrix\Main\DB\Result. They also vary according to databases.

These classes permit working with databases at a low level, but it is rarely required. Instead, working through ORM is recommended since ORM permits programming only at a business logic level.

Obtaining Database Connection, Named Connections

A connection may be obtained through applications and is, among other things, an entry point. From this entry point, instances of “star” objects for this application may be obtained that are needed for all (or almost all) pages or components of this application.

$connection = Main\Application::getConnection();
$sqlHelper = $connection->getSqlHelper();

$sql = "SELECT ID FROM b_user WHERE LOGIN = '".$sqlHelper->forSql($login, 50)."' ";

$recordset = $connection->query($sql);
while ($record = $recordset->fetch())
{
   ***

Various Forms of Query Execution Call

Accordingly, a call must be executed through the application in various forms: simple query, query with a limit for entries, scalar query, or a query “in general.”

$result1 = $connection->query($sql);
$result2 = $connection->query($sql, $limit);
$result3 = $connection->query($sql, $offset, $limit);

$cnt = $connection->queryScalar("SELECT COINT(ID) FROM table");

$connection->queryExecute("INSERT INTO table (NAME, SORT) VALES ('Name', 100)")

Obtaining Query Results:

$connection = Main\Application::getConnection();
$sqlHelper = $connection->getSqlHelper();

$sql = "SELECT ID FROM b_user WHERE LOGIN = '".$sqlHelper->forSql($login, 50)."' ";

$recordset = $connection->query($sql);
while ($record = $recordset->fetch())
{
   ***

Typed data are immediately returned as a type and not as lines or numbers.

Result Modification:

$connection = \Bitrix\Main\Application::getConnection();
$recordset = $connection->query("select * from b_iblock_element", 10);
$recordset->setFetchDataModifier(
   function ($data)
   {
       $data["NAME"] .= "!";
       return $data;
   }
);

while ($record = $recordset->fetch(\Bitrix\Main\Text\Converter::getHtmlConverter()))
   $data[] = $record

Result may be modified and conversed immediately, e.g. for preparation to XML displaying, etc.

Classes. Examples

Configuration

Located in the namespace \Bitrix\Main\Config. Consists of 2 classes: \Bitrix\Main\Config\Configuration и \Bitrix\Main\Config\Option.

Configuration

$realm = \Bitrix\Main\Config\Configuration::getValue("http_auth_realm");
if (is_null($realm))
    $realm = "Bitrix Site Manager"

Class is responsible for the global settings of the entire application. (This feature is determined by pure data in the old core.) Class operates a single base of settings stored in the file /bitrix/.settings.php. The data stored are random. For example, the entire data pool can be stored for named connections.

Option

$cookiePrefix = \Bitrix\Main\Config\Option::get('main', 'cookie_name', 'BITRIX_SM');
$cookieLogin = $request->getCookie($cookiePrefix.'_LOGIN');
$cookieMd5Pass = $request->getCookie($cookiePrefix.'_UIDN');

The option class is virtually the same as the COption class of the old core and works with the parameters of modules and sites stored in the database. It is controlled from the administrative section: settings of specific forms, setup, etc.

Files

Work with files is object-oriented. It is located in the Bitrix\Main\IO namespace and has 3 basic classes:

Path – handling paths, static.
Directory – handling folders.
File – handling files.

Some other classes, including abstract, for managing hierarchy are also available in addition to these classes.

Other classes

The folder bitrix/modules/main/lib contains class library for implementing different frequent actions, included in the Main module and not spread among different modules. В том числе в соответствующих пространствах лежат файлы и API для работы:

Bitrix\Main\Data - with cache, including managed cache.
Bitrix\Main\Text - with text: classes for converting text and other
Bitrix\Main\Type - with data types: date, files and other.
Bitrix\Main\Web - with web: handling the URL, web queries and other.

Equivalent CUtil::jSPostUnescape() in Core D7

If you need to use HttpRequest in AJAX queries:

Application::getInstance()->getContext()->getRequest()->getPost('name')

you'll have to consider that CUtil::JSPostUnescape won't help in case of encoding win-1251.

You can use instead:

use Bitrix\Main\Web\PostDecodeFilter;
...
Application::getInstance()->getContext()->getRequest()->addFilter(new PostDecodeFilter)

After this, you can get decoded data via getPost.

Handling D7. Location example

Do not forget to connect sale module.

Types of locations

Adding a location type:

$res = \Bitrix\Sale\Location\TypeTable::add(array(
	'CODE' => 'CITY',
	'SORT' => '100', // nesting level
	'DISPLAY_SORT' => '200', // display priority when searching
	'NAME' => array( // language names
		),
		'en' => array(
			'NAME' => 'City'
		),
	)
));
if($res->isSuccess())
{
	print('Type added with ID = '.$res->getId());
}

Location type update

$res = \Bitrix\Sale\Location\TypeTable::update(21, array(
	'SORT' => '300',
	'NAME' => array(
		'en' => array(
			'NAME' => 'New City'
		),
	)
));
if($res->isSuccess())
{
	print('Updated!');
}

Deleting location type

$res = \Bitrix\Sale\Location\TypeTable::delete(21);
if($res->isSuccess())
{
	print('Deleted!');
}

Getting type of location by ID

$item = \Bitrix\Sale\Location\TypeTable::getById(14)->fetch();
print_r($item);

Getting list of types with names on the current language

$res = \Bitrix\Sale\Location\TypeTable::getList(array(
	'select' => array('*', 'NAME_EN' => 'NAME.NAME'),
	'filter' => array('=NAME.LANGUAGE_ID' => LANGUAGE_ID)
));
while($item = $res->fetch())
{
	print_r($item);
}

Getting groups with account of hierarchy having this location

<?
\Bitrix\Main\Loader::includeModule('sale');

function getGroupsByLocation($locationId)
{
    $res = \Bitrix\Sale\Location\LocationTable::getList([
        'filter' => ['=ID' => $locationId],
        'select' => [
            'ID', 'LEFT_MARGIN', 'RIGHT_MARGIN'
        ]
    ]);

    if(!$loc = $res->fetch())
    {
        return [];
    }

    $locations = [$locationId];

    $res = \Bitrix\Sale\Location\LocationTable::getList([
        'filter' => [
            '<LEFT_MARGIN' => $loc['LEFT_MARGIN'],
            '>RIGHT_MARGIN' => $loc['RIGHT_MARGIN'],
            'NAME.LANGUAGE_ID' => LANGUAGE_ID,
        ],
        'select' => [
            'ID',
            'LOCATION_NAME' => 'NAME.NAME'
        ]
    ]);

    while($locParent = $res->fetch())
    {
        $locations[] = $locParent['ID'];
    }

    $res = \Bitrix\Sale\Location\GroupLocationTable::getList([
        'filter' => ['=LOCATION_ID' => $locations]
    ]);

    $groups = [];

    while($groupLocation = $res->fetch())
    {
        $groups[] = $groupLocation['LOCATION_GROUP_ID'];
    }

    return $groups;
}

Locations

Adding

$res = \Bitrix\Sale\Location\LocationTable::add(array(
	'CODE' => 'newly-created-location-code',
	'SORT' => '100', // priority for showing in list
	'PARENT_ID' => 1, // parent location ID
	'TYPE_ID' => 14, // type ID
	'NAME' => array( // language names
		'en' => array(
			'NAME' => 'New York'
		),
	),
	'EXTERNAL' => array( // external service values
		array(
			'SERVICE_ID' => 1, // service ID
			'XML_ID' => '163000' // value
		),
		array(
			'SERVICE_ID' => 1,
			'XML_ID' => '163061'
		),
	)
));
if($res->isSuccess())
{
	print('Location added with ID = '.$res->getId());
}
else
{
	print_r($res->getErrorMessages());
}

Update

$res = \Bitrix\Sale\Location\LocationTable::update(3156, array(
	'PARENT_ID' => 33,
	'NAME' => array(
		'de' => array(
			'NAME' => 'New York'
		),
	)
));
if($res->isSuccess())
{
	print('Updated!');
}

Deleting

$res = \Bitrix\Sale\Location\LocationTable::delete(3156);
if($res->isSuccess())
{
	print('Deleted!');
}

Getting location by ID

$item = \Bitrix\Sale\Location\LocationTable::getById(3159)->fetch();
print_r($item);

Getting location by CODE, with optional filtering\field retrieval. In fact, this is a wrapper \Bitrix\Sale\Location\LocationTable::getList().

$item = \Bitrix\Sale\Location\LocationTable::getByCode('newly-created-location-code', array(
	'filter' => array('=NAME.LANGUAGE_ID' => LANGUAGE_ID),
	'select' => array('*', 'NAME_EN' => 'NAME.NAME')
))->fetch();
print_r($item);

Getting list of locations with names on the current language and type codes

$res = \Bitrix\Sale\Location\LocationTable::getList(array(
	'filter' => array('=NAME.LANGUAGE_ID' => LANGUAGE_ID),
	'select' => array('*', 'NAME_EN' => 'NAME.NAME', 'TYPE_CODE' => 'TYPE.CODE')
));
while($item = $res->fetch())
{
	print_r($item);
}

Getting node direct descendants with ID=1 with names on the current language, codes and names for location types

$res = \Bitrix\Sale\Location\LocationTable::getList(array(
	'filter' => array(
		'=ID' => 1, 
		'=CHILDREN.NAME.LANGUAGE_ID' => LANGUAGE_ID,
		'=CHILDREN.TYPE.NAME.LANGUAGE_ID' => LANGUAGE_ID,
	),
	'select' => array(
		'CHILDREN.*',
		'NAME_EN' => 'CHILDREN.NAME.NAME',
		'TYPE_CODE' => 'CHILDREN.TYPE.CODE',
		'TYPE_NAME_EN' => 'CHILDREN.TYPE.NAME.NAME'
	)
));
while($item = $res->fetch())
{
	print_r($item);
}

Getting parent nodes for three nodes

$res = \Bitrix\Sale\Location\LocationTable::getList(array(
	'filter' => array(
		'=ID' => array(3159, 85, 17), 
		'=PARENT.NAME.LANGUAGE_ID' => LANGUAGE_ID,
		'=PARENT.TYPE.NAME.LANGUAGE_ID' => LANGUAGE_ID,
	),
	'select' => array(
		'PARENT.*',
		'NAME_EN' => 'PARENT.NAME.NAME',
		'TYPE_CODE' => 'PARENT.TYPE.CODE',
		'TYPE_NAME_EN' => 'PARENT.TYPE.NAME.NAME'
	)
));
while($item = $res->fetch())
{
	print_r($item);
}

Getting path from tree root to the current item

$res = \Bitrix\Sale\Location\LocationTable::getList(array(
	'filter' => array(
		'=ID' => 224, 
		'=PARENTS.NAME.LANGUAGE_ID' => LANGUAGE_ID,
		'=PARENTS.TYPE.NAME.LANGUAGE_ID' => LANGUAGE_ID,
	),
	'select' => array(
		'I_ID' => 'PARENTS.ID',
		'I_NAME_EN' => 'PARENTS.NAME.NAME',
		'I_TYPE_CODE' => 'PARENTS.TYPE.CODE',
		'I_TYPE_NAME_EN' => 'PARENTS.TYPE.NAME.NAME'
	),
	'order' => array(
		'PARENTS.DEPTH_LEVEL' => 'asc'
	)
));
while($item = $res->fetch())
{
	print_r($item);
}

Getting list of root nodes with indicated number of descendants

$res = \Bitrix\Sale\Location\LocationTable::getList(array(
	'filter' => array(
		'=PARENT_ID' => 0,
		'=NAME.LANGUAGE_ID' => LANGUAGE_ID,
		'=TYPE.NAME.LANGUAGE_ID' => LANGUAGE_ID,
	),
	'select' => array(
		'ID',
		'NAME_EN' => 'NAME.NAME',
		'TYPE_CODE' => 'TYPE.CODE',
		'TYPE_NAME_EN' => 'TYPE.NAME.NAME',
		'CHILD_CNT'
	)
));
while($item = $res->fetch())
{
	print_r($item);
}

Getting external data for locations with indicated service code

$res = \Bitrix\Sale\Location\LocationTable::getList(array(
	'filter' => array(
		'CODE' => array('newly-created-location-code', '0000028090'),
	),
	'select' => array(
		'EXTERNAL.*',
		'EXTERNAL.SERVICE.CODE'
	)
));
while($item = $res->fetch())
{
	print_r($item);
}

Getting subtree of nodes on the current language

$res = \Bitrix\Sale\Location\LocationTable::getList(array(
	'runtime' => array(
		'SUB' => array(
			'data_type' => '\Bitrix\Sale\Location\Location',
			'reference' => array(
				'>=ref.LEFT_MARGIN' => 'this.LEFT_MARGIN',
				'<=ref.RIGHT_MARGIN' => 'this.RIGHT_MARGIN'
			),
			'join_type' => "inner"
		)
	),
	'filter' => array(
		'=CODE' => '0000028042',
		'=SUB.NAME.LANGUAGE_ID' => LANGUAGE_ID
	),
	'select' => array(
		'S_CODE' => 'SUB.CODE',
		'S_NAME_EN' => 'SUB.NAME.NAME',
		'S_TYPE_CODE' => 'SUB.TYPE.CODE'
	)
));
while($item = $res->fetch())
{
	print_r($item);
}

Getting locations included into the group without hierarchy.

\Bitrix\Main\Loader::includeModule('sale');


/* Group identifier */
$groupId = 1

/* Get locations included into group */
$res = \Bitrix\Sale\Location\GroupLocationTable::getConnectedLocations(1);

while($item = $res->fetch())
{
    var_dump($item);
}

Service Locator

Description

Service locator - is a design pattern used for convenient handling of application services. You can find more details in this article.

Idea of service patten is designed to use special object (service locator) that will be responsible for creating and locating services instead of creating specific services directly (via "new"). It's a kind of a register.

Class \Bitrix\Main\DI\ServiceLocator implements the interface PSR-11. Available from main version 20.5.400.

Simple example of use:

$serviceLocator = \Bitrix\Main\DI\ServiceLocator::getInstance();

if ($serviceLocator->has('someService'))
{
    $someService = $serviceLocator->get('someService');
    //...$someService service use
}

Service registration

Service registration via bitrix/.settings.php files

Before querying the service, register it, using .settings.php files. All the necessary services are listed in the services section.

 [
        'value' => [
            'someServiceName' => [
                'className' => \VendorName\Services\SomeService::class,
            ],                      
            'someGoodServiceName' => [
                'className' => \VendorName\Services\SecondService::class,
                'constructorParams' => ['foo', 'bar'],
            ],                      
        ],
        'readonly' => true,
      ],
      //...
   ];

As a result, these services will be available immediately after kernel is initialized. Below you can read about the available service describing methods.

$serviceLocator = \Bitrix\Main\DI\ServiceLocator::getInstance();
$someGoodServiceName = $serviceLocator->get('someGoodServiceName');
$someServiceName = $serviceLocator->get('someServiceName');

Service registration has been performed via the {moduleName}/.settings.php module setting files

Module root directory can also contain the .settings.php file. It can contain service descriptions belonging to this module and are used in it. Semantics is similar to description in the global bitrix/.settings.php and config description rules.

 [
        'value' => [
            'someModule.someServiceName' => [
                'className' => \VendorName\SomeModule\Services\SomeService::class,
            ],                      
            'someModule.someAnotherServiceName' => [
                'constructor' => static function () {
                    return new \VendorName\SomeModule\Services\SecondService('foo', 'bar');
                },
            ],                      
            'someModule.someGoodServiceName' => [
                'className' => \VendorName\SomeModule\Services\SecondService::class,
                'constructorParams' => static function (){
                    return ['foo', 'bar'];
                },
            ],                      
        ],
        'readonly' => true,
      ],
      //...
   ];

Attention! These services will be registered only after module is connected. Also, it is recommended to name module services by using module name prefix, to avoid duplicate service codes, for example:

 iblock.imageUploader
    disk.urlManager
    crm.entityManager
    crm.urlManager
    someModule.urlManager.

Registering service via API

Services can be registered via API as well. Use the class methods \Bitrix\Main\DI\ServiceLocator

Service configuration

Configuration is described as an array and prompts service locator a method for creating an object. Presently, there are three description methods:

Indication of service class. Service locator creates the service by calling new $className.

 'someModule.someServiceName' => [
            'className' => \VendorName\SomeModule\Services\SomeService::class,
        ]

Indicating service class and parameters to be passed into constructor. Service locator creates a service by calling new $className('foo', 'bar').

'someModule.someServiceName' => [
            'className' => \VendorName\SomeModule\Services\SomeService::class,
            'constructorParams' => ['foo', 'bar'],
        ]                      

        'someModule.someServiceName' => [
            'className' => \VendorName\SomeModule\Services\SomeService::class,
            'constructorParams' => static function (){
               return ['foo', 'bar'];
            },
        ]

Indicating closure-constructor that create and return service object.

 'someModule.someAnotherServiceName' => [
            'constructor' => static function () {
                return new \VendorName\SomeModule\Services\SecondService('foo', 'bar');
            },
        ]

Locator registration

Service registration

Service registration via the bitrix/.settings.php files

Before querying the service, it must be registered. It can be done via .settings.php files. All the necessary services are listed in the services section.

 [
        'value' => [
            'someServiceName' => [
                'className' => \VendorName\Services\SomeService::class,
            ],                      
            'someGoodServiceName' => [
                'className' => \VendorName\Services\SecondService::class,
                'constructorParams' => ['foo', 'bar'],
            ],                      
        ],
        'readonly' => true,
      ],
      //...
   ];

As the result, these services will be available immediately after core D7 initialization. Read below about which service description methods are presently available.

$serviceLocator = \Bitrix\Main\DI\ServiceLocator::getInstance();
$someGoodServiceName = $serviceLocator->get('someGoodServiceName');
$someServiceName = $serviceLocator->get('someServiceName');

Service registration using the module settings {moduleName}/.settings.php files

The module root can also have the .settings.php file. You can describe services that belong and are used in this module. Semantics is similar to the description in the global bitrix/.settings.php files and config description rules.

 [
        'value' => [
            'someModule.someServiceName' => [
                'className' => \VendorName\SomeModule\Services\SomeService::class,
            ],                      
            'someModule.someAnotherServiceName' => [
                'constructor' => static function () {
                    return new \VendorName\SomeModule\Services\SecondService('foo', 'bar');
                },
            ],                      
            'someModule.someGoodServiceName' => [
                'className' => \VendorName\SomeModule\Services\SecondService::class,
                'constructorParams' => static function (){
                    return ['foo', 'bar'];
                },
            ],                      
        ],
        'readonly' => true,
      ],
      //...
   ];

Attention! These services will be registered only after module is connected. Also, it is recommended to name the module services by using the module name prefix to avoid issues with service code duplicates, for example:

 iblock.imageUploader
    disk.urlManager
    crm.entityManager
    crm.urlManager
    someModule.urlManager.

Service registration via API

Services can be registered via API as well. Use the class methods \Bitrix\Main\DI\ServiceLocator

Service configuration

Configuration is described as an array and prompts service locator a method for creating an object. Presently, there are three methods for description:

Indicating a service class. Service locator creates a service by calling a new $className.

 'someModule.someServiceName' => [
            'className' => \VendorName\SomeModule\Services\SomeService::class,
        ]

Indicating a service class and parameters to be passed into constructor. Service locator will create a service by calling a new $className('foo', 'bar').

'someModule.someServiceName' => [
            'className' => \VendorName\SomeModule\Services\SomeService::class,
            'constructorParams' => ['foo', 'bar'],
        ]                      

        'someModule.someServiceName' => [
            'className' => \VendorName\SomeModule\Services\SomeService::class,
            'constructorParams' => static function (){
               return ['foo', 'bar'];
            },
        ]

Indicating a closure-constructor that must create and return a service object.

 'someModule.someAnotherServiceName' => [
            'constructor' => static function () {
                return new \VendorName\SomeModule\Services\SecondService('foo', 'bar');
            },
        ]

Controllers

Terminology

Action, or AJAX action is a responder method that implements final logic, executes operations and returns data.
Controller - is a combination of AJAx-actions.
configureActions() method regulates configuration of actions inside the controller, defining rules of access to actions.
Pre-, post-filters are configuration items, that are action start and end event handers. Prefilter can block the start, postfilter can affect the result.

Agreements

Note: Main (main) module version 20.600.87 supports PSR-4 in ajax-controllers.

Upon calling all parameter names are caseSEnsitive
Upon calling all parameter names are caseSEnsitive
Upon calling all action names are case-INsensitive

Full action name is generated by the template vendor:module.partOfNamespace0.partOfNamespace1.Controller.action.

    \Bitrix\Disk\Controller\Folder::getAction() 
    bitrix:disk.Controller.Folder.get

    \Bitrix\Disk\Controller\Intergation\Dropbox::connectAction() 
    bitrix:disk.Controller.Intergation.Dropbox.connect

    \Qsoft\Somedisk\Controller\SuperFolder::getAction() 
    qsoft:somedisk.Controller.SuperFolder.get

When not indicating the vendor:, it means it is bitrix:

    \Bitrix\Disk\Controller\Folder::getAction() 
    disk.Controller.Folder.get

When indicating defaultNamespace in module settings, it can be omitted and not indicated in the action.

	defaultNamespace = \Bitrix\Disk\Controller
	
    \Bitrix\Disk\Controller\Folder::getAction() 
    disk.Folder.get

When indicating alias in module settings, use it instead of abbreviated namespace.

	\Bitrix\Disk\CloudIntegration\Controller => cloud
	
    \Bitrix\Disk\CloudIntegration\Controller\File::getAction() 
    disk.cloud.File.get

Upon calling the action from component, indicate full component name and action name (without Action suffix).

    bitrix:list.example
    showFormAction

    BX.ajax.runComponentAction('bitrix:list.example', 'showForm', {
        ...
    }).then(function (response) {});

Time, date, links must be returned not in string format, but as objects.

        \Bitrix\Main\Type\DateTime
        \Bitrix\Main\Type\Date
        \Bitrix\Main\Web\Uri

Controller

Controllers is the part of MVC architecture, responsible for query processing and response generation.

Actions

Controllers consist of main operational actions, employed by user to get a result. Single controller can have one or several actions. For example, let's create controller with two actions item.add and item.view in the module example. Specifically for this example, controller must be located at /modules/vendor.example/lib/controller/item.php.

First step - create file .settings.php in the module root.

<?php
//modules/vendor.example/.settings.php
return [
	'controllers' => [
		'value' => [
			'defaultNamespace' => '\\Vendor\\Example\\Controller',
		],
		'readonly' => true,
	]
];

Next, create controller file (see details for available methods here):

namespace Vendor\Example\Controller;

use \Bitrix\Main\Error;

class Item extends \Bitrix\Main\Engine\Controller
{
	public function addAction(array $fields):? array
	{
		$item = Item::add($fields);

		if (!$item)
		{
			$this->addError(new Error('Could not create item.', {error_code}));

			return null;
		}

		return $item->toArray();
	}

	public function viewAction($id):? array
	{
		$item = Item::getById($id);
		if (!$item)
		{
			$this->addError(new Error('Could not find item.', {error_code}));
					
			return null;
		} 

		return $item->toArray();
	}
}

First, the add action (using specific method Item::addAction) attempts to create a specific Item passed by $fields.

Note. Array $fields retrieved by automatic binding of method parameters and $_REQUEST.

When an activity was failed due to specific reasons, return null and complete the controller by errors. In this case, kernel generates a response:

{
	"status": "error", //please note that status has been automatically updated
	"data": null,
	"errors": [
		{
			"message": "Could not create item.",
			"code": {code}
		}
	]
}

Otherwise, add an item and return it as an array $item->toArray() from activity. This array, kernel generates the response:

{
	"status": "success",
	"data": {
		"ID": 1,
		"NAME": "Nobody",
		//...element fields
	},
	"errors": null
}

Generally, activity can return not only scalars, but objects as well.

The view activity (using specific method Item::viewAction) first attempts loading a specific Item object by specific passed parameter $id. It's important to note, the $id will be automatically retrieved from $_POST['id'] or $_GET['id'].

When this parameter is not found, kernel generates response with error:

{
	"status": "error",
	"data": null,
	"errors": [
		{
			"message": "Could not find value for parameter {id}",
			"code": 0
		}
	]
}

How execute controller action?

Specific AJAX-action requires action naming convention awareness. In our case: Item::addAction -> vendor:example.item.add Item::viewAction -> vendor:example.item.view.

vendor:example.item.add, vendor:example.item.view can be used for calling actions using BX.ajax.runAction:

BX.ajax.runAction('vendor:example.item.add', {
	data: {
		fields: {
            ID: 1,
            NAME: "test"
        } 
	}
}).then(function (response) {
	console.log(response);
	/**
	{
		"status": "success", 
		"data": {
			"ID": 1,
			"NAME": "test"
		}, 
		"errors": []
	}
	**/			
}, function (response) {
	//receives all responses with status status !== 'success'
	console.log(response);
	/**
	{
		"status": "error", 
		"errors": [...]
	}
	**/				
});

Or retrieve the link to action and send individual http-query.

/** @var \Bitrix\Main\Web\Uri $uri **/
$uri = \Bitrix\Main\Engine\UrlManager::getInstance()->create('vendor:example.item.view', ['id' => 1]);
echo $uri;
// /bitrix/services/main/ajax.php?action=vendor:example.item.view&id=1
// execute GET-query

Creating controllers and actions

Creating controllers

Controllers must be inherited from \Bitrix\Main\Engine\Controller or its descendants. Controllers can be located inside the module, or inside the component in the file ajax.php and be a controller for component.

Creating actions

Creating actions means creating methods in a specific controller. Method requires to be public and have an Action suffix.

If action returns \Bitrix\Main\HttpResponse or its descendants, this object is sent to client. When action returns data, it must be converted to scalar or object format, to be converted to JSON for generating \Bitrix\Main\Engine\Response\AjaxJson.

Cumulatively, the action can return both scalars but objects as well that implement the following interfaces:

Creating action-classes

There is an option to create action classes, inherited from \Bitrix\Main\Engine\Action. This option may be required, when logic must be repeatedly used in several controllers. For example, for implementing the same exchange protocol in different modules (e. g. standard search, executing step-by-step actions with progress and etc.). You need to describe the method configureActions in the controller config map:

To call this action, query testoPresto, as described in the config map. Class action supports pre- and post- filters and are no different from the standard action method. run() method reason is similar to other methods/ajax-actions.

Using controllers inside components

Preliminarily create and use controller classes, located in modules, as listed in this article, because this allows to organize better a repeated use of auxiliary code and business logic.

In simple cases, when component is self-sufficient and is not actively used with module's API, you can use controllers inside the component.

Controller life cycle

Application query create controller based on naming convention. Next, controller executes the following work:

Several namespaces

You can indicate several namespaces in .settings.php, in addition to defaultNamespace. This can may be necessary, when controllers are located next to their workflow entities. For example, in a "Drive" module we have integration with clouds.

Now you have call-available controllers, located in both namespaces. Both of them support calling via action full name and via abbreviated record, due to available cloud alias.

Calling modular controller

When you need to query the controller, implemented in the module, use the following method from component context by getting signed parameters:

Controllers and component

You can use the following two approaches for processing AJAX queries in component:

class.php

Example

ajax.php

Query controller handler in the ajax.php file allows creating lightweight ajax-query handler, by directly dedicating logic from component.

Practical hints for developers

For convenient error debugging in AJAX life cycle, enable debug => true in .settings.php, then you will be able to view error and exception traces.

When required:

Practical advice: interaction with controllers from Javascript

Frequently, AJAX-query must retrieve the same parameters from component that were used for its page display.

As the result, your can use the parameters STORAGE_ID, PATH_TO_SOME_ENTITY in your AJAX-action. These parameters are signed and integrity is controlled by kernel.

When you need to work with signed parameters inside ajax.php, use the method Controller::getUnsignedParameters() inside the controller action; it will contain array with unpacked data.

Additional information

Practical advice: page navigation

You can organize page navigation in AJAX-action by implementing in the method parameters \Bitrix\Main\UI\PageNavigation and return \Bitrix\Main\Engine\Response\DataType\Page.

For example, in case of REST, calculation of total records is always required, but for standard AJAX it's optional. More performance and convenient is to use a separate AJAX-action for getting total records as per specific filter.

Practical advice: integration with REST module

You can make controllers, programmed inside a module, available for REST module. This is very convenient, because we re-use already written code.

How to use \CRestServer in AJAX-action

In case AJAX-action must use \CRestServer for a specific task, it can be done by declaring \CRestServer as one of parameters.

Please, be advised, the example above cannot work via standard AJAX, because \CRestServer $restServer is not available in it and cannot be implemented. It can be available only for the REST module. If you declare it as optional, everything will work.

How to understand, if actions are called in REST or AJAX environment?

It can happen that you need to distinguish in which context the action is presently executed: in REST or AJAX? You need to ask the controller:

Practical advice: dependency integration

Scalar and nonscalar parameters

How to retrieve method parameters?

Scalar parameters $userId, $newName, $groups will be retrieved automatically from REQUEST.

Failed search without matching results means that action won't be launched; server will send response with error message informing about missing parameter.

How to integrate objects (nonscalar parameters)?

Integrating custom types

We have a standard AJAX-controller for a specific Folder. However, all actions are eventually performed for an object, with an attempt to load folder and etc. It's preferable to receive Folder $folder on input.

It's important that closure after $className can indicate unlimited number of parameters needed for created object. Such parameters will be associated with data from $_REQUEST in the same way as scalars in standard action methods.

In detail: first, we have declared class name which subclasses we will attempt to create when encounter them in AJAX-actions. Anonymous function will created an action instance.

Bitrix Framework

What is Bitrix Framework?

For Those Who Switched to Bitrix Framework from Other Platforms

Bitrix Framework and Drupal

Bitrix Framework and Joomla

Glossary

Glossary

Production Architecture

Production Architecture

MVC Architecture for Bitrix Framework

Structure