bitrix-sessions

会话

基线：main 23.0+ · 已验证：main 26.800.0

切勿使用 $_SESSION：它会绕过延迟启动、只读和虚拟模式。

use Bitrix\Main\Application;

$session = Application::getInstance()->getSession(); // SessionInterface + ArrayAccess
$session->set('vendor.wizard', ['step' => 2]);
$state = $session->get('vendor.wizard');              // null if missing
if ($session->has('vendor.flash')) { $msg = $session->get('vendor.flash'); $session->remove('vendor.flash'); }
$session->regenerateId();                             // after login / privilege change

• 键名添加模块 ID 前缀；仅存储标量和数组。
• 后台作业和 Agent 运行前，会话会先写入并关闭：addBackgroundJob() 中的写入会丢失（bitrix-background-jobs）。CLI、Agent 和 Messenger 没有会话。

本地会话 —“会话缓存”

$local = Application::getInstance()->getLocalSession('vendor_cart'); // separate container per name
$local->set('productIds', [1, 2, 3]);
$ids = $local['productIds'] ?? [];

• 数据存储在 cache 引擎（Redis/Memcache/APC）中，以会话 ID 为键，并在请求结束时保存；使用文件缓存时，会退回到 $_SESSION。
• TTL：.settings.php 'session_local_storage' => ['value' => ['ttl' => 86400]]。
• 适用于购物车、筛选条件、向导草稿：这类数据较大或经常变更，不应让主会话变得臃肿或被锁定。

内核会话

Application::getInstance()->getKernelSession() 保存内核数据（身份验证、sessid）。在 default 模式下，它是主会话；在 separated 模式下，它使用加密 Cookie（crypto_key），且不支持对象。不要在其中存储应用数据。

模式（在 prolog_before.php 之前定义）

• define('BX_SECURITY_SESSION_READONLY', true); — 处理程序读取时不加锁，且绝不写入。适用于并行的只读 AJAX（建议、计数器）；更改会被丢弃。
• define('BX_SECURITY_SESSION_VIRTUAL', true); — 使用内存中的会话，不使用 Cookie，也不存储任何内容。适用于使用令牌进行身份验证的 REST/Webhook。
• define('BX_FORCE_DISABLE_SEPARATED_SESSION_MODE', true); — 强制脚本使用 default 模式。

session 部分（bitrix-settings）

'session' => [
    'value' => [
        'mode' => 'separated',              // 'default' | 'separated'
        'lifetime' => 14400,                // kernel cookie lifetime, separated mode only
        'handlers' => [
            'kernel' => 'encrypted_cookies',  // the only allowed kernel handler
            'general' => [
                'type' => 'redis',            // file | database | redis | memcache | null
                'host' => '127.0.0.1',
                'port' => 6379,
                'keyPrefix' => 'site1',       // default 'BX'; unique per site sharing a server
            ],
        ],
        'regenerateIdAfterLogin' => true,
        'ignoreSessionStartErrors' => false, // true: hit continues if storage is down
    ],
    'readonly' => true,
],

• separated：内核数据存储在 Cookie 中，通用会话会在首次访问时延迟启动——不会触及会话的匿名请求不会访问存储。
• Redis/Memcache 的通用会话 TTL 使用 php.ini 中的 session.gc_maxlifetime，而非 lifetime。
• Redis 选项：host、port、password、servers（集群列表，格式为 ['host'=>…, 'port'=>…]）、serializer、persistent、failover、timeout、readTimeout、keyPrefix、exclusiveLock（锁的值为请求的页面，会显示在锁超时错误中）。Memcache 选项：host、port、servers、connectionTimeout、keyPrefix、exclusiveLock。文件选项：savePath。数据库：表 b_user_session（无其他键）。
• 如果没有 session 部分，且 php.ini 中的 session.save_handler 不等于 files，则直接使用 PHP 自带的处理程序。
• 每个可写会话在整个请求期间都会被锁定（Redis/Memcache 最多等待约 60 秒，然后触发致命错误）：同一用户的并行 AJAX 请求会串行运行——没有写入内容时请使用 BX_SECURITY_SESSION_READONLY。

安全

• 会话 Cookie 始终启用 HttpOnly；Secure/SameSite 由 php.ini 中的 session.cookie_secure / session.cookie_samesite 决定。
• 登录和权限变更时重新生成 ID（使用 regenerateIdAfterLogin 或 regenerateId()）。
• 切勿在会话中存储机密信息或完整的用户对象；每次请求都要重新检查权限（bitrix-security）。