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 Migration API, which migrates data into Drupal.

Overview of migration

Migration is an Extract, Transform, Load (ETL) process. For historical reasons, in the Drupal migration tool the extract phase is called "source", the transform phase is called "process", and the load phase is called "destination".

Source, process, and destination phases are each provided by plugins. Source plugins extract data from a data source in "rows", containing "properties". Each row is handed off to one or more series of process plugins, where each series operates to transform the row data into one result property. After all the properties are processed, the resulting row is handed off to a destination plugin, which saves the data.

The Migrate module provides process plugins for common operations (setting default values, mapping values, etc.), and destination plugins for Drupal core objects (configuration, entity, URL alias, etc.). The Migrate Drupal module provides source plugins to extract data from various versions of Drupal. Custom and contributed modules can provide additional plugins; see the Plugin API topic for generic information about providing plugins, and sections below for details about the plugin types.

The configuration of migrations is stored in configuration entities, which list the IDs and configurations of the plugins that are involved. See Migration configuration entities below for details. To migrate an entire site, you'll need to create a migration manifest; see Migration manifests for details.

https://www.drupal.org/node/2127611 has more complete information on the Migration API, including information on load plugins, which are only used in Drupal 6 migration.

Source plugins

Migration 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. Migration source plugins are managed by the \Drupal\migrate\Plugin\MigratePluginManager class.

Process plugins

Migration 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. Migration process plugins are managed by the \Drupal\migrate\Plugin\MigratePluginManager class.

Destination plugins

Migration 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. Migration destination plugins are managed by the \Drupal\migrate\Plugin\MigrateDestinationPluginManager class.

Migration configuration entities

The definition of how to migrate each type of data is stored in configuration entities. The migration configuration entity class is \Drupal\migrate\Entity\Migration, with interface \Drupal\migrate\Entity\MigrationInterface; the configuration schema can be found in the migrate.schema.yml file. Migration configuration consists of IDs and configuration for the source, process, and destination plugins, as well as information on dependencies. Process configuration consists of sections, each of which defines the series of process plugins needed for one destination property. You can find examples of migration configuration files in the core/modules/migrate_drupal/config/install directory.

Migration manifests

You can run a migration with the "drush migrate-manifest" command, providing a migration manifest file. This file lists the configuration names of the migrations you want to execute, as well as any dependencies they have (you can find these in the "migration_dependencies" sections of the individual configuration files). For example, to migrate blocks from a Drupal 6 site, you would list:

# Migrate blocks from Drupal 6 to 8
-d6_filter_format - d6_custom_block - d6_block;

See also

Update API


core/modules/migrate/migrate.api.php, line 12
Hooks provided by the Migrate module.


Namesort descending Location Description
hook_migrate_prepare_row core/modules/migrate/migrate.api.php Allows adding data to a row before processing it.


Namesort descending Location Description
CckFieldPluginBase core/modules/migrate_drupal/src/Plugin/migrate/cckfield/CckFieldPluginBase.php The base class for all cck field plugins.
DestinationBase core/modules/migrate/src/Plugin/migrate/destination/DestinationBase.php Base class for migrate destination classes.
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.
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.
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 all source plugins.


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.