README

Упрощает подключение на Битрикс-проект миграций через doctrine/migrations и содежит собственный базовый класс для миграций с рядом полезных методов под Битрикс.

Кроме этого, работа с миграциями ведётся так же как при базовом использовании doctrine/migrations.

Установка и первичная настройка

composer require maximaster/bitrix-migrations

Далее установите стандартные конфиги требуемые doctrine/migrations:

./vendor/bin/bitrix-migrations init

Использование

Основная польза библиотеки раскрывается, когда вы используете её специфичные для Битрикса методы. Ярким примером служит метод addCreateIblockTableSql:

$this->addCreateIblockTableSql('b_iblock_element_prop_s?', sprintf('XML_ID = "%s"', self::ID), '(
    IBLOCK_ELEMENT_ID INT(11) not null REFERENCES b_iblock_element(ID),
    PRIMARY KEY (IBLOCK_ELEMENT_ID)
)');

Здесь имя таблицы будет зависеть от ID инфоблока с нужным XML_ID.

Внутри используются Prepared Statements писать которые каждый раз было бы крайне громоздко.

Для эффективной работы с библиотекой рекомендуется сразу изучить защищённые методы класса BitrixMigration.

Отдельно стоит отметить метод addGeneratedSql, который позволяет генерировать запросы использующие подстановки данных "по месту", чтобы понять как данный метод работает, посмотрите как он используется в других методах BitrixMigration. Реализация была вдохновлена Thesis, который на момент обновления данного README, так и не был опубликован.

Обратная совместимость

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

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

Дополнительные функции

Если пользуетесь symfony/console, то можете подключить в своё консольное приложение доп. команды данного пакета (пока есть только одна):

bitrix-migrations:generate-table - генерирует миграцию, которая создаёт таблицу в базе данных по DataManager-классу.

$bitrixLoader = \Maximaster\BitrixLoader\BitrixLoader::fromComposerConfigExtra(__DIR__ . '/../composer.json');
$bitrixMigrationsCommandsFactory = require __DIR__ . '/../vendor/maximaster/bitrix-migrations/config/commands.php';
$app->addCommands($bitrixMigrationsCommandsFactory($bitrixLoader));

Альтернативы

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

если данный проект не использует в качестве основы какую-то популярную библиотеку миграций вроде doctrine/migrations, то манипуляции с миграциями будут ограничены, а качество ниже, ведь как правило подобные решения не покрыты тестами и стат. анализом;
если данный проект пропогандирует использование Битрикс API в миграциях, будьте готовы, что в один не очень прекрасный день, ранее отлично работавшая миграция создающая, скажем, инфоблок сломается, например, по той причине, что вы добавили в проект некий обработчик на создание инфоблока, который теперь начнёт выполняться в миграциях запускаемых на свежих установках и результат работы миграций изменится. Даже если эту проблему можно решить, вам очень не захочется постоянно решать проблемы с миграциями которые были написаны давно. И не все проблемы можно будет решить, ведь они могут прийти из ядра Битрикс (допустим после обновления ядра);
если данный проект заявляет, что вы можете автоматически генерировать миграции в ходе действий в админке, то обратите внимание на получившиеся миграции. Если в них упоминаются фиксированные ID, то подумайте, что с этими миграциями случится на продуктиве, когда окажется, что данный ID уже занят из-за того что между тем как вы делали копию БД и накатываете это обновление прошло время и какой-то менеджет в админке создан какой-то объект, который начал занимать этот ID.

maximaster / bitrix-migrations

Maintainers

Details