Writing a process plugin

• Process plugins must be in namespace subdirectory Plugin\migrate\process under the namespace of the module that defines them. In other words, if your module is called 'mymodule', the process plugins must be located in mymodule/src/Plugin/migrate/process directory.
• Process plugins implement\Drupal\migrate\Plugin\MigrateProcessInterface and usually extend \Drupal\migrate\ProcessPluginBase.
• Process plugins are annotated with \Drupal\migrate\Annotation\MigrateProcessPlugin annotation.
• Migration process plugins are managed by the\Drupal\migrate\Plugin\MigratePluginManager class.

The core Migrate module provides process plugins for common operations (setting default values, mapping values, etc.). In addition to these, the contributed Migrate Plus provides useful process plugins as well. You can use these process plugins as examples when writing your own process plugins.

The contributed Migrate Sandbox module offers a UI for experimenting with process plugins and the process pipeline without running real migrations. This can be very helpful when developing custom process plugins since it offers an easy way to test them out.

Example

In your module module_example create TransformValue migrate plugin.

First, we will create plugin place holder in our module

mkdir -p src/Plugin/migrate/process
touch src/Plugin/migrate/process/TransformValue.php

In TransformValue.php let's define namespace

<?php

namespace Drupal\migrate_example\Plugin\migrate\process;

add TransformValue class

<?php

namespace Drupal\migrate_example\Plugin\migrate\process;

use Drupal\migrate\ProcessPluginBase;

class TransformValue extends ProcessPluginBase {
}

and add notation

<?php

namespace Drupal\migrate_example\Plugin\migrate\process;

use Drupal\migrate\ProcessPluginBase;

/**
 * Perform custom value transformations.
 *
 * @MigrateProcessPlugin(
 *   id = "transform_value"
 * )
 *
 * To do custom value transformations use the following:
 *
 * @code
 * field_text:
 *   plugin: transform_value
 *   source: text
 * @endcode
 *
 */
class TransformValue extends ProcessPluginBase {
}

Let's add transform() function to modify our value

<?php

namespace Drupal\migrate_example\Plugin\migrate\process;

use Drupal\migrate\MigrateExecutableInterface;
use Drupal\migrate\ProcessPluginBase;
use Drupal\migrate\Row;

/**
 * Perform custom value transformations.
 *
 * @MigrateProcessPlugin(
 *   id = "transform_value"
 * )
 *
 * To do custom value transformations use the following:
 *
 * @code
 * field_text:
 *   plugin: transform_value
 *   source: text
 * @endcode
 *
 */
class TransformValue extends ProcessPluginBase {
  /**
   * {@inheritdoc}
   */
  public function transform($value, MigrateExecutableInterface $migrate_executable, Row $row, $destination_property) {
    return strrev($value);
  }
}

Reacting to problems

We can use MigrateException to throw an error:

  public function transform($value, MigrateExecutableInterface $migrate_executable, Row $row, $destination_property) {
    // Throw an error if value and reverse value are the same.
    if ($value === strrev($value)) {
      throw new MigrateException('Reverse value is the same as value.');
    }

    return strrev($value);
  }

More specific exceptions allow control of how the migration behaves in response to the problem.

Throwing MigrateSkipRowException causes the source record currently being migrated to be skipped:

throw new MigrateSkipRowException('Skip this record.');

throw new MigrateSkipProcessException($message);

Configuration

Values in the migration's process definition can be accessed in the source plugin's configuration:

process:
  my_destination:
    plugin: my_source_plugin
    source: my_source
    cake: genoise

$cake_type = $this->configuration['cake'];