Справочник API

Для чтения настроек используется класс Kokhanenko\Settings\Settings. Вызовы выполняются после подключения ядра Битрикса и успешного Loader::includeModule('kokhanenko.settings').

Данные для примеров

В примерах используются настройки на сайте s1: base.useButton = true, base.buttonTitle = 'Связаться с нами'; в contacts.departments — множественный список с вариантами sales / «Продажи», support / «Поддержка», выбран support. Как создать их — в руководстве администратора.

get()

PHP

Settings::get(
    string $sectionCode,
    string $key,
    ?string $siteId = null,
    mixed $default = null
): mixed

Возвращает типизированное значение настройки.

PHP

Settings::get('base', 'useButton', 's1', false); // true
Settings::get('base', 'buttonTitle', 's1', '');  // 'Связаться с нами'
Settings::get('contacts', 'departments', 's1'); // ['support']
Settings::get('base', 'missingKey', 's1', 'нет'); // 'нет'

note

$default возвращается, только если настройка не найдена. Выключенный флажок вернёт false, пустой одиночный список — null, пустой множественный — [], независимо от переданного $default. См. таблицу типов.

all()

PHP

Settings::all(string $sectionCode, ?string $siteId = null): array

Возвращает массив ключ => типизированное значение настроек раздела. Если их нет — [].

PHP

Settings::all('contacts', 's1');
// ['departments' => ['support']]
// Если в contacts есть phone или другие настройки,
// они тоже попадут в результат.

В массив входят только значения. Названия полей, подсказки и другие параметры настройки в него не включаются. Если дочернее поле скрыто выключенным родителем, его значение всё равно может присутствовать в результате.

has()

PHP

Settings::has(string $sectionCode, string $key, ?string $siteId = null): bool

Проверяет наличие настройки по адресу.

PHP

Settings::has('base', 'useButton', 's1');  // true, даже если флажок выключен
Settings::has('base', 'missingKey', 's1'); // false

Не заменяйте эту проверку empty(Settings::get(...)): пустые значения могут быть корректными.

selectedOptions()

PHP

Settings::selectedOptions(
    string $sectionCode,
    string $key,
    ?string $siteId = null
): array

Возвращает выбранные варианты enum с подписями:

PHP

Settings::selectedOptions('contacts', 'departments', 's1');
// [
//     ['value' => 'support', 'label' => 'Поддержка'],
// ]

Для одиночного списка результат тоже массив пар, а не одна пара.
Порядок соответствует порядку вариантов в определении списка, а не порядку выбора пользователем.
Если ничего не выбрано или настройка отсутствует, результат []. Для различения этих ситуаций вызовите has().
Для существующей настройки другого типа выбрасывается LogicException.
Для получения только кодов используйте get().

clearCache()

PHP

Settings::clearCache(): void

Сбрасывает кеш модуля через SettingsCache, возвращаемого значения нет. Штатные изменяющие операции сервисов инвалидируют этот кеш автоматически.

PHP

Settings::clearCache();
$title = Settings::get('base', 'buttonTitle', 's1', '');

note

clearCache() очищает кеш модуля, но не готовый HTML в кеше компонентов или страниц Битрикса. Если страница отдаётся из такого кеша, новый вызов get() может не выполняться. Подробнее — хранение и кеширование.

Выбор сайта

siteId — код сайта Битрикса, например s1, а не домен. Если он отсутствует, пустой или состоит из пробелов, используется сайт по умолчанию из настроек Битрикса. Это не обязательно сайт текущей публичной страницы.

Если сайт по умолчанию определить не удалось, возникает ошибка. Для многосайтовых шаблонов передавайте нужный код явно; не рассчитывайте на автоматическое наследование значений глобального раздела.

Магические методы: Settings::base()

Код раздела можно использовать как имя статического метода. Вызов обрабатывается через __callStatic() и служит сокращением для get() или all(): Settings::base() читает раздел base, Settings::contacts() — раздел contacts.

PHP

Settings::base('buttonTitle', 's1', '');
// То же, что Settings::get('base', 'buttonTitle', 's1', '').

Settings::base(null, 's1');
// То же, что Settings::all('base', 's1').

Settings::base();
// Все значения base на сайте по умолчанию.

Аргументы передаются в следующем порядке:

Аргумент	Назначение	Если не передан
1. Ключ настройки	Строка для чтения одного значения; `null` для всего раздела	Читается весь раздел
2. Код сайта	Например, `'s1'`	Используется сайт по умолчанию Битрикса
3. Резервное значение	Возвращается, если настройка с указанным ключом не найдена	`null`

Для чтения всего раздела на конкретном сайте передайте null первым аргументом, как в Settings::base(null, 's1'). В этом случае третий аргумент не допускается. Именованные аргументы не поддерживаются.

Код раздела должен начинаться с латинской буквы и содержать только латинские буквы, цифры и _. Если он совпадает с именем существующего метода фасада (get, all, has, selectedOptions, clearCache), используйте явные get() и all(): магический вызов не перехватывает существующие методы.

Результаты и обработка ошибок совпадают с соответствующим явным методом. Для проверки наличия настройки и получения подписей списка используйте has() и selectedOptions().

Ошибки и границы API

Отсутствие настройки — штатный результат. Некорректный адрес, невозможность определить сайт, повреждённые данные и ошибки чтения — ошибки, которые не следует маскировать резервным значением. При необходимости обрабатывайте исключения на уровне приложения и записывайте их в журнал проекта, не выводя технические подробности посетителю.

Класс Settings предназначен для чтения и не имеет метода set(). Для записи из PHP см. примеры SettingsService. Используйте описанные там методы строгого сервиса; старые совместимые методы могут принимать и возвращать данные иначе.