In previous posts, we have provided tips and tricks for a successful Drupal migration from earlier versions of the content management system to the latest Version 8. In this installment of our series, we will talk about the Drupal 8 Migrate Plugin System.
About Drupal 8 Migrate
The migrate module has been moved into the core in Drupal 8, showing the community dedicated to making the process of upgrading between versions or migrating into Drupal an easier path to a successful move. The migrate module takes advantage of the Drupal 8 Plugin system, offering developers several Plugin types that they can implement: MigrateProcessPlugin, MigrateSourcePlugin, MigrateDestinationPlugin.
In an earlier blog post in this series, we dove into an introduction of the Migrate module in Drupal 8 and reviewed a basic setup of the migration mappings needed to get started. In this post, we will dive into MigrateProcessPlugins: what they are, how they work and examples on how to create your own.
What is a Drupal 8 Migrate Processor?
A migration processor is a plugin that is used to manipulate data that is being mapped from a source to a destination. These plugins are typically small, but very powerful. Processors are used in the “process” portion of your migration configuration file.
Drupal 8 comes with several migration processors out-of-the-box. Some of the more notable ones that you will likely use on a regular basis are:
get – Default, 1:1 data migration plugin
default_value – Allows you to define a default value for a field
explode – Converts a string into an array of strings based on a delimiter
iterator – Iterates over an array of values to perform a process on
migration_lookup – Looks up an entity based on an ID from a source to a destination
skip_on_empty – Skips the current field or row if the value is empty in the migration
What Are the Benefits of Using a Drupal 8 Migrate Processor?
Migration process plugins provide developers with more flexibility and reusability when working with migrations in Drupal 8. By utilizing the Drupal 8 Plugin system, the Migrate module allows users to create new processors that implement a generic interface and can essentially be plug and play. In addition, the OO design of the plugin system allows developers to utilize inheritance of abstract classes and enforcement of methods if they have several variations of a plugin, without reinventing the wheel or duplicating code every time.
In English, this means that I can develop my own processors that manipulate data from my data source in any way that I want, and then reuse it across any migration that needs to use it.
How Does a MigrateProcessPlugin Work?
If you are finding that the out-of-the-box MigrateProcessPlugin’s are not enough for your use case, you may want to consider creating a new custom MigrateProcessPlugin. Creating a new process plugin in Drupal 8 is a fairly simple task.
Let’s take a look at a simple MigrateProcessPlugin as an example to get us started.
In the DefaultValue MigrateProcessPlugin, we only have one method that is implemented, called “transform”. Transform takes in a value that is passed in by the user, checks to see if it is set, and sets that value for the field in the destination mapping.
How Do I Use a Process Plugin in My Migration?
Using a process plugin in your migration is relatively simple. If you have written a migration before, you have used these without even knowing it. Let’s take a look at the example below:
In this example, you will notice several plugins are utilized:
get: The “get” plugin is the default plugin. Any mapping that does not have a child element defining a plugin will utilize the “get” plugin
default_value: In this example, we are setting the user ID of a blog_post to user 1
When am I Going to Need a Custom Processor Plugin?
Before you venture down the path of creating custom processors, ask yourself the following questions:
Can any of the existing process plugins, or a combination of any of the existing process plugins, manipulate the data to the format I need?
Is the data transformation something that follows a pattern?
Is this processing/data manipulation something that will need to be used for more than one migration?
Is this a transformation that other users/migrations may benefit from?