README

Bitrix-migrations

Database migrations for Bitrix CMS and more

Installation

1. composer require aniart-solutions/bitrix-migrations

2. cp vendor/aniart-solutions/bitrix-migrations/migrator migrator - copy the executable file to a convenient location.

3. Open the file and make sure that $_SERVER['DOCUMENT_ROOT'] is set correctly. Change settings if needed.

4. php migrator install

This command will create a table in the database to store the names of executed migrations.

By default:

1. The table is called migrations.

2. composer.json and migrator are located in the site root.

3. Migration files will be created in the ./migrations directory relative to the file copied in step 2.

If necessary, all of this can be changed in the copied migrator file.

• It is highly recommended to make migrator and ./migrations inaccessible via HTTP through the web server. *

Usage

Workflow

The workflow is done through the console and is briefly described as follows:

1. Create a migration file (or files) using php migrator make migration_name

A migration file is a class with two methods: up() and down()

1. Implement the necessary database changes in the up() method. Optionally, implement rollback of these changes in the down() method.

2. Apply available migrations - php migrator migrate

3. Add migration files to version control so they can be run on other machines.

Available Commands

You can get a list of available commands in the console - php migrator list

Migration Templates

Since changing the Bitrix database structure through its API is extremely unpleasant, there is a migration template mechanism to facilitate this process, which works as follows: When generating a migration file, you can specify its template: php migrator make migration_name -t add_iblock where add_iblock is the template name. A class with a boilerplate from the template will be generated and you only need to specify the details (for example, the name and code of the infoblock) You can add your own migration templates directly in the migrator file using TemplateCollection::registerTemplate()

Available templates:

Automatic Migration Creation

Another killer feature is the automatic migration creation mode. To enable it, add something like the following to init.php

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

The path to the directory similar to the config in the migrator file is passed to the Manager::init() method.

After that, when performing a number of actions in the admin panel, the following will happen:

1. A Bitrix event handler is triggered

2. A migration file is created as with php migrator make

3. The migration is marked as applied

4. A notification about the previous points is shown

Enabling this mode allows you to get rid of manually writing migrations for many cases. Nothing needs to be edited in automatically created migrations.

List of handled events:

• Migrations use OnBefore... events. If an error occurred during your change (for example, the site binding was not specified when adding an infoblock) and a notification was shown that the migration was created, you must manually rollback such a migration using php migrator rollback --hard --delete *

Migration Error Handling

To cancel a migration during its execution, it is enough to throw an exception - php throw new MigrationException('Error text here'); Neither the migration itself nor subsequent ones will be applied.

Usage Outside Bitrix

The package is created for use with Bitrix, but it can be easily used in other systems as well. To do this, you need to in the migrator file:

1. Replace the Bitrix core connection with the core of another system.

2. Implement your own analogue of AniartSolutions\BitrixMigrations\Repositories\BitrixDatabaseRepository; and use it.

3. Optionally disable existing migration templates by creating your own.