arrilot / bitrix-migrations
Database migrations for Bitrix CMS
Installs: 62 956
Dependents: 4
Suggesters: 0
Security: 0
Stars: 123
Watchers: 19
Forks: 56
Open Issues: 5
Requires
- php: >=5.5.0
- symfony/console: ~2|~3|~4
- tightenco/collect: 5.*
Requires (Dev)
- mockery/mockery: ~0.9
- phpunit/phpunit: ~4.0
README
Данный пакет больше активно не поддерживается
Причина - мы больше не используем Битрикс в своих проектах. Если вам интересен этот проект и вы хотите заняться его поддержкой - форкните его и создайте Issue в данном репозитории чтобы мы поместили здесь ссылку на форк.
Форки:
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;
и использовать его. -
По желанию отключить существующие шаблоны миграций, сделав свои.