rulybka/bitrix-migrations

Database migrations for Bitrix CMS

2.8.4 2023-01-27 08:28 UTC

Requires

• php: >=5.5.0
• symfony/console: ~2|~3|~4
• tightenco/collect: 5.*

Requires (Dev)

• mockery/mockery: ~0.9
• phpunit/phpunit: ~4.0

MIT

• migrations
• bitrix

README

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

Установка

1. composer require rulybka/bitrix-migrations

2. cp vendor/rulybka/bitrix-migrations/migrator migrator - копируем исполняемый файл в удобное место.

3. заходим внутрь и удостоверяемся что задается правильный $_SERVER['DOCUMENT_ROOT']. Меняем настройки если нужно.

4. php migrator install

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

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

1. Таблица называется migrations.

2. composer.json и migrator лежат в корне сайта.

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

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

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

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

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

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

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

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

1. Реализуем в методе up()необходимые изменения в БД. При желании в методе down() реализуем откат этих изменений

2. Применяем имеющиеся миграции - php migrator migrate

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

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

Список доступных команд можно получить в консоли - 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`	Создание группы пользователей

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

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

Для его включения необходимо добавить примерно следующее в init.php

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

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

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

1. Срабатывает битриксовый обработчик события

2. Создается файл миграции как при php migrator make

3. Миграция помечается примененной

4. Показывается нотификация о предыдущих пунктах

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

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

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

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

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

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