Migrate API in Drupal 8

Same name and namespace in other branches

1. 9 core/modules/migrate/migrate.api.php \migration

Overview of the Migrate API, which migrates data into Drupal.

Overview of a migration

Migration is an Extract, Transform, Load (ETL) process. In the Drupal Migrate API, the extract phase is called 'source', the transform phase is called 'process', and the load phase is called 'destination'. It is important to understand that the term 'load' in ETL refers to loading data into the storage while in a typical Drupal context the term 'load' refers to loading data from storage.

In the source phase, a set of data, called the row, is retrieved from the data source. The data can be migrated from a database, loaded from a file (for example CSV, JSON or XML) or fetched from a web service (for example RSS or REST). The row is sent to the process phase where it is transformed as needed or marked to be skipped. Processing can also determine if a 'stub' needs to be created. For example, if a term has a parent term which hasn't been migrated yet, a stub term is created so that the parent relation can be established, and the stub is updated at a later point. After processing, the transformed row is passed to the destination phase where it is loaded (saved) into the target Drupal site.

Migrate API uses the Drupal plugin system for many different purposes. Most importantly, the overall ETL process is defined as a migration plugin and the three phases (source, process and destination) have their own plugin types.

Migrate API migration plugins

Migration plugin definitions are stored in a module's 'migrations' directory. The plugin class is \Drupal\migrate\Plugin\Migration, with interface \Drupal\migrate\Plugin\MigrationInterface. Migration plugins are managed by the \Drupal\migrate\Plugin\MigrationPluginManager class. Migration plugins are only available if the providers of their source plugins are installed.

Example migrations in Migrate API handbook.

Migrate API source plugins

Migrate API source plugins implement \Drupal\migrate\Plugin\MigrateSourceInterface and usually extend \Drupal\migrate\Plugin\migrate\source\SourcePluginBase. They are annotated with \Drupal\migrate\Annotation\MigrateSource annotation and must be in namespace subdirectory 'Plugin\migrate\source' under the namespace of the module that defines them. Migrate API source plugins are managed by the \Drupal\migrate\Plugin\MigrateSourcePluginManager class.

List of source plugins provided by the core Migrate module. Core and contributed source plugin usage examples in Migrate API handbook.

Migrate API process plugins

Migrate API process plugins implement \Drupal\migrate\Plugin\MigrateProcessInterface and usually extend \Drupal\migrate\ProcessPluginBase. They are annotated with \Drupal\migrate\Annotation\MigrateProcessPlugin annotation and must be in namespace subdirectory 'Plugin\migrate\process' under the namespace of the module that defines them. Migrate API process plugins are managed by the \Drupal\migrate\Plugin\MigratePluginManager class.

List of process plugins for common operations provided by the core Migrate module.

Migrate API destination plugins

Migrate API destination plugins implement \Drupal\migrate\Plugin\MigrateDestinationInterface and usually extend \Drupal\migrate\Plugin\migrate\destination\DestinationBase. They are annotated with \Drupal\migrate\Annotation\MigrateDestination annotation and must be in namespace subdirectory 'Plugin\migrate\destination' under the namespace of the module that defines them. Migrate API destination plugins are managed by the \Drupal\migrate\Plugin\MigrateDestinationPluginManager class.

List of destination plugins for Drupal configuration and content entities provided by the core Migrate module.

Documentation handbooks

Migrate API handbook. Upgrading to Drupal 8 handbook.

File

core/modules/migrate/migrate.api.php, line 12

Hooks provided by the Migrate module.

Functions

Classes

Interfaces