README

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

Установка

composer require rulybka/bitrix-migrations
cp vendor/rulybka/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`
`element_add`	Добавление элемента в раздел инфоблока
`section_add`	Добавление раздела в инфоблок инфоблока
`hlb_element_add`	Добавление элемента в сущность хайлоада
`event_add`	Добавление почтового события
`event_msg_add`	Добавление шаблона почтового события
`group_add`	Создание группы пользователей

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('Тут текст ошибки'); Ни сама миграция, ни последующие при этом применены не будут.

rulybka / bitrix-migrations

Maintainers

Details