Налаштування модуля Migrate для міграції контенту в Drupal

Налаштування модуля Migrate для міграції контенту в Drupal

Drupal Migrate — вбудована ETL-система (Extract, Transform, Load) для імпорту даних з будь-яких джерел: старих версій Drupal, WordPress, CSV, XML, JSON, SQL-баз сторонніх систем. Конфігурується через YAML, розширюється плагінами.

Архітектура Migrate

Source — звідки читаємо дані (CSV, SQL, JSON, Drupal 7 DB) Process — трансформація: маппінг полів, конвертація, збагачення Destination — куди записуємо (Node, Term, User, File, Config)

Кожна міграція — окремий YAML-файл в config/install/migrate_plus.migration.*.yml.

Установка

composer require drupal/migrate_plus drupal/migrate_tools drupal/migrate_source_csv
drush en migrate migrate_plus migrate_tools -y

Міграція з CSV

Файл config/install/migrate_plus.migration.articles_from_csv.yml:

id: articles_from_csv
label: 'Статті з CSV'
migration_group: content_import

source:
  plugin: csv
  path: 'public://import/articles.csv'
  ids:
    - external_id
  header_row_count: 1
  column_names:
    - external_id
    - title
    - body
    - category
    - publish_date
    - image_url

process:
  title: title
  'body/value': body
  'body/format':
    plugin: default_value
    default_value: full_html
  created:
    plugin: format_date
    source: publish_date
    from_format: 'd.m.Y'
    to_format: 'U'
  status:
    plugin: default_value
    default_value: 1
  field_category:
    plugin: migration_lookup
    migration: categories_from_csv
    source: category
  field_image:
    plugin: download
    source:
      - image_url
      - '@filename'
    destination:
      plugin: 'public://images'
    rename: true

destination:
  plugin: 'entity:node'
  default_bundle: article

migration_dependencies:
  required:
    - categories_from_csv

Кастомний Source плагін

Для нестандартних джерел — кастомний плагін:

// src/Plugin/migrate/source/ExternalApiSource.php
namespace Drupal\mymodule\Plugin\migrate\source;

use Drupal\migrate\Plugin\migrate\source\SourcePluginBase;

/**
 * @MigrateSource(
 *   id = "external_api",
 *   source_module = "mymodule"
 * )
 */
class ExternalApiSource extends SourcePluginBase {
    public function getIds(): array {
        return ['id' => ['type' => 'integer']];
    }

    public function fields(): array {
        return [
            'id' => 'ID записи',
            'title' => 'Заголовок',
            'content' => 'Контент',
            'tags' => 'Теги (через кому)',
        ];
    }

    protected function initializeIterator(): \Iterator {
        $page = 0;
        do {
            $response = \Drupal::httpClient()->get(
                'https://api.external.com/posts?page=' . $page,
                ['headers' => ['Authorization' => 'Bearer ' . $this->configuration['api_key']]]
            );
            $data = json_decode($response->getBody(), true);
            $items = $data['items'];

            foreach ($items as $item) {
                yield $item;
            }

            $page++;
        } while (!empty($items) && $page < $data['total_pages']);
    }
}

Кастомний Process плагін

// src/Plugin/migrate/process/ExtractFirstImage.php
namespace Drupal\mymodule\Plugin\migrate\process;

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

/**
 * @MigrateProcessPlugin(id = "extract_first_image")
 */
class ExtractFirstImage extends ProcessPluginBase {
    public function transform($value, MigrateExecutableInterface $migrate_executable, Row $row, $destination_property): ?string {
        if (preg_match('/<img[^>]+src=["\']([^"\']+)["\']/', $value, $matches)) {
            return $matches[1];
        }
        return NULL;
    }
}

Запуск та моніторинг

# Список доступних міграцій
drush migrate:status

# Запуск конкретної міграції
drush migrate:import articles_from_csv

# Запуск всіх з групи
drush migrate:import --group=content_import

# З оновленням вже мігрованих записів
drush migrate:import articles_from_csv --update

# Откат міграції
drush migrate:rollback articles_from_csv

# Статус з прогресом
drush migrate:status --format=table

Обробка помилок

# Перегляд помилок міграції
drush migrate:messages articles_from_csv

# Пропуск записів з помилками та продовження
drush migrate:import articles_from_csv --continue-on-failure

Міграція медіафайлів

# Крок 1: міграція файлів
id: files_migration
source:
  plugin: csv
  path: 'public://import/files.csv'
process:
  filename:
    plugin: callback
    callable: basename
    source: file_url
  uri:
    plugin: download
    source:
      - file_url
      - '@filename'
    destination:
      plugin: 'public://migrated'
destination:
  plugin: 'entity:file'

# Крок 2: в міграції нод
field_image:
  plugin: migration_lookup
  migration: files_migration
  source: file_id

Incremental migration

Щоб при повторному запуску мігрувалися лише нові записи, джерело має відстежувати highwater mark:

source:
  plugin: csv
  path: 'public://import/articles.csv'
  ids:
    - external_id
  track_changes: true  # перемігрувати при зміні рядка

# Або через highwater mark (для дат)
highwaterProperty:
  name: updated_at
  alias: u

Строк виконання

Проста міграція з CSV (500–5000 записів) — 2–3 дні. Складна міграція з кількох джерел з кастомними плагінами та трансформаціями — 1–2 тижні.