arrilot/bitrix-migrations

Database migrations for Bitrix CMS

, _(*1)

Данный пакет больше активно не поддерживается

Причина - мы больше не используем Битрикс в своих проектах. Если вам интересен этот проект и вы хотите заняться его поддержкой - форкните его и создайте Issue в данном репозитории чтобы мы поместили здесь ссылку на форк., _(*2)

Форки: - https://github.com/informunity/bitrix-migrations, _(*3)

Bitrix-migrations

Миграции БД для Битрикса и не только, _(*4)

Установка

1) composer require arrilot/bitrix-migrations, _(*5)

2) cp vendor/arrilot/bitrix-migrations/migrator migrator - копируем исполняемый файл в удобное место., _(*6)

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

4) php migrator install, _(*8)

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

По умолчанию:, _(*10)

1) Таблица называется migrations., _(*11)

2) composer.json и migrator лежат в корне сайта., _(*12)

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

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

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

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

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

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

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

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

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

3) Применяем имеющиеся миграции - php migrator migrate, _(*19)

4) Вносим файлы миграций в систему контроля версий, чтобы их можно было запустить и на других машинах, _(*20)

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

Список доступных команд можно получить в консоли - php migrator list, _(*21)

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

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

Имеющиеся шаблоны:, _(*23)

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

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

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

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

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

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

1) Срабатывает битриксовый обработчик события, _(*28)

2) Создается файл миграции как при php migrator make, _(*29)

3) Миграция помечается примененной, _(*30)

4) Показывается нотификация о предыдущих пунктах, _(*31)

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

Список обрабатываемых событий:, _(*33)

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

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

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

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

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

1) Заменить подключение ядра Битрикса на ядро другой системы., _(*36)

2) Реализовать свой аналог Arrilot\BitrixMigrations\Repositories\BitrixDatabaseRepository; и использовать его., _(*37)

3) По желанию отключить существующие шаблоны миграций, сделав свои., _(*38)