Drupal 8 Migration with Multiple Paragraph References

Joel Steidl

As of Fall 2018 and the release of Drupal 8.6, the Migrate module in core is finally stabilizing! Hopefully Migrate documentation will continue to solidify, but there are plenty of gaps to fill.

Recently, I ran into an issue migrating Paragraph Entities (Entity Reference Revisions) that had a few open core bugs and ended up being really simple to solve within prepareRow in the source plugin.


In my destination D8 site, I had a content type with a Paragraph reference field. Each node contained one or more Paragraph entities. This was reflected by having a Node migration with a dependency on a Paragraph Entity migration.

With single value entity references, the migration_lookup plugin makes it really easy lookup up entity reference identifiers that were previously imported. As of September 2018, there is an open core issue to allow multiple values with migration_lookup. Migration lookup uses the migration map table created in the database to connect previously migrated data to Drupal data. The example below lookups up the taxonomy term ID based on the source reference (topic_area_id) from a previously ran migration. Note: You will need to add a migration dependency to your migration yml file to make sure migrations are run in the correct order.



Without using a Drupal Core patch, we need a way to do a migration_lookup in a more manual way. Thankfully prepareRow in your Migrate source plugin makes this pretty easy.

Note: This is not a complete Migrate source plugin. All the methods are there, but I’m focussing on the prepareRow method for this post. The most important part of the code is manually querying the Migrate map database table created in the Paragraph Entity migration.

span style="color: #808080; font-style: italic;">/**
* Source plugin for Sample migration.
* @MigrateSource(
*   id = "sample"
* )
  * {@inheritdoc}
  */// Query source data.
  * {@inheritdoc}
  */// Add source fields.
  * {@inheritdoc}
  */'item_id' => [
       'type' => 'integer',
       'alias' => 'item_id',
  * {@inheritdoc}
  */// In migrate source plugins, the migrate database is easy.
   // Example: $this->select('your_table').
   // Getting to the Drupal 8 db requires a little more code.
'default', 'default');
   $paragraphs = [];
   $results = $drupalDb->select('your_migrate_map_table', 'yt')
     ->fields('yt', ['destid1', 'destid2'])
     ->condition('yt.sourceid2', $row->getSourceProperty('item_id'), '='// destid1 in the map table is the nid.
       // destid2 in the map table is the entity revision id.
       $paragraphs[] = [
         'target_id' => $result->destid1,
         'target_revision_id' => $result->destid2,
   // Set a source property that can be referenced in yml.
  // Source properties can be named however you like.

In your migration yml file, you can reference the prepare_multiple_paragraphs that was created in the migrate source plugin like this:

id: sample
label: 'Sample'

Sub_process was formally the iterator plugin and allows you to loop over items. This will properly create references to multiple Paragraph Entities. It will be nice when the migration_lookup plugin can properly handle this use case, but it’s a good thing to understand how prepareRow can provide flexibility.

About the Author

With over ten years of professional experience, Joel's joint background in design, development and information architecture allows him to lead our development team with a focus on building user-centered web applications.

Read More