README

Библиотека миграций для ваших Битрикс-проектов.

Преимущества:

использует в качестве основы проверенную временем и хорошо оттестированную 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-классу;
bitrix-migrations:generate-perfmon - генерирует миграцию, которая будет содержать addSql-запросы взятые из монитора производительности;
bitrix-migrations:generate-template-migration - генерирует миграцию по шаблону, см. "Шаблоны" ниже.

Может добавить все команды в проект со стандартными настройками так:

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

Шаблоны

Шаблоны основаны на библиотекеmaximaster/attributemplate, что позволяет создавать шаблоны на базе PHP-классов с помощью атрибутов. Данный подход хорош тем, что данные шаблоны можно проверять с статического анализа, в отличии от штатных шаблонов doctrine/migration.

Все шаблоны которые предоставляет библиотека находятся в директории src/Templates, таким образом, чтобы ими воспользоваться, нужно будет вызывать консольную команду следующим образом:

console bitrix-migrations:generate-template-migration vendor/maximaster/bitrix-migrations/src/Templates/AddIblockMigrationTemplate.php

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

Для упрощения, рекомендуется в проекте создать директорию templates и внутри неё хранить собственные шаблоными миграций, а так же симлинк default на директорию ./vendor/maximaster/bitrix-migrations/src/Templates. Таким образом получится сохранить вызов до:

console bitrix-migrations:generate-template-migration templates/default/AddIblockMigrationTemplate.php

При этом возможность автодополнения средствами командной строки сохраняется.

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

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

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

Разработка

перед отправкой выполняйте composer qa

maximaster / bitrix-migrations

Maintainers

Details