Drupal 8: Migrate from Drupal 6 with a custom process plugin

by Jim Frederick on

When migrating a site from Drupal 6 to Drupal 8, we had to write some very basic Plugins. Since plugins and some of their related pieces are new to Drupal 8, here is a walk-through of how we put it together:

Use case

In Drupal 6, the contrib Date module provided a date field that had both a start and end date. So, the beginning of Crazy Dan’s Hot Air Balloon Weekend Extravaganza might be July 12, with an end date of July 14. However, the datetime module in Drupal 8 core does not allow for end dates. So, we had to use two distinct date fields on the new site: one for the start date, and one for the end date.

Fields in D6:
1.  field_date: has start and end date

Fields in D8:
1.  field_date_start: holds the start date
2.  field_date_end: holds the end date

Migration overview

A little background information before we move along: migrations use a series of sequential plugins to move your data: builder, source, process, and finally, destination.

Since we are moving data from one field into two, we had to write a custom migration process plugin. Process plugins are where you can manipulate the data that is being migrated.

Writing the process plugin (general structure)

The file system in Drupal 8 is organized very differently than in Drupal 7. Within your custom module, plugins will always go in [yourmoduledir]/src/Plugin. In this case, our migrate process plugin goes in [yourmodulename]/src/Plugin/migrate/process/CustomDate.php.

Here is the entire file, which we’ll break down below.

 

<?php
/**
 * @file
 * Contains \Drupal\custom_migrate\Plugin\migrate\process\CustomDate.
 */

Standard code comments.

namespace Drupal\custom_migrate\Plugin\migrate\process;
use Drupal\migrate\ProcessPluginBase;
use Drupal\migrate\MigrateExecutableInterface;
use Drupal\migrate\Row;

Instead of using functions like include(); or include_once(); to add various PHP files, now we "include" them by referencing their namespaces. Or rather Drupal knows which files to autoload based on the namespace.  This way, if a class is ever moved to a new directory, we won't have to change code elsewhere, as long as the namespace stays the same. We will allow our code to be used the same way, by defining its namespace.

/**
* This plugin converts Drupal 6 Date fields to Drupal 8.
*
* @MigrateProcessPlugin(
*   id = "custom_date"
* )
*/

This class comment includes an annotation. When the Migrate module is looking for all available migration plugins, it scans the file system, looking for annotations like this. By including it, you let the migration module discover your migrate process plugin with the unique id 'custom_date'.

Our new class will inherit from the ProcessPluginBase class, which is provided by the Migrate module in core. Let's step back and look at that class. This is it's definition:

abstract class ProcessPluginBase extends PluginBase implements MigrateProcessInterface { ... }

Since this is an abstract class, it can never be instantiated by itself. So, you never call new ProcessPluginBase(). Instead we create our own class that inherits it, by using the keyword extends:

class CustomDate extends ProcessPluginBase { ... }

The ProcessPluginBase class has two public methods, which will be available in child classes, unless the child class overrides the methods. In our case, we will override transform(), but leave multiple() alone, inheriting the default implementation of that one.

(A note about abstract classes: If there were any methods defined as abstract, our child class would be required to implement them. But we don't have to worry about that in this case!) To override transform() and create our own logic, we just copy the method signature from the parent class:

public function transform($value, MigrateExecutableInterface $migrate_executable, Row $row, $destination_property)

Writing the process plugin (our specific data manipulation)

In order to write custom code, let's review our use case of dates again. Since this is our mapping:

OLD D6 field_date (from component) -> NEW D8 field_date_from
OLD D6 field_date (to component) -> NEW D8 field_date_to

We will migrate field_date twice per node. The first time, we will pull the from date. The second time, we will pull the to date. Since our process plugin needs to be aware of which piece we're looking for in that particular run, we will allow the process plugin to have additional configuration. In our case, we will call this configuration date_part, which can be either from or to, and defaults to from:

$date_part = isset($this->configuration['date_part']) ? $this->configuration['date_part'] : 'from';

Depending on which date part we're looking for, we'll grab the appropriate date from the D6 source field, which is stored in the array $value.

$value = ($date_part == 'from') ? $value['value'] : $value['value2'];

And we'll return the string, which will populate the new field:

return $value;

That's it for writing our process plugin! Now we just have to use it.

Using the process plugin

In our migration definition, we need to call this plugin and feed it the correct information. So back in [yourmodulename]/config/install/migrate.migration.d6_node.yml, we map the new and old fields:

field_date_start:
  plugin: custom_date
  source: field_date
  date_part: from
field_date_end:
  plugin: custom_date
  source: field_date
  date_part: to

Which reads like this: For field_date_start on the new site, pass the old field_date to the custom_date process plugin, with the configuration date_part = 'from'. Do this all again for field_date_end, but with the configuration date_part = 'to'. Both of our D8 fields get filled out, each getting its data from a single field on the old D6 site.

migration

Time to fly! (Image courtesy of Wikimedia)

Feedback

Hopefully this helps. If you have any corrections, improvements, questions, or links to how you use plugins, leave them in the comments!