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')）。

功能标志 — 自 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 h；直接编辑表后调用 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；由数据库提供支持（ConnectionBasedPersistentStorage）。键最长为 255 个字符（module.feature.id），值必须可序列化为 JSON。
• TTL：正 int 秒数或 DateInterval；null/≤ 0 → InvalidTtlException。保持在 7 天以内。clear() 不受支持。
• new DeferredStorageDecorator($storage) 会将写入缓冲到调用 save() 或对象销毁时——适用于每次请求多次写入且可接受崩溃时数据丢失的场景。