Форк для поддержки пакетов symfony 5.* и phpUnit 9.
Миграции БД для Битрикса и не только
-
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;и использовать его. -
По желанию отключить существующие шаблоны миграций, сделав свои.
1. docker build --no-cache --file ./Dockerfile --tag arrilot-bitrix-migrations .
2. docker run --rm -v `pwd`:/app arrilot-bitrix-migrations composer install
3. docker run --rm -v `pwd`:/app arrilot-bitrix-migrations ./vendor/bin/phpunit tests