Установка и обновление модуля (install)

Установщик — это лицо модуля: он создаёт таблицы, регистрирует события и агентов, копирует компоненты и админ-страницы, а при удалении чисто всё убирает. Грамотно написанные DoInstall/DoUninstall и механизм обновлений updater делают модуль воспроизводимым и безопасным при выкатке на прод.

Жизненный цикл установки

Когда администратор нажимает «Установить» в Marketplace → Установленные решения, Битрикс создаёт объект класса-установщика из install/index.php и вызывает его DoInstall(). Обратный процесс — DoUninstall().

• DoInstall — регистрирует модуль, создаёт таблицы, события, агентов, копирует файлы;
• DoUninstall — снимает всё в обратном порядке и удаляет запись модуля;
• оба метода могут показывать шаги мастера — HTML-формы для выбора параметров установки.

Метод DoInstall

Типовой DoInstall разбивают на приватные шаги — так код читается и переиспользуется в обновлениях.

public function DoInstall() {
  global $APPLICATION;
  \Bitrix\Main\ModuleManager::registerModule($this->MODULE_ID);
  $this->InstallDB();
  $this->InstallEvents();
  $this->InstallFiles();
  $APPLICATION->IncludeAdminFile(
    'Установка модуля ' . $this->MODULE_NAME,
    __DIR__ . '/step.php'
  );
}

IncludeAdminFile() подключает файл шага в оформлении админки — там показывают сообщение об успехе или форму. Порядок важен: сначала регистрация модуля, затем БД и события, иначе registerEventHandler() может отработать до появления записи модуля.

Создание и удаление таблиц

Схему БД разворачивают либо SQL-файлами, либо через ORM. SQL-подход:

public function InstallDB() {
  global $DB;
  $this->errors = $DB->RunSQLBatch(__DIR__ . '/db/install.sql');
  return empty($this->errors);
}

ORM-подход надёжнее для кроссплатформенности:

\Bitrix\Main\Loader::includeModule($this->MODULE_ID);
\B2bsite\Exchange\ProfileTable::getEntity()->createDbTable();

События, агенты и права

Всё, что модуль «вешает» на систему, регистрируется в установке и снимается в удалении симметрично.

Агенты удобно чистить пачкой: CAgent::RemoveModuleAgents($this->MODULE_ID) снимет все агенты, привязанные к идентификатору модуля, за один вызов.

Копирование компонентов и файлов

Компоненты, админ-страницы и публичные файлы поставляются внутри модуля (в install/components, install/admin) и копируются в рабочие каталоги при установке.

CopyDirFiles(
  __DIR__ . '/components',
  $_SERVER['DOCUMENT_ROOT'] . '/local/components',
  true, true
);

В DoUninstall те же файлы удаляют через DeleteDirFiles(). Держите оригиналы в модуле, а в рабочие каталоги только копируйте — тогда обновление перезальёт актуальные версии, не задев кастомизации в других местах.

Механизм обновлений

После установки модуль обновляется не переустановкой, а патчами через систему обновлений. При повышении VERSION в install/version.php Битрикс подтягивает скрипты обновления и применяет их.

• каждый апдейт-скрипт получает объект $updater (CUpdater) с методами CopyFiles(), Rollback() и данными о версиях;
• изменения схемы БД делают безопасными: ALTER TABLE ... ADD COLUMN с проверкой существования колонки;
• версия и дата в version.php — источник истины для сравнения.

if ($updater->CanUpdateKernel()) {
  $updater->CopyFiles('install/components', 'components');
}

Проверка и отладка установки

Перед выкаткой прогоните полный цикл на тестовом контуре:

1. установка «с нуля» — все таблицы, события и агенты на месте;
2. удаление — ничего не осталось в b_module_to_module, b_agent, БД (если выбрано удаление данных);
3. повторная установка — не падает на существующих объектах;
4. обновление с предыдущей версии — миграции применяются, данные целы.

Ошибки установки копятся в свойстве $this->errors и выводятся мастером. Логируйте критичные шаги, чтобы при проблеме на проде было видно, где именно установщик остановился.

Итог

Установщик модуля строится вокруг симметричных DoInstall/DoUninstall: регистрация модуля, создание/удаление таблиц, события через registerEventHandler, агенты через CAgent, копирование компонентов через CopyDirFiles. Обновления идут не переустановкой, а патчами updater с ростом VERSION. Ключевые правила — идемпотентность, бережное отношение к данным и полный прогон цикла на тесте.

Когда модуль обслуживает боевой обмен с 1С или интеграцию под нагрузкой, цена ошибки установки высока. Мы в B2Bsite проектируем установщики и миграции так, чтобы выкатка проходила без простоя и потери данных, а откат был предсказуемым.