Каждый модуль на Битриксе рано или поздно обрастает настройками: ключ внешнего API, TTL кэша, признак тестового режима, e‑mail для уведомлений. Хранить это в константах или зашивать в код неудобно - каждое изменение требует правки файлов на проде. Для таких задач в D7 есть класс Option в Битрикс D7, который читает и пишет значения в базу с привязкой к модулю и, при необходимости, к конкретному сайту. Разбираю, как им пользоваться на практике, чем он отличается от старого COption и как вывести собственную страницу настроек в админке.
Зачем модулю отдельное хранилище настроек
Когда пишешь модуль под конкретную задачу клиента - интеграцию с CRM, вебхук в Telegram, кастомный экспорт в 1С - почти всегда нужны параметры, которые администратор должен менять без правки кода: API-ключ, адрес внешнего сервиса, включён ли тестовый режим. Зашивать такие значения в константы или в файлы модуля неправильно: они попадают в репозиторий, их не поменять через интерфейс, а при обновлении кода можно случайно откатить рабочий ключ на старый.
Опции модуля - штатный механизм Битрикса для этой задачи. Значения лежат в базе, привязаны к идентификатору модуля, читаются и пишутся через простой API, и любой другой код на сайте - агент, обработчик события, компонент - может обратиться к ним по имени модуля, не зная, как физически устроено хранилище.
Класс Option в D7: get, set и delete
В новом ядре за настройки отвечает класс Bitrix\Main\Config\Option. У него три метода, которые закрывают почти всю практику: get, set и delete.
use Bitrix\Main\Config\Option;
use Bitrix\Main\Loader;
Loader::includeModule("mycompany.mymodule");
$moduleId = "mycompany.mymodule";
// записываем значение
Option::set($moduleId, "api_key", "sk-live-12345");
// читаем с дефолтом на случай, если опция ещё не задана
$apiKey = Option::get($moduleId, "api_key", "");
$cacheTtl = (int)Option::get($moduleId, "cache_ttl", 3600);
// удаляем одну опцию
Option::delete($moduleId, ["name" => "api_key"]);
// удаляем все опции модуля, например при деинсталляции
Option::delete($moduleId);
Option::get принимает идентификатор модуля, имя опции и значение по умолчанию, которое вернётся, если опция ещё не создана - это избавляет от отдельной проверки на существование. Option::set создаёт запись или обновляет уже существующую. Option::delete с фильтром убирает одну конкретную опцию, а без фильтра - сразу все опции модуля, это удобно вызывать в обработчике удаления модуля.
Значения хранятся строками, поэтому числовые и булевы настройки приводи к нужному типу сам при чтении, как cacheTtl в примере выше.
Бесплатный материал
🎁 Полезный скрипт в подарок
Подпишитесь на Telegram - пришлю готовый скрипт по этой теме.
Без спама. Отписка в 1 клик.
Старый COption и новый Option: что изменилось
До D7 за настройки отвечал класс COption с методами GetOptionString, SetOptionString и RemoveOption. Он никуда не делся и продолжает работать в актуальных версиях, а в документации некоторых старых классов ядра прямо указан аналог в D7 в качестве рекомендуемой замены.
Разница в основном в стиле кода: Option::get и Option::set - статические методы из отдельного неймспейса, которые проще тестировать и которые ожидает остальной D7-код модуля - ORM, обработчики событий, HTTP-контекст. Если пишешь новый модуль, логичнее сразу брать Option. Если дорабатываешь старый, где уже есть COption::GetOptionString по всему коду, переписывать всё разом не обязательно - оба класса читают одну и ту же таблицу и спокойно работают вперемешку.
Таблица b_option и мультисайтовость
Физически значения лежат в таблице b_option: столбцы MODULE_ID, NAME, VALUE и SITE_ID. Из-за последнего столбца у Option::get и Option::set есть четвёртый параметр - идентификатор сайта. Если не передавать его в Option::set, опция общая для всех сайтов на ядре; Option::get без этого параметра читает значение для текущего сайта. Если передать конкретный SITE_ID, значение будет действовать только для этого сайта, а чтение с тем же SITE_ID вернёт именно его - и упадёт на общее значение, если для сайта своей записи нет.
use Bitrix\Main\Config\Option;
$moduleId = "mycompany.mymodule";
// значение только для сайта s2
Option::set($moduleId, "sender_email", "shop@example.com", "s2");
// если для текущего сайта своего значения нет, вернётся общее (SITE_ID = "")
$siteId = SITE_ID;
$senderEmail = Option::get($moduleId, "sender_email", "info@example.com", $siteId);
На практике это нужно нечасто - разве что при нескольких сайтах на одном ядре, когда у каждого свой e‑mail отправителя или список получателей уведомлений, а остальные настройки общие для всех.
Страница настроек модуля в админке
Чтобы администратор менял значения через интерфейс, а не через консоль разработчика, в папке модуля нужен файл options.php: /local/modules/[ID модуля]/options.php. Ядро само подключает его, когда администратор открывает меню Настройки → Настройки продукта → Настройки модулей → [название модуля] - по факту это переход на /bitrix/admin/settings.php с параметром mid, а settings.php уже сам подставляет содержимое вашего options.php.
Файл - обычный PHP-скрипт, который settings.php подключает внутри уже собранной админской страницы, поэтому admin-прологи в нём подключать не нужно: достаточно проверить sessid, разобрать POST, сохранить значения через Option::set и вывести форму с текущими значениями.
<?php
use Bitrix\Main\Config\Option;
use Bitrix\Main\Context;
use Bitrix\Main\Loader;
$moduleId = "mycompany.mymodule";
if (!Loader::includeModule($moduleId)) {
ShowError("Модуль ".$moduleId." не установлен");
return;
}
$request = Context::getCurrent()->getRequest();
if ($request->isPost() && check_bitrix_sessid()) {
Option::set($moduleId, "api_key", trim($request->getPost("api_key")));
Option::set($moduleId, "cache_ttl", (int)$request->getPost("cache_ttl"));
LocalRedirect($APPLICATION->GetCurPage()."?mid=".urlencode($moduleId)."&lang=".LANGUAGE_ID);
}
$apiKey = Option::get($moduleId, "api_key", "");
$cacheTtl = Option::get($moduleId, "cache_ttl", 3600);
$APPLICATION->SetTitle("Настройки модуля");
Дальше выводится обычная HTML-форма с нужными полями, которая отправляет POST на ту же страницу settings.php с параметрами mid и lang - логика сохранения уже отработана в блоке выше. Если собирать такие админки руками некогда, эту работу тоже можно отдать на сторону - я беру доработку и поддержку модулей 1С-Битрикс под такие задачи, когда клиенту нужно, чтобы настройки жили в интерфейсе, а не в коде разработчика.
Кэш и типичные ошибки при работе с опциями
Option, как и старый COption, при первом обращении к модулю за один хит подгружает разом все его опции и держит их в статическом кэше на время запроса - это значит, что можно вызывать Option::get много раз в разных местах кода за один хит без риска устроить лишние запросы к базе. А вот кэшировать результат в собственной статической переменной между запросами не стоит - изменение опции через админку и LocalRedirect на ту же страницу такой кэш не увидит до следующего хита.
Из ошибок, которые встречаю в клиентском коде регулярно:
- Забывают привести значение к нужному типу - галка «включено» хранится строкой «Y» или «N», а код проверяет её через сравнение с true и получает true на любой непустой строке, включая «N».
- Опечатка в идентификаторе модуля - Option::get с несуществующим ID модуля просто вернёт значение по умолчанию без единой ошибки, поэтому опечатку легко не заметить неделями.
Возможности 1С-Битрикс и структура D7 меняются от обновления к обновлению, поэтому перед внедрением в проект я сверяюсь с актуальной документацией вендора.
Частые вопросы
Чем Option отличается от COption на практике?
По возможностям почти ничем - оба читают и пишут одну и ту же таблицу b_option. Разница в оформлении кода: Option - статический класс из неймспейса Bitrix\Main\Config, ожидаемый в D7-коде, COption - методы старого ядра вроде GetOptionString и SetOptionString. Для нового кода логичнее брать Option, для правок в старом модуле можно оставить то, что уже используется в файле.
Можно ли хранить в опциях модуля пароли и токены?
Технически да - значение ляжет в b_option обычной строкой. Но это таблица в базе данных сайта, а не отдельное защищённое хранилище секретов: при бэкапе или экспорте она уедет вместе с остальными данными. Для токенов внешних сервисов на большинстве проектов это приемлемо, но доступ к разделу настроек стоит закрывать правами и не выводить сохранённое значение обратно в форму открытым текстом.
Что происходит с опциями при удалении модуля?
Сами по себе строки в b_option при деинсталляции модуля никуда не деваются - это забота разработчика. В обработчике удаления модуля стоит явно вызвать Option::delete с идентификатором модуля и без фильтра, тогда все его настройки уйдут из базы вместе с модулем.
Опции модуля одинаковы на всех сайтах при мультисайтовости?
По умолчанию да - опция без указанного SITE_ID общая для всех сайтов на одном ядре. Если нужно разное значение для каждого сайта, при сохранении и чтении передаётся четвёртый параметр Option::set и Option::get с идентификатором нужного сайта, тогда для этого сайта появится своя строка в таблице, а остальные сайты продолжат получать общее значение.