cjp2600/bim-core

Bitrix db migration core libs

Bitrix Migration (BIM)

, _(*1)

Версионная миграция структуры БД для 1С Битрикс CMS, _(*2)

• Установка
  • Автоматическая установка
  • Ручная установка
• Настройка
• Выполнение - bim up
• Отмена - bim down
• Вывод списка - bim ls
• Создание - bim gen
  • Создание пустой миграции
  • Создание миграционного кода по наличию
  • Модуль (iblock,highloadblock)
  • IblockType
  • Iblock
  • IblockProperty
  • Highloadblock
  • HighloadblockField
  • Модуль (main)
  • Group
  • Site
  • Режим multi - bim gen multi
  • Тегирование миграций
  • Логирование
• Информация о проекте - bim info

1 Установка

1.1 Автоматическая установка

Для установки и инициализации bim для bitrix проекта необходимо выполнить следующиие действия из корня проекта:, _(*3)

• Установить Composer:

curl -s https://getcomposer.org/installer | php

• Выполнить установочный скрипт:

``` bash php -r "readfile('https://raw.githubusercontent.com/cjp2600/bim/master/install');" | php, <sub>(*4)</sub>

> Автоматические действия установщика:

> 1. Добавление файла bim в корень проекта.
> 2. Инициализация **composer autoloader** в файле **init.php**
> 3. Создание файла **composer.json** в корне проекта со ссылкой на bim репозиторий **"require": { "cjp2600/bim-core": ">=1.0.0"}**

### <a name="hand"></a>1.2 Ручная установка 

Для ручной установки bim необходимо:

- Установить Composer:

curl -s https://getcomposer.org/installer | php, <sub>(*5)</sub>

- Добавть инициализацию composer (в файл init.php добавить запись):

```bash
if (file_exists($_SERVER['DOCUMENT_ROOT'] . '/vendor/autoload.php'))
    require_once $_SERVER['DOCUMENT_ROOT'] . '/vendor/autoload.php';

• Создать в корне сайта файл composer.json с содержимым:

{
    "require": {
        "cjp2600/bim-core": ">=1.0.0"
    }
}

• В .gitignore добавить запись:

/vendor

• Done! :):

``` php php vendor/bin/bim info, <sub>(*6)</sub>

# 2 <a name="prop"></a>Настройка

Для начала работы обновляем **composer** и создаем миграционную таблицу в БД:

``` bash
php composer.phar update

Создаём таблицу миграций :, <sub>(*7)</sub>

php bim init

3 Выполнение миграций [BIM UP]

• Общее выполнение:

php bim up

Выполняет полный список не выполненых либо ранее отмененных миграционных классов отсортированых по названию (timestamp)., <sub>(*8)</sub>

• Еденичное выполнение:

php bim up 1423660766

Выполняет указанную в праметрах миграцию., <sub>(*9)</sub>

• Выполнение по временному периоду:

php bim up --from="29.01.2015 00:01" --to="29.01.2015 23:55"

• Выполнение по тегу:

php bim up --tag=iws-123

Выполняет все миграции где найден указанный тег в описании., <sub>(*10)</sub>

• Логирование: ``` bash php bim up --logging

# 4 <a name="down"></a>Отмена выполненых миграций  [BIM DOWN]

- Общая отмена:
```bash
php bim down

Отменяет весь список выполненных миграционных классов., <sub>(*11)</sub>

• Еденичная отмена: ``` bash php bim down 1423660766

Отменяет указанную в праметрах миграцию.

- Отмена по временному периоду:
```bash
php bim down --from="29.01.2015 00:01" --to="29.01.2015 23:55"

• Отмена по тегу:

php bim down --tag=iws-123

Отменяет все миграции где найден указанный тег в описании., <sub>(*12)</sub>

• Логирование: ``` bash php bim down --logging

# 5 <a name="ls"></a>Вывод списка миграций [BIM LS]
- Общей список:
```bash
php bim ls

• Список выполненных миграций:

php bim ls --a

• Список отменённых миграций:

php bim ls --n

• Список миграций за определённый период времени:

php bim ls --from="29.01.2015 00:01" --to="29.01.2015 23:55" 

• Список миграций по тегу:

php bim ls --tag=iws-123

6 Создание новых миграций [BIM GEN]

Существует два способа создания миграций:, <sub>(*13)</sub>

1) Создание пустой миграции:

Создается пустой шаблон миграционного класса. Структура класса определена интерфейсом Bim/Revision и включает следующие обязательные методы:, <sub>(*14)</sub>

• up(); - выполнение
• down(); - отмена
• getDescription(); - получения описания.
• getAuthor(); - получение автора.

Дополнительно запрашивается: - [Description], <sub>(*15)</sub>

Пример:, <sub>(*16)</sub>

``` bash php bim gen, <sub>(*17)</sub>

Также возможно передать description опционально:
``` bash  
php bim gen --d="new description #iws-123"

Далее создается файл миграции вида: */[migrations_path]/[timestamp].php, <sub>(*18)</sub>

Например: /migrations/123412434.php, <sub>(*19)</sub>

2) Создание миграционного кода по наличию:

Создается код развертывания/отката существующего элемента схемы bitrix БД. На данный момент доступно генерация по наличию для следующих элементов bitrix БД:, <sub>(*20)</sub>

2.1 IblockType ( php bim gen IblockType:[add|delete] ):

Создается Миграционный код "Типа ИБ" включая созданные для него (UserFields, IBlock, IblockProperty), <sub>(*21)</sub>

Дополнительно запрашивается: - [IBLOCK_TYPE_ID] - [Description], <sub>(*22)</sub>

Пример:, <sub>(*23)</sub>

``` bash php bim gen IblockType:add, <sub>(*24)</sub>

Также возможно передать iblock type id и description опционально:
``` bash  
php bim gen IblockType:add --typeId=catalog --d="new description #iws-123"

2.2 Iblock ( php bim gen Iblock:[add|delete] ):

Создается Миграционный код "ИБ" включая созданные для него (IblockProperty), <sub>(*25)</sub>

Дополнительно запрашивается: - [IBLOCK_CODE] - [Description], <sub>(*26)</sub>

Пример: ``` bash
php bim gen Iblock:add, <sub>(*27)</sub>

Также возможно передать iblock code и description опционально:
``` bash  
php bim gen Iblock:add --code=goods --d="new description #iws-123"

2.3 IblockProperty ( php bim gen IblockProperty:[add|delete] ):

Создается Миграционный код "Свойства ИБ", <sub>(*28)</sub>

Дополнительно запрашивается: - [IBLOCK_CODE] - [PROPERTY_CODE] - [Description], <sub>(*29)</sub>

Пример: ``` bash
php bim gen IblockProperty:add, <sub>(*30)</sub>

Также возможно передать iblock code, property code и description опционально:
``` bash  
php bim gen IblockProperty:add --code=goods --propertyCode=NEW_ITEM --d="new description #iws-123"

2.4 Hlblock ( php bim gen Hlblock:[add|delete] ):

Создается Миграционный код "Highloadblock" включая созданные для него (UserFields), <sub>(*31)</sub>

Дополнительно запрашивается: - [HLBLOCK_ID] - [Description], <sub>(*32)</sub>

Пример: ``` bash
php bim gen Hlblock:add, <sub>(*33)</sub>

Также возможно передать hlblock id и description опционально:
``` bash  
php bim gen IHlblock:add --id=82 --d="new description #iws-123"

2.5 HlblockField ( php bim gen HlblockField:[add|delete] ):

Создается Миграционный код "HighloadblockField (UserField)", <sub>(*34)</sub>

Дополнительно запрашивается: - [HLBLOCK_ID] - [USER_FIELD_ID] - [Description], <sub>(*35)</sub>

Пример: ``` bash
php bim gen HlblockField:add, <sub>(*36)</sub>

Также возможно передать hlblock id, hlblock field id и description опционально:
``` bash  
php bim gen IHlblock:add --hlblockid=93 --hlFieldId=582 --d="new description #iws-123"

2.6 Group ( php bim gen Group:[add|delete] ):

Создается Миграционный код "Group (Группы пользователей)", <sub>(*37)</sub>

Дополнительно запрашивается: - [GROUP_ID] - [Description], <sub>(*38)</sub>

Пример: ``` bash
php bim gen Group:add, <sub>(*39)</sub>

Также возможно передать group id, и description опционально:
``` bash  
php bim gen Group:add --id=5 --d="new description #iws-123"

2.7 Site ( php bim gen Site:[add|delete] ):

Создается Миграционный код "Site (Сайты)", <sub>(*40)</sub>

Дополнительно запрашивается: - [SITE_ID] - [Description], <sub>(*41)</sub>

Пример: ``` bash
php bim gen Site:add, <sub>(*42)</sub>

Также возможно передать site id, и description опционально:
``` bash  
php bim gen Site:add --id=s1 --d="new description #iws-123"

Обратите внимание!, <sub>(*43)</sub>

что миграционные классы созданные по наличию, выполняются автоматически., <sub>(*44)</sub>

Режим multi [BIM GEN MULTI]:

Так же доступен режим массовой генерации по наличию. Данный способ удобен при созданиие миграций по наличию для множества одинаковых элементов. Например для нескольких UserFields., <sub>(*45)</sub>

Пример:, <sub>(*46)</sub>

``` bash php bim gen multi, <sub>(*47)</sub>

## <a name="tag"></a> Тегирование миграций:

При создании нового миграционного класса существует возможность выставления тега в комментарии к миграции для дальнейшей более удобной отмены либо выполнения группы миграций связанных одним тегом.

**Формат**: #[название]

**Пример:**
Как вариант применения, вставлять тег номера задачи из трекера.

``` bash
[Description]: #IWS-242 Add new Iblock[services]

Логирование:

Существует возможность логирования информации о состоянии выполнения или отмены миграций., <sub>(*48)</sub>

Пример: ``` bash php bim up --logging, <sub>(*49)</sub>

или
``` bash
php bim down --logging

Примечание: По умолчанию инфомация сохраняется в файл вида _log/bim/[Year]/[Month]/[Day]/bim.log, <sub>(*50)</sub>

7 Информация о проекет [BIM INFO]

Информация о текущем bitrix проекте:, <sub>(*51)</sub>

• Название проекта
• Версия bitrix
• Редакция bitrix

Пример: bash php bim info, <sub>(*52)</sub>