bitrix-storage
Covers choosing between Option, Persistent Storage, Cache and sessions — PersistentStorageInterface (main 25.1100+), DeferredStorageDecorator, Bitrix\Main\Config\Option for permanent module settings. Applied when deciding where to put config vs TTL state vs derived cache. Key ter
Install
npx skills add https://github.com/bxmaximum/bitrix-framework-skills/tree/main/skills/bitrix-storage
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install bxmaximum-bitrix-framework-skills@llmmart
git clone https://github.com/bxmaximum/bitrix-framework-skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole bxmaximum/bitrix-framework-skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
Хранение: Option, Feature и данные с TTL
Baseline: main 23.0+ · Verified: main 26.1000.0
Перед PHP-кодом прочитай bitrix-framework, если ещё не читал его в этой задаче.
| Задача | Использовать |
|---|---|
| Конфигурация развёртывания и секреты | .settings_extra.php / env (bitrix-settings) |
| Постоянная настройка модуля, редактируемая администратором | Config\Option + default_option.php |
| Флаг возможности, постепенное включение по пользователям | Config\Feature (Since main 26.700); раньше Option Y/N |
| Серверное состояние на N секунд | PersistentStorageInterface (Since main 25.1100); раньше своя ORM-таблица со сроком действия |
| Производные данные, которые можно потерять | Кеш (bitrix-caching) |
| Состояние посетителя | Сессия (bitrix-sessions) |
| Большие двоичные данные | Файлы (bitrix-files) |
Не используй Option для частых изменений прогресса, токенов и контрольных точек; кеш — для обязательного сохранения данных; Persistent storage — для секретов.
Option
use Bitrix\Main\Config\Option;
$interval = (int)Option::get('vendor.module', 'sync_interval'); // запасное значение из default_option.php
Option::set('vendor.module', 'sync_interval', (string)$interval);
$stored = Option::getRealValue('vendor.module', 'sync_interval'); // null, если никогда не сохранялось
$all = Option::getForModule('vendor.module');
Option::delete('vendor.module', ['name' => 'sync_interval']); // без фильтра удаляет все настройки модуля
- Значения — строки: приводи типы на границе. Значения по умолчанию:
bitrix-modules(default_option.php). - Для значения по сайту передавай
$siteId; пустой сайт означает глобальное значение. set()очищает кеш настроек, запускаетoption_triggers.php, отправляетOnAfterSetOption_<name>/OnAfterSetOption. Не подходит для записи на каждом хите.- Отличай отсутствие записи от значения по умолчанию:
getRealValue()или сигнальное значение (Option::get('main', 'x', 'Z')).
Флаги возможностей (Since 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]; // должны пройти все требования
}
}
use Bitrix\Main\Config\Feature;
use Bitrix\Main\Config\Feature\Rules\UserIdRule;
if (Feature::isEnabled(NewCheckoutFlag::class)) { /* новый сценарий */ }
Feature::allow(NewCheckoutFlag::class, UserIdRule::class, ['userIds' => [1, 42]]); // тестовые пользователи
Feature::enable(NewCheckoutFlag::class); // для всех; хранится в b_feature_flag
Feature::resetToDefault(NewCheckoutFlag::class); // правила остаются: 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()срабатывают только при реальном изменении сохранённого значения.
Постоянное хранилище с TTL (Since 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 обязателен
$state = $storage->get('vendor.module.import.42'); // null после истечения
$storage->delete('vendor.module.import.42');
- API PSR-16 с БД (
ConnectionBasedPersistentStorage). Ключ до 255 символов (module.feature.id), значение сериализуемо в JSON. - TTL: положительное число секунд
intилиDateInterval;null/≤ 0вызываетInvalidTtlException. Ограничивай семью днями.clear()не поддерживается. new DeferredStorageDecorator($storage)откладывает записи доsave()или уничтожения: для множества записей за хит, когда потеря при сбое допустима.
Files (bitrix-framework-skills)
-
SKILL.md 6.5 KB
--- name: bitrix-storage description: 'Используй для хранения состояния Битрикса: Config\Option, флаги Config\Feature и временные данные PersistentStorage. Выбор между БД, кешем и сессией.' --- # Хранение: Option, Feature и данные с TTL Baseline: main 23.0+ · Verified: main 26.1000.0 Перед PHP-кодом прочитай `bitrix-framework`, если ещё не читал его в этой задаче. | Задача | Использовать | | --- | --- | | Конфигурация развёртывания и секреты | `.settings_extra.php` / env (`bitrix-settings`) | | Постоянная настройка модуля, редактируемая администратором | `Config\Option` + `default_option.php` | | Флаг возможности, постепенное включение по пользователям | `Config\Feature` (**Since main 26.700**); раньше `Option` `Y`/`N` | | Серверное состояние на N секунд | `PersistentStorageInterface` (**Since main 25.1100**); раньше своя ORM-таблица со сроком действия | | Производные данные, которые можно потерять | Кеш (`bitrix-caching`) | | Состояние посетителя | Сессия (`bitrix-sessions`) | | Большие двоичные данные | Файлы (`bitrix-files`) | Не используй `Option` для частых изменений прогресса, токенов и контрольных точек; кеш — для обязательного сохранения данных; Persistent storage — для секретов. ## Option ```php use Bitrix\Main\Config\Option; $interval = (int)Option::get('vendor.module', 'sync_interval'); // запасное значение из default_option.php Option::set('vendor.module', 'sync_interval', (string)$interval); $stored = Option::getRealValue('vendor.module', 'sync_interval'); // null, если никогда не сохранялось $all = Option::getForModule('vendor.module'); Option::delete('vendor.module', ['name' => 'sync_interval']); // без фильтра удаляет все настройки модуля ``` - Значения — строки: приводи типы на границе. Значения по умолчанию: `bitrix-modules` (`default_option.php`). - Для значения по сайту передавай `$siteId`; пустой сайт означает глобальное значение. - `set()` очищает кеш настроек, запускает `option_triggers.php`, отправляет `OnAfterSetOption_<name>` / `OnAfterSetOption`. Не подходит для записи на каждом хите. - Отличай отсутствие записи от значения по умолчанию: `getRealValue()` или сигнальное значение (`Option::get('main', 'x', 'Z')`). ## Флаги возможностей (**Since main 26.700**) Флаг — класс в `lib/` своего модуля (модуль определяется по пространству имён: `Vendor\Shop\…` → `vendor.shop`): ```php 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]; // должны пройти все требования } } ``` ```php use Bitrix\Main\Config\Feature; use Bitrix\Main\Config\Feature\Rules\UserIdRule; if (Feature::isEnabled(NewCheckoutFlag::class)) { /* новый сценарий */ } Feature::allow(NewCheckoutFlag::class, UserIdRule::class, ['userIds' => [1, 42]]); // тестовые пользователи Feature::enable(NewCheckoutFlag::class); // для всех; хранится в b_feature_flag Feature::resetToDefault(NewCheckoutFlag::class); // правила остаются: 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()` срабатывают только при реальном изменении сохранённого значения. ## Постоянное хранилище с TTL (**Since main 25.1100**) ```php $storage = \Bitrix\Main\DI\ServiceLocator::getInstance() ->get(\Bitrix\Main\Data\Storage\PersistentStorageInterface::class); $storage->set('vendor.module.import.42', ['step' => 3], 3600); // TTL обязателен $state = $storage->get('vendor.module.import.42'); // null после истечения $storage->delete('vendor.module.import.42'); ``` - API PSR-16 с БД (`ConnectionBasedPersistentStorage`). Ключ до 255 символов (`module.feature.id`), значение сериализуемо в JSON. - TTL: положительное число секунд `int` или `DateInterval`; `null`/`≤ 0` вызывает `InvalidTtlException`. Ограничивай семью днями. `clear()` не поддерживается. - `new DeferredStorageDecorator($storage)` откладывает записи до `save()` или уничтожения: для множества записей за хит, когда потеря при сбое допустима.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.