Deprecated
Migration Manager is now Migration Assistant. We have transitioned to a paid plugin in order to provide better support and updates going forward. As Craft continues to grow and evolve and more people take advantage of simplified migrations via the Migration Manager, it was becoming difficult to provide a level of support and responsiveness that people needed when depending on this plugin to help manage their Craft sites. The current free version of Migration Manager will remain available for a period of time to ensure a smooth transition for everyone using the plugin. Thank you to everyone who used this plugin and offered feedback to make it better., (*1)
Create migrations to easily move settings and content between CraftCMS website installations with the click of a mouse, no coding required. You can select which elements to migrate and create a native Craft content migration file that can be committed to your version control system. The migration(s) can then be applied on different CraftCMS installations to instantly create and update settings and content, without needing to enter data multiple times. By using migrations you can ensure your various website environments (local, staging, production, etc.) stay in sync and up to date., (*2)
Related: Migration Manager for Craft 2.x, (*3)
Installation
Plugin Store (the easy way)
- In the Craft Control Panel, go to Settings -> Plugins
- Search for 'MigrationManager'
- click the "Install" button
Composer Command Line (the manual way)
- Go to the command line and
cd to your project's root folder
- Add repository to your projects composer.json file
composer config repositories.migrationmanager vcs https://github.com/Firstborn/Craft-Migration-Manager.git
- Download the plugin via composer
composer require firstborn/migrationmanager
- In the Craft Control Panel, go to Settings -> Plugins
- Click the "Install" button for MigrationManager
Overview
The Migration Manager can create migrations for the following tasks:, (*4)
- adding and updating:
- fields
- sections and entry types
- categories
- asset volumes and transformations
- user groups
- sites and locales
- tags
- routes
- email settings
- adding and updating content:
- entries
- categories
- globals
- users
To create a migration select the elements you wish to migrate and then click the 'Create Migration' button at the bottom of the page., (*5)
, (*6)
It is important to remember to create Migrations in an order that is consistent with manually creating fields, sections etc. Fields must exist before they can be added to Sections. Categories must exist before they can be used by Fields, etc. When creating migrations keep that in mind, break your migrations into smaller steps to prevent issues instead of one large migration., (*7)
A migration file will be created in the craft/migrations folder. The migration filename will contain the slugs/handles of the migrated items. Move the new migration file to your destination environment, ideally with version control., (*8)
- In your development environment:
git add .
git commit -am 'new migration'
git push
- In your destination environment:
git pull
When new migration(s) are in your destination environment a badge will appear to let you know. Click on the 'Migrations' tab and run the new migrations. You can run all the pending migrations by simply clicking the Run Migrations button or you can select individual migrations to run. You can also run migrations from the native Craft/Utilities/Migrations tab (this only allows you to run all pending migrations, not individual ones)., (*9)
, (*10)
The MigrationManager uses Craft's built in migrator to run migrations. Failed migrations will be rolled back and the database will be returned to it's pre migration state. You can check both the Craft logs to see details on why the migration failed. In many instances it's simply a case of a migration having dependencies (ie required fields) that have not been setup on the destination site or a missing plugin., (*11)
You can also view previously applied migrations by clicking the 'Applied' tab on the MigrationManager/Migrations page. This will show you migrations that have already been applied and migrations that were created locally (and don't need to be run locally). Note that if you create blank migrations (by clicking the Create Migration button without selecting elements) they will show up in the New Migrations list, so that you have a chance to test and run them locally with your custom migration code., (*12)
Field type support
Migration manager currently supports all core CraftCMS fields types:, (*13)
- Assets
- Categories
- Checkboxes
- Color
- Date/Time
- Dropdown
- Entries
- Lightswitch
- Matrix
- Multi-select
- Number
- Plain Text
- Radio Buttons
- Rich Text
- Table
- Tags
- Url
- Users
In addition it also supports:, (*14)
To support additional field types and special content you can use event handlers for customized import/export functions. There are two distinct types of export/import procedures you need to consider when adding custom support. Exporting/importing element settings and exporting/importing element content., (*15)
To handle export/import of custom field types your plugin/module should listen for the Export/Import events that are triggered from elements that utilize fields. Following is the list of elements that the Migration Manager has events for that allow you to modify the export/import data to support custom fields., (*16)
Settings
- AssetSource
- AssetTransform (only after import)
- Categories
- Fields
- Globals
- Sections
- Sites
- Tags
- UserGroups
You can also listen for export/import events on pure content migrations to modify data or perform additional actions as part of a migration., (*17)
Content
- Entries
- Categories
- Globals
- Users
Using events
During the export event you can modify the \$event->value data to include any additional settings not already in the data to be exported., (*18)
//Custom field example
Event::on(Fields::class, Fields::EVENT_BEFORE_EXPORT_ELEMENT, function(ExportEvent $event) {
$value = $event->value;
$value['typesettings']['special_setting'] = 'some special setting value';
$event->value = $value;
});
During the import you can modify the data before it is imported or deal with the element after it has been imported and either created or updated., (*19)
Before import, the $event->element is the element model (based on handle match) to be imported (updated or created). The $event->value property is the raw data used to populate the element model. Change properties in the \$event->element to modify the element before it is saved., (*20)
//Custom fields
Event::on(Fields::class, Fields::EVENT_BEFORE_IMPORT_ELEMENT, function(ExportEvent $event) {
$element = $event->element;
$element->special_setting = $event->value['settings']['special_setting'];
$event->element = $element;
});
After import you can access the $event->element and $event->value to perform additional operations related to the element if needed., (*21)
Event::on(Fields::class, Fields::EVENT_AFTER_IMPORT_ELEMENT, function(ExportEvent $event) {
$event->value['typesettings']['special_setting'] = 'some special setting value';
});
You can also cancel an import if needed and provide an error message. Error messages will be written to the Craft web log., (*22)
//Custom fields
Event::on(Fields::class, Fields::EVENT_BEFORE_IMPORT_ELEMENT, function(ExportEvent $event) {
$event->isValid = false;
$event->error = 'my reason for cancelling';
});
Any values in the field data that contains id's should be converted to handles/slug or some string based value that can be looked up on the destination site without depending on matching id values as id values can differ between website database instances., (*23)
For importing custom fields the imported value should match the fields required input structure. Check the field type's documentation and code for help on determining the correct structure., (*24)
Content migrations
With migrations you also have the ability to create content migrations directly from element index pages (ie the entry, category and user list pages). Select the entries you wish to export and then click the 'create migration' option in the action list. Content migrations are dependent on a workflow where you migrate related/dependent elements first. For example, if you have an entry that has some selected categories, the categories need exist on the destination site before the entry migration will work correctly. This means creating a migration of the category(ies) first. This holds true for users, assets other other entries. In the case of assets you will need to ensure the matching asset (based on asset source/folder/filename) exists on the destination site. For Global values, use the 'Create Migration' button on the global screen., (*25)
, (*26)
Permissions
By default all users with admin rights have full access to the Migration Manager and the ability to create content migrations. Non admin users can be granted permissions to access the Migration Manager and to create content migrations in the user/permissions section of Craft., (*27)
Custom migrations
In addition to generated migrations you can use the MigrationManger to create empty migrations that can be used for tasks like deleting fields and creating content. To create an empty migration simply click the 'Create Migration' on the Migration Manager/Create Migrations tab. A new empty migration will be added to the craft/migrations folder., (*28)
View the examples., (*29)
To learn more about creating custom migrations:, (*30)
Credits
The entire dev team at Firstborn, (*31)
Flying Duck icon by Agne Alesiute from the Noun Project, (*32)
Wallogit.com
