Bitrix Settings

Kernel Configuration (.settings.php)

Baseline: main 23.0+. Features newer than baseline are marked Since.

Primary config: /bitrix/.settings.php or /local/.settings.php (Since main 24.100). Overrides: /bitrix/.settings_extra.php or /local/.settings_extra.php (Since main 24.100).

Errors in .settings.php can break the site. Back up before changes.

Also maintain /local/php_interface/dbconn.php for legacy kernel compatibility even when using D7 only.

Structure

Each section:

'section_name' => [
    'value' => [ /* settings */ ],
    'readonly' => true,  // true = no runtime API changes
],

Global vs Module .settings.php

Routing is global-only: the router loads files listed in global routing.config from /local/routes/ and /bitrix/routes/ only. Module route files must be required from /local/routes/web.php — a module .settings.php routing section does not auto-load them.

There is no validation section in .settings.php. Use ValidationService via ServiceLocator (main.validation.service in main module services). See skill bitrix-validation.

Key Sections

exception_handling

Keys applied in Application::initializeExceptionHandler() (verified):

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

smtp (mail via SMTP)

Since main 21.900.0. Two roles of the smtp section:

1. Enable local SMTP connections. Per-sender SMTP connections are created in Admin → Settings → Product settings → Mail and SMS events → SMTP settings, but they are used for sending only if the smtp section with enabled => true exists in .settings.php — enabled is mandatory and checked strictly (=== true, boolean, not 'Y'/1).

'smtp' => [
    'value' => [
        'enabled' => true,  // required — without it admin-created SMTP connections are ignored
        'debug' => true,    // optional: log SMTP dialogue
        'log_file' => '/home/bitrix/www/bitrix/mailer.log', // optional (BitrixVM example path)
    ],
    'readonly' => true,
],

2. Default SMTP server — add connection parameters to the same section:

'smtp' => [
    'value' => [
        'enabled' => true,
        'host' => 'smtp.host.domain',
        'port' => 465,
        'login' => 'user',
        'password' => 'password',
        'from' => 'user@example.com',   // sender address
        'connection_timeout' => 10,     // seconds
        'encryption_type' => 'smtps',   // SMTPS for port 465, STARTTLS for other ports
        'debug' => true,                // optional
        'logFile' => '/home/bitrix/www/bitrix/mailer.log', // optional
    ],
    'readonly' => true,
],

• log_file vs logFile (kernel Smtp\Mailer::getActualConfiguration): when a per-sender SMTP connection is used (role 1), the kernel reads log_file from the section; when the section itself is the default server (role 2), the raw section array is used and the key read is logFile. Set the matching key for your case (or both). If omitted, the log goes to mailer.log in DOCUMENT_ROOT; debug is the same key in both cases.
• The default server (role 2) is used only when both host and login are filled; port defaults to 465, connection_timeout to 30 s.
• encryption_type: 'smtps' (lowercase) — kernel picks SMTPS on port 465, STARTTLS on other ports; 'smtp' = no encryption. There is no separate 'starttls' value.
• Extra key force_from => true — rewrite the From: header of every message with the section's from.
• Use encryption with a valid CA-signed certificate matching the server name — a self-signed certificate fails TLS verification.

cookies / http_client_options / cache_flags (examples)

'cookies' => [
    'value' => [
        'secure' => false,
        'http_only' => true,
    ],
    'readonly' => false,
],

'http_client_options' => [
    'value' => [
        // merged into every new HttpClient — redirect, timeouts, etc.
        'socketTimeout' => 30,
        'streamTimeout' => 60,
    ],
    'readonly' => false,
],

'cache_flags' => [
    'value' => [
        'config_options' => 3600,
        // ORM: "b_tablename_max_ttl" / "b_tablename_min_ttl" (see Entity::getCacheTtl)
    ],
    'readonly' => false,
],

'ui' => [
    'value' => [
        'a11y' => [
            'restoreLostFocus' => false,
            'useFocusTrapInDialogs' => false,
        ],
    ],
    'readonly' => false,
],

composer

'composer' => [
    'value' => ['config_path' => '../composer.json'],
    'readonly' => true,
],

crypto

Encryption keys for CryptoField, encrypted cookies. Store keys outside git — use .settings_extra.php or environment.

readonly

• true — protects critical settings (DB, services) from runtime modification.
• false — allows runtime changes (e.g. exception_handling).

Checklist

• User overrides in /local/.settings.php, not edited /bitrix/.settings.php.
• debug => false on production.
• Secrets in .settings_extra.php or env vars.
• readonly => true for connections and services.
• Module services / controllers / console in module .settings.php; routing only via global + /local/routes/.
• No fictional validation section — use main.validation.service.