Views: 245639
Last Modified: 29.05.2024

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 command line PHP Command line - system tool, allowing to launch arbitrary code on PHP with function calls. : 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:

    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
    • redis From version 18.5.200.
    • 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

    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' => '',
               '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.

    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.

    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;

    Your array should be displayed.

    services section

    This section is intended for registering services. Find more details in the lesson Service Locator 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 ...

    Courses developed by Bitrix24