Download the PHP package mb4it/bitrix-migration without Composer

mb4it/bitrix-migration

Версионируемые миграции для 1С-Битрикс в стиле Laravel: класс миграции с up()/down(), таблица-леджер применённых версий, батчи, откат, статус. Плюс fluent-билдеры и экспортёры сущностей Битрикса (инфоблоки, HL-блоки, агенты, почта, опции, пользователи/группы, sitemap) для генерации миграций из живой БД. Namespace — MB\Bitrix\Database\Migrations\.

Самодостаточный пакет: зависит от ядра 1С-Битрикс и от mb4it/bitrix-console (движок + свои console-команды), но НЕ от mb4it/bitrix-support. Леджер MigrationVersionTable extends \Bitrix\Main\ORM\Data\DataManager; DI-обвязка (биндинги Migrator и пр.) и CLI-команды регистрируются через провайдер пакета, который консоль подхватывает автоматически (discovery по extra.mb-console.providers).

Требования

• PHP ^8.2
• 1С-Битрикс (модуль main; отдельные экспортёры грузят iblock/highloadblock/seo)
• Для запуска из консоли — mb4it/bitrix-console (команды migrate*, make:migration*)

Установка

Пакет — path-репозиторий в composer.json потребителя (модуля/проекта):

Подключение — автоматическое: пакет объявляет свой console-провайдер в composer.json → extra.mb-console.providers, а mb4it/bitrix-console подхватывает его через Console\PackageManifest (читает vendor/composer/installed.json). Никакой ручной регистрации не нужно. mb4it/bitrix-support не требуется.

Быстрый старт

Сам движок — библиотека; CLI-команды даёт mb4it/bitrix-console. Обычно ставят консоль (миграции придут транзитивно) — и всё работает сразу, без настройки:

Появится самодостаточный бинарь vendor/bin/bx (далее — просто bx):

Нужно только программное использование, без CLI? Ставьте один движок:

и вызывайте app(\MB\Bitrix\Database\Migrations\Migrator::class) (см. «Программное использование»).

Что внутри

Три таблицы (создаёт migrate:install, а также ленивое авто-создание):

• mb_migration_version — леджер: ID, MIGRATION (для модуля <id>:<файл>), BATCH, APPLIED_AT.
• mb_migration_created — сущности, созданные миграцией (чтобы откат удалял только их).
• mb_migration_snapshot — снимок прежних значений обновлённых сущностей (чтобы откат восстанавливал поля, а не удалял сущность).

Как написать миграцию

Файл миграции — обычный PHP-файл, который возвращает анонимный экземпляр Migration. Имя файла timestamped: 2026_07_07_120000_create_orders_table.php.

Внутри up()/down() доступны:

• $this->connection() → Bitrix\Main\DB\Connection;
• $this->statement(string $sql) → выполнить SQL;
• весь D7 ORM; а при установленном mb4it/bitrix-support — глобальные хелперы app(), config(), module().

down() можно оставить пустым — тогда миграция необратима (rollback просто удалит запись из леджера).

Схему таблиц ORM-сущностей (Storage\Base) удобно накатывать прямо из миграции: MyEntityTable::migrate(\Bitrix\Main\Application::getConnection()).

Где лежат файлы

• Проектные — local/migrations/ (путь по умолчанию из PathRegistry).
• Модульные — <module>/migrations/ (напр. local/modules/my.module/migrations/).

Модульные миграции изолированы в леджере через scope: имя хранится как <moduleId>:<файл>, поэтому проектные и модульные миграции не смешиваются и откатываются независимо. Пустой scope — проект.

Запуск (через mb4it/bitrix-console)

Любая команда принимает --format=json для машиночитаемого вывода (ИИ-агент).

migrate:install создаёт все три служебные таблицы (mb_migration_version, mb_migration_created, mb_migration_snapshot) — идемпотентно; они также создаются лениво при первом обращении.

Генерация миграций из живых сущностей

Экспортёры читают существующую сущность Битрикса и пишут файл миграции (up() воссоздаёт, down() откатывает). Команды и их опции — в README пакета mb4it/bitrix-console: make:migration:options, :iblock, :iblock-elements, :hlblock, :hlblock-elements, :agents, :mail, :user-groups, :users, :sitemap.

Выборочный экспорт инфоблока: --properties=CODE,… / --no-properties, --sections=ID|CODE|XML_ID,… / --no-sections, --with-elements.

Те же билдеры доступны и для ручного написания: \MB\Bitrix\Database\Migrations\Builders\OptionBuilder::make('main','x')->value('1')->apply();.

Переносимость между сайтами

Билдеры резолвят сущность по символьному ключу (CODE / XML_ID); записанный первичный ID используется лишь как фолбэк для сущностей без ключа. Поэтому миграция, перенесённая на другой сайт (где тот же ID занят несвязанной сущностью), не перезапишет чужую запись: она найдёт цель по ключу либо создаст новую.

Не-разрушающий откат и восстановление полей

down() не удаляет вслепую. Для каждой затронутой сущности:

• создана этой миграцией → удалить;
• существовала и лишь обновлена → восстановить прежние значения полей из снимка (mb_migration_snapshot), не удаляя сущность;
• иначе → не трогать.

Покрыты: инфоблоки (поля + привязка к сайтам), свойства (поля + список значений enum + LINK_IBLOCK), разделы, элементы (поля + значения свойств). Вне контекста миграции (ручной вызов билдера) remove() работает как раньше — удаляет.

Перенос файлов

Картинки элементов (PREVIEW_PICTURE / DETAIL_PICTURE) и файловые свойства (тип F, одиночные и множественные) переносятся как самодостаточные файлы: MigrationWriter выносит их в sidecar-папку files/<миграция>/, а в .php остаётся ссылка PATH. При apply() файл заливается заново (новый b_file), при откате — восстанавливается из снимка. Списочные значения переносятся по enum-id; пустые — очищают свойство.

Важно: миграция теперь — это .php плюс папка files/<миграция>/. Переносите и коммитьте их вместе. Экспорт файла возможен только там, где физический файл существует; иначе файл просто пропускается.

Программное использование

Migrator разрешается из контейнера. При наличии mb4it/bitrix-support доступен глобальный хелпер app(); в standalone-режиме резолвьте через контейнер консоли или соберите объект напрямую.

API Migrator

Биндинги контейнера

Кастомный путь по умолчанию

PathRegistry по умолчанию засеян local/migrations. Чтобы добавить свои каталоги (например, для авто-подхвата), переопределите singleton в своём ServiceProvider: