Подключение в коде

Чтобы вывести значение настройки на сайте, подключите модуль и прочитайте нужный ключ через класс Settings. Код выполняется внутри шаблона или скрипта, где уже подключено ядро Битрикса.

В примере читаем подпись кнопки base.buttonTitle на сайте s1. Эта настройка создаётся при чистой установке модуля:

use Bitrix\Main\Loader;
use Kokhanenko\Settings\Settings;

if (Loader::includeModule('kokhanenko.settings')) {
    $title = Settings::get('base', 'buttonTitle', 's1', '');
    $values = Settings::all('base', 's1');
    $exists = Settings::has('base', 'buttonTitle', 's1');
}

Фасад возвращает настройки и типизированные значения. boolean — это bool, а не legacy-строка '1'. Коды списка возвращает get(), подписи — selectedOptions(). См. точную модель и справочник методов.

Сокращённые (магические) вызовы

Вместо get() и all() можно использовать код раздела как имя статического метода:

// Все настройки раздела base на сайте по умолчанию.
$values = Settings::base();
// То же, что Settings::all('base').

// Весь раздел для явно выбранного сайта s1.
$values = Settings::base(null, 's1');
// То же, что Settings::all('base', 's1').

// Отдельное значение с резервным значением для отсутствующей настройки.
$title = Settings::base('buttonTitle', 's1', '');
// То же, что Settings::get('base', 'buttonTitle', 's1', '').

Эти вызовы также требуют подключения модуля. Используйте позиционные аргументы: ключ, сайт, резервное значение. Для чтения всего раздела на конкретном сайте первым аргументом передайте null, вторым — код сайта. Подробнее — в справочнике API.

Выбор сайта

Передавайте идентификатор явно. Без него используется сайт по умолчанию Битрикса, а не обязательно текущий сайт страницы. Для шаблона нескольких сайтов можно передать корректный код текущего сайта, определённый вашим приложением; в примерах фиксирован s1 для воспроизводимости.

Безопасный вывод

if (Loader::includeModule('kokhanenko.settings')) {
    echo htmlspecialcharsbx(Settings::get('base', 'buttonTitle', 's1', ''));
}

htmlspecialcharsbx() подходит для обычного текстового HTML-вывода. Для JavaScript применяйте JSON-сериализацию, для URL — проверку допустимого адреса и контекстное экранирование. Не вставляйте значения напрямую в HTML, атрибуты или JavaScript. Текст в textarea не становится доверенным HTML автоматически.

Практические рецепты показывают телефон, кнопку, подписи списка, дату и два сайта с точными предварительными условиями.

Запись из PHP: границы SettingsService

Обычно настройки создают и меняют в административной панели. Для скрипта импорта или другой интеграции можно использовать Kokhanenko\Settings\Service\SettingsService. В этой статье описаны его методы для версии 2.0.0; это отдельный сервис, а не часть класса чтения Settings.

Создание с начальным значением

Предварительные условия: существует сайт s1 и видимый раздел contacts; настройки contacts.phone ещё нет.

use Bitrix\Main\Loader;
use Kokhanenko\Settings\Service\SettingsService;

if (!Loader::includeModule('kokhanenko.settings')) {
    throw new \RuntimeException('kokhanenko.settings');
}

$service = new SettingsService();
$result = $service->create([
    'siteId' => 's1',
    'sectionCode' => 'contacts',
    'key' => 'phone',
    'dataType' => 'string',
    'multiple' => false,
    'editor' => 'input',
    'groupId' => 'Контактные данные',
    'description' => 'Телефон',
    'hint' => 'Номер для страницы контактов',
    'sort' => 100,
], '+7 (000) 000-00-00');

if (!$result->isSuccess()) {
    throw new \RuntimeException(implode('; ', $result->getErrorMessages()));
}

$id = (int)$result->getData()['ID'];

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

Изменение параметров и значений

$id — ID только что созданной настройки; для существующей получите запись через getForAdminByAddress() и проверьте, что она найдена.

$result = $service->updateDefinition($id, [
    'hint' => 'Демонстрационный номер; замените перед публикацией',
    'sort' => 200,
]);
if (!$result->isSuccess()) {
    throw new \RuntimeException(implode('; ', $result->getErrorMessages()));
}

$result = $service->saveValues('contacts', 's1', [
    'phone' => '+7 (000) 111-11-11',
]);
if (!$result->isSuccess()) {
    throw new \RuntimeException(implode('; ', $result->getErrorMessages()));
}

// При успехе saveValues():
// $result->getData() === ['count' => 1, 'keys' => ['phone']]

create() и updateDefinition() возвращают Bitrix\Main\Result; при успехе в данных есть ID. Перед использованием результата всегда проверяйте isSuccess(). Если операция не выполнена, получите сообщения через getErrorMessages().

Важные ограничения

• updateDefinition() не допускает изменение siteId, sectionCode, key, dataType, multiple и не записывает новое значение.
• Для enum передавайте dataOptions в форме ['items' => [['value' => 'support', 'label' => 'Поддержка']]]. Редактор — select, multiple — bool.
• Сервис принимает строгие значения: bool, строки, null и массивы согласно контракту типов, а не произвольный ввод HTML-формы.
• При смене вариантов списка проверяется уже сохранённое значение. Сначала перенесите выбор на допустимый код.
• saveValues() предварительно проверяет весь переданный набор и сохраняет его транзакционно. Ошибка одного поля не должна приводить к частичному сохранению набора. Непереданные ключи не меняются.
• delete($id) удаляет одну настройку и возвращает Result. Родитель с дочерними настройками защищён от удаления.
• Не меняйте таблицы прямыми SQL-запросами в обход проверки и инвалидирования кеша.

Методы совместимости со старой моделью, например add() и updateById(), обрабатывают данные иначе. Для новых интеграций используйте показанные выше create(), updateDefinition() и saveValues().

Переход со старого API

В 2.0.0 SiteSettings удалён. Перенос данных не переписывает ваши шаблоны. Таблица замен, изменения типов и контрольный список — в инструкции обновления.