n the previous article we provided a reference of available configuration options for migrate source plugins. In today’s article we are doing something similar for destination plugins. We will present a reference of available configuration options for migrate destination plugins provided by Drupal core and some contributed modules. Knowing which options are available might require some Drupal development knowledge. By providing this reference it should make the process of writing migrations easier.
For each migrate destination plugin we will present: the module that provides it, the class that defines it, the class that the plugin extends, and any inherited options from the class hierarchy. For each plugin configuration option we will list its name, type, a description, and a note if it is optional.
DestinationBase (abstract class)
Module: Migrate (Drupal Core)
Class: Drupal\migrate\Plugin\migrate\destination\DestinationBase
Extends: Drupal\Core\Plugin\PluginBase
This abstract class is extended by many migrate destination plugins. This means that the provided configuration keys apply to any destination plugin extending it.
List of configuration keys:
- destination_module: An optional string value. Identifies the module handling the destination data. If not set, the Migrate API tries to read the value from the destination plugin definition.
Entity (abstract class)
Module: Migrate (Drupal Core) Plugin ID: `entity:$entity_type` See below.
Class: Drupal\migrate\Plugin\migrate\destination\Entity
Extends: Drupal\migrate\Plugin\migrate\destination\DestinationBase
Inherited configuration options: destination_module.
Related article: Drupal migrations reference: List of properties per content entity
This abstract class is extended by migrate destination plugins that want to import entities. It uses the MigrateEntity derivative to handle both content and configuration entities. The derivative sets the plugin ID to `entity:$entity_type` where $entity_type is the machine name of the entity. For example, `entity:node` and `entity:node_type`.
By default, content entities are handled by the EntityContentBase class while configuration entities use EntityConfigBase. Some entities like user (content) and node type (configuration) use specific classes for the import operation. The DefaultPluginManager::getDefinitions method triggers the search for classes that will override the default for a particular plugin ID. The override ultimately happens in the DerivativeDiscoveryDecorator::getDerivatives method.
In addition to the keys provided in the parent class chain, this abstract class provides the following configuration keys, which will be available to its derivatives:
- default_bundle: An optional string value. Gets the bundle for the row taking into account the default. If not present, the `bundle` entity key should be set in the `process` section for entities that can have more than one bundle. For example, the `type` property for nodes, the `vid` property for taxonomy terms, and the `bundle` property for media entities.
EntityContentBase
Module: Migrate (Drupal Core) Plugin ID: `entity:$entity_type` See below.
Class: Drupal\migrate\Plugin\migrate\destination\EntityContentBase
Extends: Drupal\migrate\Plugin\migrate\destination\Entity
Inherited configuration options: destination_module and default_bundle.
This class is used to handle import operations for all content entities, unless a specific class exists for the plugin ID being used. For example, nodes are handled by this class, but users leverage the EntityUser class. The MigrateEntity derivative sets the plugin ID to `entity:$entity_type` where $entity_type is the machine name of the content entity. For example, `entity:node`, `entity:user`, `entity:taxonomy_term`, `entity:file`, `entity:media`, `entity:comment`, `entity:block_content`, and `entity:contact_message`.
In addition to the keys provided in the parent class chain, this class provides the following configuration keys:
- translations: An optional boolean value. It indicates if the entity is translatable, defaults to FALSE. If set to TRUE, the corresponding `langcode` entity key will be added to the list of destination IDs that uniquely identifies each record. If the migration itself does not provide a value for the langcode property, the site’s default language is used.
- overwrite_properties: An optional array of string values. It is a list of properties or fields in the destination entity that will be overwritten if an entity with the same ID already exists. Any properties that are not listed will not be overwritten. Refer to the class documentation for an example.
- validate: An optional boolean value. It indicates whether an entity should be validated, defaults to FALSE. This was introduced in Drupal 8.8 and can be used to prevent invalid entities from being migrated. For example, a node with an empty title would fail validation. A required field that is not set by the migration will trigger a validation error, unless the field is configured to have a default value. Similarly, an integer field with minimum and maximum values will trigger an error if a value outside that range tries to be imported. Field API validations are triggered when this configuration option is set to TRUE.
EntityUser
Module: User (Drupal Core) Plugin ID: `entity:user` See below.
Class: Drupal\user\Plugin\migrate\destination\EntityUser
Extends: Drupal\migrate\Plugin\migrate\destination\EntityContentBase
Inherited configuration options: destination_module, default_bundle, translations, overwrite_properties, and validate.
This class provides a destination plugin for migrating user entities. It performs extra checks like preventing that the password for user 1 is overridden by the migration.
In addition to the keys provided in the parent class chain, this abstract class provides the following configuration keys:
- md5_passwords: An optional boolean value. If set to TRUE, the `pass` (password) property of the user entity is assumed to contain an MD5 hash. The passwords will be salted and re-hashed before they are saved to the destination Drupal database.
EntityRevision
Module: Migrate (Drupal Core) Plugin ID: `entity_revision:$entity_type` See below.
Class: Drupal\migrate\Plugin\migrate\destination\EntityRevision
Extends: Drupal\migrate\Plugin\migrate\destination\EntityContentBase
Inherited configuration options: destination_module, default_bundle, translations, overwrite_properties, and validate.
This class provides an entity revision destination plugin. Only revisionable entities, those that define a `revision` entity key, can use this destination plugin. It uses the MigrateEntityRevision derivative which sets the plugin ID to `entity_revision:$entity_type` where $entity_type is the machine name of the entity. For example, `entity_revision:node` whose revision key is `vid` and `entity_revision:block_content` whose revision key is `revision_id`.
Entity revisions can only be migrated after the entity to which they belong has been migrated. For example, revisions of a given node (`entity_revision:node` destination migration) can be migrated only after the current version of that node (`entity:node` destination migration) has been imported.
EntityReferenceRevisions
Module: Entity Reference Revisions module Plugin ID: `entity_reference_revisions:$entity_type` See below.
Class: Drupal\entity_reference_revisions\Plugin\migrate\destination\EntityReferenceRevisions
Extends: Drupal\migrate\Plugin\migrate\destination\EntityRevision
Inherited configuration options: destination_module, default_bundle, translations, overwrite_properties, and validate.
Related article: Introduction to paragraphs migrations in Drupal
This class provides an entity revision revision destination plugin. It uses the MigrateEntityReferenceRevisions derivative which sets the plugin ID to `entity_reference_revisions:$entity_type` where $entity_type is the machine name of the entity. For example, `entity_reference_revisions:node` and `entity_reference_revisions:paragraph`. For example, `entity_reference_revisions:node` whose revision key is `vid` and `entity_reference_revisions:paragraph` whose revision key is `revision_id`.
This is the destination plugin used for migrating Paragraphs. Entity reference fields are no longer supported to reference Paragraphs. Instead, entity entity reference revisions must be used. Therefore, this class is used for paragraphs migrations with the `entity_reference_revisions:paragraph` plugin ID. See this article for an example on how to migrate paragraphs.
In addition to the keys provided in the parent class chain, this abstract class provides the following configuration keys:
- new_revisions: An optional boolean value. Flag to indicate if a new revision should be created instead of updating a previous default record. Only applicable when providing an entity id without a revision_id. Defaults to FALSE.
EntityConfigBase
Module: Migrate (Drupal Core) Plugin ID: `entity:$entity_id` See below.
Class: Drupal\migrate\Plugin\migrate\destination\EntityConfigBase
Extends: Drupal\migrate\Plugin\migrate\destination\Entity
Inherited configuration options: destination_module and default_bundle.
This class is used to handle import operations for all configuration entities, unless a specific class exists for the plugin ID being used. For example, taxonomy vocabularies are handled by this class, but node types leverage the EntityNodeType class. The MigrateEntity derivative sets the plugin ID to `entity:$entity_type` where $entity_type is the machine name of the content entity. For example, `entity:node_type`, `entity:user_role`, `entity:taxonomy_vocabulary`, `entity:block`, `entity:comment_type`, `entity:block_content_type`, `entity:contact_form`, `entity:date_format`.
In addition to the keys provided in the parent class chain, this abstract class provides the following configuration keys:
- translations: An optional boolean value. if TRUE, the destination will be associated with the langcode provided by the source plugin. Defaults to FALSE. For example: `en` for English, `es` for Spanish, and `fr` for French.
EntityNodeType
Module: Node (Drupal Core) Plugin ID: `entity:node_type`
Class: Drupal\node\Plugin\migrate\destination\EntityNodeType
Extends: Drupal\migrate\Plugin\migrate\destination\EntityConfigBase
Inherited configuration options: destination_module, default_bundle, and translations.
This class is used to import node types. It does not take extra configuration options. The plugin overrides the import method to attach the body field to the imported content type. This depends on the presence of certain destination properties in the imported row. That is, the following properties needs to be mapped in the process section of the migration:
- create_body: An optional boolean value. If TRUE, a body field will be added to the content type.
- create_body_label: An optional string value. If set and `create_body` is TRUE, the value for this destination property will be used as the label of the body field.
Config
Module: Migrate (Drupal Core) Plugin ID: `config`
Class: Drupal\migrate\Plugin\migrate\destination\Config
Extends: Drupal\migrate\Plugin\migrate\destination\DestinationBase
Inherited configuration options: destination_module.
This class persists data to the configuration management system. In addition to the keys provided in the parent class chain, this class provides the following configuration keys:
- store null: An optional boolean value. If TRUE, when a property is NULL, the NULL value is stored. Otherwise, the default value is used. Defaults to FALSE. Note that there is a space character in the configuration name.
- translations: An optional boolean value. if TRUE, the destination will be associated with the langcode provided by the source plugin. Defaults to FALSE.
Additionally, the plugin expects certain destination properties in the imported row. That is, the following properties needs to be mapped in the process section of the migration:
- config_name: A string value. The machine name of the configuration. For example: `node.settings`, `node.type.article`, `user.settings`, `system.site`, and `core.extension`.
- langcode: An optional string value. The language code of the configuration. For example: `en` for English, `es` for Spanish, and `fr` for French.
Table
Module: Migrate Plus Plugin ID: `table`
Class: Drupal\migrate_plus\Plugin\migrate\destination\Table
Extends: Drupal\migrate\Plugin\migrate\destination\DestinationBase
Inherited configuration options: destination_module.
This class allows you to write directly to a table not registered with Drupal Schema API. See this test for an example on how to use this plugin.
In addition to the keys provided in the parent class chain, this class provides the following configuration keys:
- database_key: An string value. Key for the database connection used for inserting records. See this documentation page for more information on database connection keys. We also covered the topic when explaining the SqlBase source plugin.
- table_name: An string value. Name of the table where records will be imported.
- batch_size: An optional integer value. Maximum number of rows to insert in one query. Defaults to 1.
- id_fields: An associative array value. Fields used to uniquely identify table rows. At least one field is required. See the class’s docblock for an example of the expected structure.
- fields: An optional associative array value. Mapping of column names to values set in the process section.
Available configuration for other migrate destination plugins
In Drupal core itself there are around 50 migrate destination plugins. And many more are made available by contributed modules. It would be impractical to document them all here. To get a list by yourself, load the `plugin.manager.migrate.destination` service and call its `getDefinitions()` method. This will return all migrate destination plugins provided by the modules that are currently enabled on the site. This Drush command would get the list:
# List of migrate destination plugin definitions.
$ drush php:eval "print_r(\Drupal::service('plugin.manager.migrate.destination')->getDefinitions());"
# List of migrate destination plugin ids.
$ drush php:eval "print_r(array_keys(\Drupal::service('plugin.manager.migrate.destination')->getDefinitions()));"
To find out which configuration options are available for any destination plugin consider the following:
- Find the class that defines the plugin and find out which configuration values are read. Some plugins even include the list in the docblock of the class. Search for a pattern similar to `$this->configuration[‘option_name’]` or `$configuration[‘option_name’]`. The plugins can be found in the `Drupal\module_name\Plugin\migrate\destination` namespace. The class itself would be in a file under the `/src/Plugin/migrate/destination/` directory of the module.
- Look up in the class hierarchy. The destination plugin can use any configuration set directly in its definition class and any parent class. There might be multiple layers of inheritance.
- Check if the plugin requires the presence of specific destination properties to be set in the process section. This is usually documented in the class’ docblock, but you can also look for code like `$row->getDestinationProperty(‘property_name’)`.
What did you learn in today’s article? Did you know that migrate destination plugins can inherit configuration keys from their class hierarchy? Were you aware that there are so many destination plugins? Other than the ones listed here, which destination plugins have you used? Please share your answers in the comments. Also, we would be grateful if you shared this article with your friends and colleagues.
