Обновление с 1.1.3 на 2.0.0

Эта инструкция описывает переход с 1.1.3 на 2.0.0. Для более ранней версии сначала проверьте последовательность доступных обновлений в штатном клиенте Битрикса.

warning

В 2.0.0 удалён класс SiteSettings и изменились типы возвращаемых значений. До обновления рабочего сайта подготовьте изменения PHP-кода и проверьте их вместе с новым модулем на тестовой копии. Обновление БД не исправляет шаблоны автоматически.

Перед обновлением

Найдите обращения к SiteSettings в шаблонах и собственных скриптах. Подготовьте замену по таблице ниже.
Создайте тестовую копию сайта с его файлами и БД. Выполните на ней пробное обновление и проверьте подготовленный код с модулем 2.0.0.
Запланируйте время обновления рабочего сайта, когда допустим краткий перерыв в его работе.
Сделайте резервную копию файлов и БД, относящихся к одному состоянию сайта. Убедитесь, что можете её восстановить.
На рабочем сайте установите обновление и внесите проверенные изменения шаблонов в рамках одного окна обслуживания. Не оставляйте старые вызовы работающими с новым модулем или новый код — со старым.

Перенос данных

Установите пакет через штатный клиент обновлений Битрикса. Не запускайте updater.php отдельно: он предназначен для выполнения в контексте клиента обновлений.

До первой записи выполняется проверка исходных настроек. Сохраняются ID, сайты, разделы, ключи, описания, подсказки и родительские связи. Значения переводятся в типизированный формат. После переноса выполняется сверка.

Прерванное обновление допускает повтор. Состояния schema_extended, data_written, verified, completed позволяют продолжить работу, а контрольная сумма исходных данных блокирует продолжение при изменении источника.

Замена вызовов в шаблонах

В примерах классы импортированы через use Kokhanenko\Settings\SiteSettings (старый код) или use Kokhanenko\Settings\Settings (новый код).

Вызов 1.1.3	Вызов 2.0.0
`SiteSettings::get('base', 'buttonTitle', 's1', '')`	`Settings::get('base', 'buttonTitle', 's1', '')`
`SiteSettings::base('buttonTitle', 's1', '')`	`Settings::base('buttonTitle', 's1', '')`
`SiteSettings::all('contacts', 's1')`	`Settings::all('contacts', 's1')`
`SiteSettings::contacts(null, 's1')`	`Settings::contacts(null, 's1')`
`SiteSettings::get('base', 'useButton', 's1') === '1'`	`Settings::get('base', 'useButton', 's1', false)`
`SiteSettings::clearCache()`	`Settings::clearCache()`

Одной замены имени класса недостаточно. Проверьте обработку результатов:

логический тип возвращает bool, не строку '1' / '0';
одиночный enum — строковый код или null, множественный — массив строковых кодов;
пустые значения false, '', null, [] не заменяются аргументом $default;
дата имеет формат YYYY-MM-DD, время — HH:MM;
для подписей списка используйте selectedOptions(), не считайте код подписью.

Полный контракт — в модели настроек.

Где проверить служебные маркеры

Разработчик может прочитать опции через API Битрикса в контролируемом диагностическом скрипте после подключения ядра:

PHP

use Bitrix\Main\Config\Option;

$moduleId = 'kokhanenko.settings';
$storageVersion = Option::get($moduleId, 'storage_version', '');
$done = Option::get($moduleId, 'migration_2_0_0_done', '');
$state = Option::get($moduleId, 'migration_2_0_0_state', '');
$digest = Option::get($moduleId, 'migration_2_0_0_source_digest', '');

После успешного обновления 1.1.3 ожидаются storage_version=2.0.0, migration_2_0_0_done=Y, migration_2_0_0_state=completed. Контрольная сумма — служебный маркер проверки источника; не правьте её вручную.

note

Эти маркеры проверяются после обновления с 1.1.3. При чистой установке перенос старых данных не выполняется: migration_2_0_0_done=N, а состояние completed и контрольная сумма миграции могут отсутствовать.

Контрольный список результата

Версия файлов модуля — 2.0.0; служебные маркеры соответствуют именно выполненному сценарию.
На каждом используемом сайте видны ожидаемые разделы, группы и ключи; выбор сайта не смешивает данные.
Логические значения, текст, списки, даты и время читаются с новыми типами.
Подписи вариантов и родительские зависимости сохранились.
Обратимое тестовое изменение сохраняется, читается через Settings и затем возвращается к исходному значению.
Поиск по коду проекта не находит действующих обращений к SiteSettings и сравнений логического значения с legacy-строкой.
Публичные страницы работают, включая выключенные переключатели и пустые значения.
Кеши модуля и HTML-кеши проекта проверены отдельно; резервная копия сохранена до завершения приёмки.

Старый файл lib/SiteSettings.php удаляется после успешной миграции. Вызовы в ваших шаблонах автоматически не переписываются.

Откат

warning

После изменения схемы для отката нужно восстановить и файлы 1.1.3, и БД из той же резервной копии. Возврат только старых PHP-файлов оставит их работать с несовместимой схемой.

Если вы отдельно изменяли шаблоны, восстановите и их предыдущую версию. После восстановления очистите кеши и проверьте публичные страницы.

Не удаляйте неожиданный bd/database.sqlite без проверки и резервной копии.