Bitrix-migrations

Миграции БД для Битрикса и не только

Установка

composer require arrilot/bitrix-migrations
cp vendor/arrilot/bitrix-migrations/migrator migrator - копируем исполняемый файл в удобное место.
заходим внутрь и удостоверяемся что задается правильный $_SERVER['DOCUMENT_ROOT']. Меняем настройки если нужно
php migrator install

Данная команда создаст в БД таблицу для хранения названий выполненных миграций.

По умолчанию:

Таблица называется migrations.
composer.json и migrator лежат в корне сайта.
Файлы миграций будут создаваться в директории ./migrations относительно скопированного на этапе 2 файла.

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

Крайне рекомендуется сделать migrator и ./migrations недоступными по http через веб-сервер. *

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

Рабочий процесс

Рабочий процесс происходит через консоль и кратко описывается примерно так:

Создаем файл (или файлы) миграции при помощи php migrator make название_миграции

Файл миграции представляет из себя класс с двумя методами up() и down()

Реализуем в методе up()необходимые изменения в БД. При желании в методе down() реализуем откат этих измнений
Применяем имеющиеся миграции - php migrator migrate
Вносим файлы миграций в систему контроля версий, чтобы их можно было запустить и на других машинах

Доступные команды

Список доступных команд можно получить в консоли - php migrator list

Название	Описание
`php migrator install`	Создает таблицу для хранения миграций. Запускается один раз.
`php migrator make название_миграции`	Создает файл миграции Опции: `-d foo/bar` - указать поддиректорию, в которой будет создана миграция
`php migrator migrate`	Применяет все доступные для применения миграции. Миграции примененные ранее не применяются.
`php migrator rollback`	Откатывает последнюю миграцию (метод `down()`). После этого её можно применить повторно. Опции: `--hard` - выполнить жесткий откат без вызова метода `down()` `--delete` - удалить файл с миграцией после отката.
`php migrator templates`	Показывает подробную таблицу со всем существующими шаблонами миграций
`php migrator status`	Показывает доступные для выполнения миграции, а также последние выполненные.
`php migrator archive`	Переносит все миграции в архив. По умолчанию это директория archive, но можно переопределить в конфиге, указав "dir_archive" Опции: `-w 10` - не переносить в архив последние N миграций

Шаблоны миграций

Так как изменение структуры БД битрикса через его АПИ - занятие крайне малоприятное, то для облегчения этого процесса есть механизм шаблонов миграций, работающий следущим образом: При генерации файла миграции можно указать его шаблон: php migrator make название_миграции -t add_iblock где add_block - название шаблона. При этом сгенерируется класс с бойлерплейтом из шаблона и остается лишь указать детали (например название и код инфоблока) Свои шаблоны миграций можно добавить напрямую в файле migrator при помощи TemplateCollection::registerTemplate()

Имеющиеся шаблоны:

Название	Описание	Алиасы
`default`	Чистый шаблон по умолчанию
`add_iblock_type`	Добавление типа инфоблока
`add_iblock`	Добавление инфоблока
`add_iblock_element_property`	Добавление свойства в инфоблок	`add_iblock_prop`, `add_iblock_element_prop`, `add_element_prop`, `add_element_property`
`add_uf`	Добавление UF свойства
`query`	Произвольный запрос в БД через АПИ d7
`add_table`	Создание таблицы через АПИ d7	`create_table`
`delete_table`	Удаление таблицы через АПИ d7	`drop_table`

php migrator status - показывает доступные для выполнения миграции, а также последние выполненные.

Автоматическое создание миграций

Еще одна киллер-фича - режим автоматического создания миграций. Для его включения необходимо добавить примерно следующее в init.php

Arrilot\BitrixMigrations\Autocreate\Manager::init($_SERVER["DOCUMENT_ROOT"].'/migrations');

В метод Manager::init() передается путь до директории аналогичной конфигу в файле migrator.

После этого при выполнении ряда действий в админке будет происходить следующее

Срабатывает битриксовый обработчик события
Создается файл миграции как при php migrator make
Миграция помечается примененной
Показывается нотификация о предыдущих пунктах

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

Список обрабатываемых событий:

Событие	Комментарии
Добавление инфоблока
Обновление базовых полей инфоблока	Из-за специфики работы админки битрикса эта миграция зачастую создается когда не нужно, допустим при добавлении кастомного свойства в инфоблок. Ничего смертельного, но надо смириться.
Удаление инфоблока
Добавление кастомного свойства в инфоблок
Обновление кастомного свойства инфоблока	Миграция создается только если какой-либо из атрибутов свойства был изменён
Удаление кастомного свойства инфоблока
Добавление UF свойства куда-либо (раздел ИБ, пользователь, хайлоадблок)	К сожалению Битрикс не даёт возможности отслеживать изменение такого свойства - только добавление и удаление
Удаление UF свойства
Добавление хайлоадблока
Изменение хайлоадблока	Миграция создается только если какой-либо из атрибутов хайлоадблока был изменён
Удаление хайлоадблока
Добавление группы пользователей
Изменение группы пользователей
Удаление группы пользователей

Миграции используют события OnBefore.... Если при вашем изменении произошла ошибка (допустим не указана привязка к сайту при добавлении инфоблока) и было показано уведомление о том что миграция создана, необходимо вручную откатить такую миграцию при помощи php migrator rollback --hard --delete *

Обработка ошибок миграций

Для отмены миграции в момент её выполнения достаточно выкинуть исключение - php throw new MigrationException('Тут текст ошибки'); Ни сама миграция, ни последующие при этом применены не будут.

Использование вне Битрикс

Пакет создан для использования совместно с Битриксом, однако его довольно просто можно использовать и в других системах. Для этого нужно в файле migrator:

Заменить подключение ядра Битрикса на ядро другой системы.
Реализовать свой аналог Arrilot\BitrixMigrations\Repositories\BitrixDatabaseRepository; и использовать его.
По желанию отключить существующие шаблоны миграций, сделав свои.

broadcastaddress / bitrix-migrations