1. 8.5.x core/modules/migrate/migrate.api.php migration
  2. 8.0.x core/modules/migrate/migrate.api.php migration
  3. 8.1.x core/modules/migrate/migrate.api.php migration
  4. 8.2.x core/modules/migrate/migrate.api.php migration
  5. 8.3.x core/modules/migrate/migrate.api.php migration
  6. 8.4.x core/modules/migrate/migrate.api.php migration
  7. 8.6.x 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

Namesort descending Location Description
hook_migrate_MIGRATION_ID_prepare_row core/modules/migrate/migrate.api.php Allows adding data to a row for a migration with the specified ID.
hook_migrate_prepare_row core/modules/migrate/migrate.api.php Allows adding data to a row before processing it.
hook_migration_plugins_alter core/modules/migrate/migrate.api.php Allows altering the list of discovered migration plugins.

Classes

Namesort descending Location Description
CckFieldPluginBase Deprecated core/modules/migrate_drupal/src/Plugin/migrate/cckfield/CckFieldPluginBase.php The base class for all field plugins.
DestinationBase core/modules/migrate/src/Plugin/migrate/destination/DestinationBase.php Base class for migrate destination classes.
FieldPluginBase core/modules/migrate_drupal/src/Plugin/migrate/field/FieldPluginBase.php The base class for all field plugins.
MigrateCckFieldPluginManager Deprecated core/modules/migrate_drupal/src/Plugin/MigrateCckFieldPluginManager.php Deprecated: Plugin manager for migrate field plugins.
MigrateDestination core/modules/migrate/src/Annotation/MigrateDestination.php Defines a migration destination plugin annotation object.
MigrateDestinationPluginManager core/modules/migrate/src/Plugin/MigrateDestinationPluginManager.php Plugin manager for migrate destination plugins.
MigrateFieldPluginManager core/modules/migrate_drupal/src/Plugin/MigrateFieldPluginManager.php Plugin manager for migrate field plugins.
MigratePluginManager core/modules/migrate/src/Plugin/MigratePluginManager.php Manages migrate plugins.
MigrateProcessPlugin core/modules/migrate/src/Annotation/MigrateProcessPlugin.php Defines a migration process plugin annotation object.
MigrateSource core/modules/migrate/src/Annotation/MigrateSource.php Defines a migration source plugin annotation object.
MigrateSourcePluginManager core/modules/migrate/src/Plugin/MigrateSourcePluginManager.php Plugin manager for migrate source plugins.
ProcessPluginBase core/modules/migrate/src/ProcessPluginBase.php The base class for all migrate process plugins.
SourcePluginBase core/modules/migrate/src/Plugin/migrate/source/SourcePluginBase.php The base class for source plugins.

Interfaces

Namesort descending Location Description
MigrateDestinationInterface core/modules/migrate/src/Plugin/MigrateDestinationInterface.php Defines an interface for Migration Destination classes.
MigrateProcessInterface core/modules/migrate/src/Plugin/MigrateProcessInterface.php An interface for migrate process plugins.
MigrateSourceInterface core/modules/migrate/src/Plugin/MigrateSourceInterface.php Defines an interface for migrate sources.