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 をプレフィックスとして付け、スカラー値または配列のみを保存してください。
• バックグラウンドジョブとエージェントの実行前にセッションは書き込まれて閉じられるため、addBackgroundJob()による書き込みは失われます（bitrix-background-jobs）。CLI、エージェント、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 をキーとして保存され、リクエストの最後に書き込まれます。files キャッシュでは$_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 は、lifetimeではなくphp.iniのsession.gc_maxlifetimeです。
• Redis オプション：host、port、password、servers（クラスター用の['host'=>…, 'port'=>…]のリスト）、serializer、persistent、failover、timeout、readTimeout、keyPrefix、exclusiveLock（ロック値は要求されたページです。ロックタイムアウトのエラーに表示されます）。Memcache：host、port、servers、connectionTimeout、keyPrefix、exclusiveLock。File：savePath。Database：テーブル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）。