Конфигурация ядра

Критически важные настройки ядра хранятся в файле конфигурации. Это защищает их от случайного изменения через административный раздел и повышает безопасность.

Основной файл конфигурации — /bitrix/.settings.php. Менять настройки в нем можно вручную или через API.

Ошибки в настройках .settings.php могут нарушить работоспособность сайта. Перед изменениями создайте резервную копию.

Файл dbconn.php

Архитектура Bitrix Framework использует два ядра: современное D7 и старое ядро.

  • /bitrix/.settings.php — для ядра D7.

  • /bitrix/php_interface/dbconn.php — для старого ядра.

Файл dbconn.php содержит константы для обратной совместимости. Система использует его вместе с .settings.php. Чтобы избежать сбоев, сохраняйте корректность настроек в обоих файлах, даже если работаете только с D7.

Дополнительный файл конфигурации

Чтобы менять настройки динамически без API, создайте файл /bitrix/.settings_extra.php. Система автоматически объединит его настройки с основным файлом.

Папка для разработки

Начиная с версии Главного модуля 24.100.0 конфигурационные файлы можно хранить в папке /local/:

  • .settings.php и .settings_extra.php — в корне /local/,

  • dbconn.php — в папке /local/php_interface/.

Подробнее о папке /local/ в статье Структура директорий.

Секции настроек

Файл .settings.php — это PHP-массив. Его структура состоит из секций для настройки компонентов ядра. Секция connections для подключения к базе данных — обязательная. Остальные секции добавляйте по необходимости.

Защита от изменений

Параметр readonly защищает секцию от изменений через API. Возможные значения:

  • true — запрещает изменение настроек после инициализации ядра, например, параметров базы данных.

  • false — разрешает менять настройки во время работы приложения, например, детали обработки ошибок.

Параметры соединения с базой данных

Секция connections хранит параметры для подключения к основному и дополнительным источникам данных. Здесь указываются хосты, логины, пароли и имена баз данных.

'connections' => [
            'value' => [
                // Основное соединение с базой данных
                'default' => [
                    'className' => \Bitrix\Main\DB\MysqliConnection::class, // Используем драйвер MySQLi для соединения
                    'host' => 'localhost',     // Хост базы данных
                    'database' => 'busik',     // Имя базы данных
                    'login' => 'db_user',      // Имя пользователя БД
                    'password' => '***',       // Пароль пользователя БД
                    'options' => 2,            // Дополнительные опции соединения, 2 — отложенное соединение
                ],
            ],
            'readonly' => true, // Запрещает изменение настроек во время выполнения скрипта
        ],

Подробнее в статье Конфигурация БД.

Обработка ошибок

Секция exception_handling управляет реакцией приложения на ошибки и исключения. Она задает правила вывода на экран, логирования и определения критичных ошибок.

'exception_handling' => [
            'value' => [
                'debug' => true,
                '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' => [
                    'settings' => [
                        'file' => 'bitrix/modules/error.log',
                        'log_size' => 1000000,
                    ],
                ],
            ],
            'readonly' => false,
        ],

  • debug — определяет, показывать ли ошибки в браузере.

    • true — только для разработки. На боевых серверах может привести к раскрытию стека вызовов, путей файлов и других конфиденциальных данных.

    • false — обязательно для боевого сервера. Ошибки не показываются пользователю. Для анализа ошибок нужно настроить секцию log.

  • handled_errors_types — маска типов ошибок, которые система будет обрабатывать.

  • exception_errors_types — маска типов ошибок, при которых система выбросит исключение.

  • ignore_silence — отменяет действие оператора подавления ошибок @, если значение true.

  • assertion_throws_exception — преобразует неудачные assert() в исключения.

  • assertion_error_type — тип ошибки для исключений из assert().

  • log — настройки логирования ошибок. Если параметр не задан, логирование отключено.

Маски типов ошибок

Параметры handled_errors_types и exception_errors_types используют битовые маски. Битовая маска — это число, где каждый бит отвечает за включение или выключение конкретного типа ошибки. Например, E_ALL & ~E_NOTICE означает все типы ошибок, кроме уведомлений.

Основные типы ошибок:

  • E_ERROR — критические ошибки,

  • E_WARNING — предупреждения,

  • E_PARSE — ошибки парсинга,

  • E_NOTICE — уведомления,

  • E_STRICT — сообщения о совместимости,

  • E_DEPRECATED — предупреждения об устаревших функциях,

  • E_ALL — все ошибки и предупреждения.

Настройка логирования

Чтобы логировать ошибки в файл с ограничением размера, используйте конфигурацию log.

'log' => [
            'settings' => [
                'file' => 'bitrix/modules/error.log', // Путь к файлу лога относительно корня сайта
                'log_size' => 1000000, // Максимальный размер файла лога в байтах
            ],
        ],

Чтобы использовать свой класс логирования, укажите параметры:

'log' => [
            'class_name' => 'MyVendor\\MyLogClass', // Ваш класс, должен наследовать \ExceptionHandlerLog
            'required_file' => '/local/php_interface/mylog.php', // Файл для автоподгрузки класса
            'extension' => 'MyLogExt', // Расширение с классом, которое нужно загрузить. Используется вместе с class_name
            'settings' => [ // Произвольные настройки для вашего класса
                'some_parameter' => 'some_value',
            ],
        ],

Кеширование

В секции cache:

  • указываются механизм кеширования,

  • настраиваются параметры: тип кеша, время жизни и другие.

Пример настройки для Redis:

'cache' => [
            'value' => [
                'type' => [ // Настройки типа кеширования
                    'class_name' => '\\Bitrix\\Main\\Data\\CacheEngineRedis', // Использовать Redis
                    'extension' => 'redis' // Требуемое расширение PHP
                ],
                'redis' => [ // Параметры подключения к Redis
                    'host' => '127.0.0.1', // Адрес сервера
                    'port' => '6379', // Порт сервера
                ],
                'sid' => $_SERVER["DOCUMENT_ROOT"]."#01" // Уникальный идентификатор сайта для разделения кеша
            ],
        ],

Подробнее в статье Кеширование.

Push & Pull сервер

Секция конфигурирует сервер очередей сообщений для работы чатов и уведомлений в реальном времени. Для стандартных проектов рекомендуется настраивать Push & Pull сервер в административном разделе. Секция в конфигурационном файле нужна в первую очередь для хостинг-партнеров.

'pull' => [
            'value' => [
                // Базовые URL для подключения к серверу очередей (получение команд)
                'path_to_listener' => "http://#DOMAIN#/bitrix/sub/", // HTTP
                'path_to_listener_secure' => "https://#DOMAIN#/bitrix/sub/", // HTTPS
        
                // URL для современных браузеров
                'path_to_modern_listener' => "http://#DOMAIN#/bitrix/sub/", // HTTP
                'path_to_modern_listener_secure' => "https://#DOMAIN#/bitrix/sub/", // HTTPS
        
                // URL для мобильных приложений
                'path_to_mobile_listener' => "http://#DOMAIN#:8893/bitrix/sub/", // HTTP с портом
                'path_to_mobile_listener_secure' => "https://#DOMAIN#:8894/bitrix/sub/", // HTTPS с портом
        
                // URL для установки соединения по протоколу WebSocket
                'path_to_websocket' => "ws://#DOMAIN#/bitrix/subws/", // WebSocket
                'path_to_websocket_secure' => "wss://#DOMAIN#/bitrix/subws/", // Защищенный WebSocket
        
                // URL для публикации команд на сервер очередей
                'path_to_publish' => 'http://127.0.0.1:8895/bitrix/pub/', // Внутренний URL с сервера
                'path_to_publish_web' => 'http://#DOMAIN#/bitrix/pub/', // Публичный URL из браузера, HTTP
                'path_to_publish_web_secure' => 'https://#DOMAIN#/bitrix/pub/', // Публичный URL из браузера, HTTPS
        
                // Конфигурация сервера
                'nginx_version' => '3', // Версия сервера очередей
                'nginx_command_per_hit' => '100', // Количество каналов для отправки одинаковых данных за один запрос
                'nginx' => 'Y', // Флаг включения сервера очередей
                'nginx_headers' => 'N', // Флаг отправки специальных заголовков
        
                // Флаги функций
                'push' => 'Y', // Включить Push-сервер
                'websocket' => 'Y', // Включить поддержку WebSocket
        
                // Безопасность
                'signature_key' => 'your_secret_key_here', // Секретный ключ для подписи сообщений. Укажите уникальное значение для вашего проекта
                'signature_algo' => 'sha1', // Алгоритм шифрования подписи, например, sha1 или sha256
        
                // Доступ
                'guest' => 'N', // Разрешить работу для неавторизованных пользователей
        
                // Форматы и лимиты
                'enable_protobuf' => 'N', // Использовать Protocol Buffers для сообщений
                'limit_max_payload' => 2097152, // Максимальный размер одного сообщения в байтах
                'limit_max_messages_per_request' => 100, // Максимальное количество сообщений за один запрос
                'limit_max_channels_per_request' => 100, // Максимальное количество каналов за один запрос
            ],
        ],

HTTP-клиент

Секция http_client_options задает параметры по умолчанию для класса Bitrix\Main\Web\HttpClient: таймауты, прокси, редиректы.

С версии Главного модуля 23.0.0 HttpClient поддерживает стандарт PSR-18, а также работает в режиме обратной совместимости с очередями асинхронных запросов и библиотекой сURL.

Параметры, отмеченные комментарием со звездочкой * , работают только в режиме обратной совместимости. Для новых проектов рекомендуется использовать режим PSR-18.

'http_client_options' => [
            'value' => [
                // Таймауты
                'waitResponse' => true,   // Ожидать ответ на запрос (true) или вернуть управление сразу (false)
                'socketTimeout' => 30,    // Таймаут соединения с сервером в секундах
                'streamTimeout' => 60,    // Таймаут чтения данных в секундах
        
                // Работа с редиректами, только в режиме обратной совместимости
                'redirect' => true,       // * Разрешить автоматическое следование редиректам
                'redirectMax' => 5,       // * Максимальное количество редиректов
                'version' => '1.0',       // * Версия HTTP-протокола: '1.0' или '1.1'
        
                // Прокси-сервер
                'proxyHost' => 'proxy.example.com', // Адрес прокси
                'proxyPort' => 3128,                // Порт прокси
                'proxyUser' => 'user',              // Логин для аутентификации
                'proxyPassword' => 'password',      // Пароль для аутентификации
        
                // SSL и безопасность
                'disableSslVerification' => false,  // Отключить проверку SSL-сертификатов (не используйте на боевом сайте)
                'privateIp' => true,                // Разрешить запросы к частным IP-адресам
                'compress' => false,                // Отправлять заголовок Accept-Encoding: gzip
                'charset' => 'utf-8',               // Кодировка для тела запроса
                'bodyLengthMax' => 0,               // Максимально допустимая длина тела запроса
        
                // Обработка ответов и событий
                'responseBuilder' => null,          // Кастомный построитель ответов, реализует Http\ResponseBuilderInterface
                'sendEvents' => true,               // Отправлять события
        
                // Отладка
                'debugLevel' => \Bitrix\Main\Web\HttpDebug::NONE, // Уровень детализации отладки
                'cookies' => [],    // * Массив файлов cookie для отправки с запросом
                'headers' => [],    // * Массив HTTP-заголовков для отправки с запросом
        
                // Использование cURL
                'useCurl' => false,                 // Использовать библиотеку cURL вместо внутренних потоков PHP
                'curlLogFile' => '',                // Путь к файлу для логов cURL, если useCurl = true
            ],
            'readonly' => false, // Разрешить изменение настроек во время выполнения
        ],

Регистрация сервисов

Секция services регистрирует пользовательские сервисы в контейнере зависимостей. Это позволяет централизованно управлять зависимостями приложения.

Подробнее в статье Сервис Локатор.

Логгеры

Секция loggers регистрирует логгеры с интерфейсом PSR-3.

'loggers' => [
            'value' => [
                // Регистрация логгера для HTTP-клиента
                'main.HttpClient' => [
                    'className' => '\\Bitrix\\Main\\Diag\\FileLogger', // Класс логгера
                    'constructorParams' => ['/home/bitrix/www/log.txt'], // Путь к файлу с параметрами конструктора 
                    'level' => \Psr\Log\LogLevel::DEBUG, // Уровень логирования: DEBUG, INFO, ERROR и так далее
        			'formatter' => 'formatter.Arguments', // Опционально: ID форматтера из сервис-локатора
                ],
                // Здесь можно добавить другие логгеры
                // 'my.component' => [
              			...
        		 	],
            ],
            'readonly' => true, // Защищает настройки от изменений во время выполнения
        ],

Подробнее в статье Логгеры.

Роутинг

Секция routing определяет, какие файлы конфигурации маршрутов подключать из /bitrix/routes/ и /local/routes/.

'routing' => [
            'value' => [
                'config' => ['web.php'], // Можно добавить другие файлы: 'api.php', 'admin.php'
            ],
                'readonly' => true, // Защищает настройки от изменений
        ],

Подробнее в статье Роутинг.

Сессии

В секции session настраивается механизм хранения сессий: файлы, Redis, БД или Memcache. Выбор механизма влияет на производительность и отказоустойчивость.

Пример конфигурации для memcache:

    'session' => [
                'value' => [
                    'mode' => 'default', // Режим работы с сессиями
                    'handlers' => [
                        'general' => [
                            'type' => 'memcache', // Тип хранилища
                            'port' => '11211', // Порт сервера
                            'host' => '127.0.0.1', // Хост сервера
                        ],
                    ],
                ]
            ]

Подробнее в статье Сессии.

Шифрование

Секция crypto хранит ключ для шифрования конфиденциальных данных. Всегда используйте уникальный ключ.

    'crypto' => [
                'value' => [
                    'crypto_key' => 'mysupersecretphrase', // Рекомендуется использовать 32-символьную строку из a-z0-9
                ],
                'readonly' => true,
            ]

Подробнее в статье Cookie-файлы.

Отправка писем

Секция smtp позволяет настроить отправку почты через внешний SMTP-сервер. Доступно с версии Главного модуля 21.900.0.

Минимальная конфигурация SMTP включает хост и логин.

'smtp' => [
            'value' => [
                'enabled' => true, // Включить отправку через SMTP
                'host' => 'smtp.host.domain', // Хост
                'login' => 'user', // Логин
            ],
            'readonly' => true,
        ],

Дополнительно можно указать параметры авторизации, нестандартный порт подключения, имя отправителя, таймаут и так далее.

'smtp' => [
            'value' => [
                'enabled' => true, // Включить отправку через SMTP
                'host' => 'smtp.host.domain', // Хост
                'port' => 1025, // Порт для подключения, если нужен нестандартный порт
                'login' => 'user', // Логин
                'password' => '123456', // Пароль для авторизации
                'isOauth' => true, // Использовать OAuth-авторизацию
                'from' => 'Имя отправителя', // Отображаемое имя отправителя
                'connection_timeout' => 10, // Таймаут подключения к серверу в секундах
                'encryption_type' => 'smtps', // Тип шифрования. Если указать 465 порт, будет использоваться `ssl`, иначе —`starttls
            ],
            'readonly' => true,
        ],

Для отладки включите опцию debug и укажите путь к файлу лога logFile.

'smtp' => [
            'value' => [
                // ...
                'debug' => true,
                'logFile' => '/absolute/path/to/file.log',
            ],
            'readonly' => true,
        ],

Если не указать путь logFile, система создаст файл mailer.log в корне сайта DOCUMENT_ROOT.

Расширенная конфигурация SMTP-серверов выполняется в административном интерфейсе на странице Настройки > Настройки продукта > Почтовые и СМС события > Настройки SMTP.

Очереди сообщений

Секция messenger содержит конфигурацию очередей.

'messenger' => [
            'value' => [
                'run_mode' => 'web', // Режим обработки сообщений: web или cli
                'brokers' => [
                    'default' => [
                        'type' => DbBroker::TYPE_CODE, // Тип брокера
                        'params' => [ // Набор параметров, который зависит от типа брокера
                            'table' => MessengerMessageTable::class,
                        ]
                    ],
                ],
                'queues' => [ // Список очередей
                    'first_queue' => [
                        'handler' => MyReceiver::class, // Обработчик очереди
                    ],
                ],
            ],
        ]

Подробнее в статье Очереди сообщений.

Язык по умолчанию

Секция default_language задает язык по умолчанию. Система будет использовать его, если перевод для текущего языка недоступен. Это гарантирует, что интерфейс никогда не будет пустым.

'default_language' => [
            'value' => 'ru', // Код языка по умолчанию, например: 'ru', 'en', 'de'
            'readonly' => true, // Защищает настройку от изменений
        ],

Получить текущее значение можно методом Bitrix\Main\Localization\Loc::getDefaultLang(). В метод нужно передать код языка.

  1. Метод проверит, есть ли переданный язык в системе.

  2. Если язык недоступен, вернет значение из default_language.

  3. Если default_language не настроен, вернет английский язык en.

Класс Configuration

Управлять настройками через API можно с помощью класса Bitrix\Main\Config\Configuration.

Создать конфигурационный файл

Если файла .settings.php нет, создайте его методом Configuration::wnc().

Bitrix\Main\Config\Configuration::wnc();

Метод wnc() полностью перезаписывает существующий файл .settings.php и удаляет текущие настройки. Используйте его только при создании нового файла.

Получить настройки секции

Статический метод getValue($name) возвращает значение указанной секции настроек.

  • $name — название секции, например, 'cache'.
// Получить настройки кеширования
        $cacheConfig = \Bitrix\Main\Config\Configuration::getValue('cache');

Установить и сохранить настройки секции

Статический метод setValue($name, $value) устанавливает значение секции и сохраняет его в конфигурационный файл.

  • $name — название секции,

  • $value — массив с настройками.

// Установить и сохранить настройки для HTTP-клиента
        \Bitrix\Main\Config\Configuration::setValue('http_client_options', [
            'value' => [
                'socketTimeout' => 60,
                'streamTimeout' => 90,
            ],
            'readonly' => false,
        ]);

Получить объект класса

Метод getInstance() возвращает объект класса Configuration для работы с несколькими настройками.

// Получить объект для работы с настройками
        $config = \Bitrix\Main\Config\Configuration::getInstance();

Добавить или изменить параметры секции

add($name, $value) — добавляет или меняет параметры секции.

  • $name — название секции,

  • $value — массив с настройками.

// Получить объект конфигурации
        $config = \Bitrix\Main\Config\Configuration::getInstance();
        
        // Добавить настройку для HTTP-клиента
        $config->add('http_client_options', [
            'value' => [
                'socketTimeout' => 60,
                'streamTimeout' => 90,
            ],
            'readonly' => false,
        ]);

Добавить защищенную секцию

Метод addReadonly($name, $value) добавляет секцию с параметром 'readonly' => true.

  • $name — название секции,

  • $value — массив с настройками.

// Получить объект конфигурации
        $config = \Bitrix\Main\Config\Configuration::getInstance();
        
        // Добавить защищенную настройку
        $config->addReadonly('custom_section', [
            'secret_key' => 'value',
        ]);

Сохранить настройки

Метод saveConfiguration() сохраняет все изменения из add() и addReadonly().

// Получить объект конфигурации
        $config = \Bitrix\Main\Config\Configuration::getInstance();
        
        // Изменить настройку
        $config->add('exception_handling', [
            'value' => ['debug' => false],
            'readonly' => false,
        ]);
        
        // Сохранить изменения
        $config->saveConfiguration();

После add() или addReadonly() всегда вызывайте saveConfiguration(), иначе изменения не сохранятся.

Предыдущая
Что дальше
Следующая
Архитектура