Drupal Migrate API — Migrating Content from WordPress and Drupal

Source (CSV, database, XML, JSON)
        |
        v
Process (transform, map, filter, deduplicate)
        |
        v
Destination (Drupal entities, configuration)

# Core migrate modules
drush pm:enable migrate              # Core migration framework
drush pm:enable migrate_drupal       # Drupal-to-Drupal migration
drush pm:enable migrate_drupal_ui    # Web UI for Drupal migrations

# Contributed modules
composer require drupal/migrate_plus        # Additional source/process plugins
composer require drupal/migrate_tools       # Drush commands for migrations
composer require drupal/migrate_source_csv   # CSV source plugin
composer require drupal/wordpress_migrate   # WordPress import

# migrations/migrate_plus.migration.import_articles.yml
id: import_articles
label: 'Import articles from WordPress'
migration_group: wordpress
migration_tags:
  - wordpress
  - content

source:
  plugin: wordpress_post
  constants:
    uid: 1
    status: 1

process:
  type:
    plugin: default_value
    default_value: article
  title: title
  body/value: body
  body/format:
    plugin: default_value
    default_value: basic_html
  field_tags:
    plugin: migration_lookup
    migration: import_tags
    source: tags
  uid: constants/uid
  status: constants/status
  created: post_date
  changed: post_modified

destination:
  plugin: entity:node

dependencies:
  enforced:
    module:
      - migrate_plus
      - wordpress_migrate

# CSV source
source:
  plugin: csv
  path: /var/www/migrations/users.csv
  header_row_count: 1
  keys:
    - id
  fields:
    id: 'User ID'
    name: 'Username'
    email: 'Email address'

# Database source
source:
  plugin: d7_node
  node_type: article

# Embedded source (hardcoded data)
source:
  plugin: embedded_data
  data_rows:
    -
      id: 1
      name: 'Static Page'
    -
      id: 2
      name: 'About Us'
  ids:
    id:
      type: integer

# URL/JSON source
source:
  plugin: url
  data_fetcher_plugin: http
  data_parser_plugin: json
  urls: 'https://api.example.com/posts'
  item_selector: /posts
  fields:
    -
      name: title
      label: Title
      selector: title
    -
      name: body
      label: Body
      selector: content
  ids:
    title:
      type: string

process:
  # Direct mapping (source to destination as-is)
  title: source_title

  # Default value if source is empty
  type:
    plugin: default_value
    default_value: article

  # Concat multiple fields
  field_full_name:
    plugin: concat
    source:
      - first_name
      - last_name
    delimiter: ' '

  # Skip empty values
  field_summary:
    plugin: skip_on_empty
    method: process
    source: excerpt

  # Callback (PHP function)
  created:
    plugin: callback
    callable: strtotime
    source: post_date

  # Explode a string into an array
  field_tags:
    plugin: explode
    source: tags_string
    delimiter: ','

  # Extract a value from an array
  field_coordinates:
    plugin: extract
    source: location
    index:
      - lat
      - lng

  # Reference another migration
  field_author:
    plugin: migration_lookup
    migration: import_users
    source: author_id

  # Deduplicate entities
  field_category:
    plugin: dedupe_entity
    entity_type: taxonomy_term
    field: name
    source: category_name

  # Static map (replace values)
  field_region:
    plugin: static_map
    source: region_code
    map:
      NE: 'Northeast'
      SE: 'Southeast'
      MW: 'Midwest'
      W: 'West'
    bypass: true

# Create nodes
destination:
  plugin: entity:node

# Create users
destination:
  plugin: entity:user

# Create taxonomy terms
destination:
  plugin: entity:taxonomy_term

# Create configuration
destination:
  plugin: config:language

# Entity:node with bundle specified in process
process:
  type:
    plugin: default_value
    default_value: article

# List all migrations
drush migrate:status

# Show status of a specific migration
drush migrate:status import_articles

# Run a specific migration
drush migrate:import import_articles

# Run all migrations in a group
drush migrate:import wordpress

# Import with a limit (for testing)
drush migrate:import import_articles --limit=10

# Run migrations in parallel
drush migrate:import import_articles import_users --execute-dependencies

# Rollback a migration (removes imported data)
drush migrate:rollback import_articles

# Rollback all migrations in a group
drush migrate:rollback wordpress

# Show messages from a migration
drush migrate:messages import_articles

# Reset a stalled migration
drush migrate:reset import_articles

# migrations/migrate_plus.migration.import_tags.yml
id: import_tags
label: 'Import WordPress categories as taxonomy terms'
migration_group: wordpress
source:
  plugin: wordpress_category
destination:
  plugin: entity:taxonomy_term
  default_bundle: tags

# migrations/migrate_plus.migration.import_articles.yml
id: import_articles
label: 'Import WordPress posts as articles'
migration_group: wordpress
source:
  plugin: wordpress_post
process:
  field_tags:
    plugin: migration_lookup
    migration: import_tags  # This migration must run first
    source: categories
destination:
  plugin: entity:node
  default_bundle: article

# Dependencies ensure correct order
# 1. import_tags runs first (creates taxonomy terms)
# 2. import_articles runs second (references the terms)

<?php
namespace Drupal\my_module\Plugin\migrate\process;

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

/**
 * Generate a URL-safe slug from a string.
 *
 * @MigrateProcessPlugin(
 *   id = "my_slugify"
 * )
 */
class Slugify extends ProcessPluginBase {

  public function transform($value, MigrateExecutableInterface $migrate_executable, Row $row, $destination_property) {
    if (empty($value)) {
      throw new MigrateSkipProcessException();
    }

    // Convert to lowercase, replace spaces with hyphens,
    // remove special characters
    $slug = mb_strtolower($value);
    $slug = preg_replace('/[^a-z0-9-]+/', '-', $slug);
    $slug = trim($slug, '-');

    return $slug;
  }
}

# Using the custom plugin
process:
  field_slug:
    plugin: my_slugify
    source: title

# WordPress post type to Drupal content type
process:
  type:
    plugin: static_map
    source: post_type
    map:
      post: article
      page: page
      news: news
    bypass: true  # Skip if no match

# Combine first/last name into full name
process:
  field_full_name:
    plugin: concat
    source:
      - first_name
      - last_name
    delimiter: ' '

# Combine address fields
process:
  field_address:
    plugin: concat
    source:
      - street
      - city
      - zip
    delimiter: ', '

# WordPress stores dates differently from Drupal
process:
  created:
    plugin: callback
    callable: strtotime
    source: post_date_gmt