bitrix-storage

ストレージ：Option、Feature、永続ストレージ

ベースライン：main 23.0+ · 検証済み：main 26.800.0

要件	使用するもの
デプロイ時の設定、シークレット	.settings_extra.php / env（bitrix-settings）
管理者が編集できる永続的なモジュール設定	Config\Option + default_option.php
機能の切り替え、ユーザーごとの段階的なロールアウト	Config\Feature（main 26.700 以降）；それ以前：Option の Y/N
N 秒間保持する必要があるサーバー状態	PersistentStorageInterface（main 25.1100 以降）；それ以前：有効期限カラムを持つ独自の ORM テーブル
派生データ（いつ消えてもよいもの）	キャッシュ（bitrix-caching）
訪問者ごとの状態	セッション（bitrix-sessions）
大きなバイナリデータ	ファイル（bitrix-files）

頻繁に更新される実行時状態（進捗、トークン、チェックポイント）に Option を使ったり、保持が必要なデータにキャッシュを使ったり、シークレットに永続ストレージを使ったりしないでください。

Option

use Bitrix\Main\Config\Option;

$interval = (int)Option::get('vendor.module', 'sync_interval');   // falls back to default_option.php
Option::set('vendor.module', 'sync_interval', (string)$interval);
$stored = Option::getRealValue('vendor.module', 'sync_interval'); // null if never stored
$all = Option::getForModule('vendor.module');
Option::delete('vendor.module', ['name' => 'sync_interval']);   // no filter = all module options

• 値は文字列です。境界で型変換してください。デフォルト値：bitrix-modules（default_option.php）。
• サイトごとの上書き：$siteId を渡します。空のサイト ID はグローバルを意味します。
• set() はオプションのキャッシュをクリアし、option_triggers.php を実行し、OnAfterSetOption_<name> / OnAfterSetOption を発火します。リクエストごとの書き込みには使わないでください。
• 「未設定」とデフォルト値を区別するには、getRealValue() またはセンチネル値をデフォルトとして指定します（Option::get('main', 'x', 'Z')）。

Feature フラグ — main 26.700 以降

フラグは、モジュールの lib/ にあるクラスです（モジュール名は名前空間から導出されます：Vendor\Shop\… → vendor.shop）。

namespace Vendor\Shop\Config\Feature;

use Bitrix\Main\Config\Feature\AbstractFlag;
use Bitrix\Main\Config\Feature\Context;

final class NewCheckoutFlag extends AbstractFlag
{
    public function enabledByDefault(): bool
    {
        return false;
    }

    public function getRequirements(): array
    {
        return [static fn (Context $context): bool => $context->userId !== null]; // all must pass
    }
}

use Bitrix\Main\Config\Feature;
use Bitrix\Main\Config\Feature\Rules\UserIdRule;

if (Feature::isEnabled(NewCheckoutFlag::class)) { /* new flow */ }
Feature::allow(NewCheckoutFlag::class, UserIdRule::class, ['userIds' => [1, 42]]); // beta users
Feature::enable(NewCheckoutFlag::class);          // everyone; stored in b_feature_flag
Feature::resetToDefault(NewCheckoutFlag::class);  // rules stay: clearRules()

• 判定順序：要件 → deny ルール → allow ルール → 保存値 → enabledByDefault()。
• ルール：UserIdRule（userIds）、ModuleMinVersionRule（module、minVersion）；独自ルールは AbstractRule を継承します（static createFromConfig(array $config)、check(Context $context): bool）。
• コンテキスト：デフォルトでは現在のユーザーです。new Context(?int $userId = null, array $params =) を使用します。ID が 1 未満の場合は匿名ユーザーです。
• 注意点：不明またはロードできないフラグクラスは true を返します（「提供後に削除された」ものとして扱われます）。名前空間のモジュールがインストールされていない場合、enable()/disable() は何もせずに終了します。フラグを php_interface に定義しないでください。値とルールは 24 時間キャッシュされます。テーブルを直接編集した後は Feature::clearCache() を呼び出してください。onEnable()/onDisable() は、保存値に実際の変更があった場合にのみ発火します。

永続ストレージ — main 25.1100 以降

$storage = \Bitrix\Main\DI\ServiceLocator::getInstance()
    ->get(\Bitrix\Main\Data\Storage\PersistentStorageInterface::class);

$storage->set('vendor.module.import.42', ['step' => 3], 3600); // TTL required
$state = $storage->get('vendor.module.import.42');              // null after expiry
$storage->delete('vendor.module.import.42');

• PSR-16 API。DB を使用します（ConnectionBasedPersistentStorage）。キーは 255 文字以下（module.feature.id）、値は JSON にシリアライズ可能である必要があります。
• TTL：正の int 秒数、または DateInterval。null/≤ 0 の場合は InvalidTtlException が発生します。7 日以下にしてください。clear() はサポートされていません。
• new DeferredStorageDecorator($storage) は、save() の呼び出し時またはデストラクター実行時まで書き込みをバッファーします。1 リクエスト内で多数の書き込みがあり、クラッシュ時のデータ消失を許容できる場合に使用します。