PHPackages                             diswebru/bitrix-migrations - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. diswebru/bitrix-migrations

ActiveLibrary

diswebru/bitrix-migrations
==========================

Database migrations for Bitrix CMS

1.0.2(1y ago)120MITPHPPHP >=8.2

Since Jan 25Pushed 1y ago1 watchersCompare

[ Source](https://github.com/DisWEBru/bitrix-migrations)[ Packagist](https://packagist.org/packages/diswebru/bitrix-migrations)[ Docs](https://github.com/DisWEBru/bitrix-migrations)[ RSS](/packages/diswebru-bitrix-migrations/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (3)Dependencies (5)Versions (4)Used By (0)

Bitrix-migrations
=================

[](#bitrix-migrations)

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

Установка
---------

[](#установка)

1. `composer require diswebru/bitrix-migrations`
2. `cp vendor/diswebru/bitrix-migrations/migrator migrator` - копируем исполняемый файл в удобное место.
3. в .env проекта нужно добавить параметр BX\_MIGRATION\_DOC\_ROOT с путем $\_SERVER\['DOCUMENT\_ROOT'\] (домашний путь) к 1С-Битрикс или заходим внутрь файла migrator и удостоверяемся что задается правильный $\_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()`

2. Реализуем в методе `up()`необходимые изменения в БД. При желании в методе `down()` реализуем откат этих измнений
3. Применяем имеющиеся миграции - `php migrator migrate`
4. Вносим файлы миграций в систему контроля версий, чтобы их можно было запустить и на других машинах

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

[](#доступные-команды)

Список доступных команд можно получить в консоли - `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`6. `php migrator status` - показывает доступные для выполнения миграции, а также последние выполненные.

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

[](#автоматическое-создание-миграций)

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

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

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

[](#использование-вне-битрикс)

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

1. Заменить подключение ядра Битрикса на ядро другой системы.
2. Реализовать свой аналог ` Diswebru\BitrixMigrations\Repositories\BitrixDatabaseRepository;` и использовать его.
3. По желанию отключить существующие шаблоны миграций, сделав свои.

###  Health Score

30

—

LowBetter than 64% of packages

Maintenance42

Moderate activity, may be stable

Popularity8

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity52

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

3

Last Release

478d ago

PHP version history (2 changes)1.0.0PHP >=7.3.0

1.0.1PHP >=8.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/f3a6b25959ee1af0c9e0b299e301517e834704492dbf5a01e493d9516f4745ae?d=identicon)[DisWEBru](/maintainers/DisWEBru)

---

Top Contributors

[![DisWEBru](https://avatars.githubusercontent.com/u/52661237?v=4)](https://github.com/DisWEBru "DisWEBru (4 commits)")

---

Tags

bitrixmigrations

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/diswebru-bitrix-migrations/health.svg)

```
[![Health](https://phpackages.com/badges/diswebru-bitrix-migrations/health.svg)](https://phpackages.com/packages/diswebru-bitrix-migrations)
```

###  Alternatives

[laravel/framework

The Laravel Framework.

34.7k509.9M17.0k](/packages/laravel-framework)[robmorgan/phinx

Phinx makes it ridiculously easy to manage the database migrations for your PHP app.

4.5k46.2M405](/packages/robmorgan-phinx)[bacula-web/bacula-web

The open source web based reporting and monitoring tool for Bacula

1537.5k](/packages/bacula-web-bacula-web)[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

245.2k](/packages/aedart-athenaeum)[zachleigh/yarak

Laravel inspired devtools for Phalcon. Database migrations, model factories and database seeders.

293.8k](/packages/zachleigh-yarak)[lion/bundle

Lion-framework configuration and initialization package

122.2k1](/packages/lion-bundle)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)