Migration helpers

This module is meant as an aid for development and deployment, and includes bits of help for migrate and bits that can be used directly in deploy hooks to rearrange content on your modern Drupal site without migration.

It currently does not use Drupal's Migrate API.

Features

So far its functions include migration_helpers_entity_query() and two that make heavy use of it this helper, migration_helpers_move_terms() and

migration_helpers_text_list_to_boolean()<code>.

And the class <code>MigrationHelperFieldTransformations

which has a method fieldToMediaEntity() which can move data from file/image fields into media reference fields, including handling translated media.

Post-Installation

This module does nothing at all unless you call its functions from your own code.

Here are examples of the sorts of thing you can do in deploy hooks.

Note in every case it is expected that you have created the destination entities and fields already.

Move file fields to media reference fields

function example_deploy_move_files_to_media() {
  /** @var \Drupal\migration_helpers\MigrationHelperFieldTransformations $field_transformations_service */
  $field_transformations_service = \Drupal::service('migration_helpers.field_transformations');
  $field_transformations_service->fieldToMediaEntity(
    entity_type: 'node',
    source_field_names: 'field_attachments',
    media_field_name: 'field_media_attachments',
    source_entity_bundles: ['page', 'forms_resources'],
    media_entity_bundle: 'document',
    media_target_field: 'field_media_document'
  );
}

Modify taxonomy terms and move from old term reference field to a different vocabulary

/**
 * Rename and move select terms to new vocabulary and term reference field.
 *
 * Here we move select terms from the deprecated 'Design sector' vocabulary
 * (note the source vocabulary does not get specified, as we are only moving
 * terms that are referenced by the chosen entity type (defaults to node) and
 * bundle) from the design_type field into the new Focus Areas vocabulary which
 * is referenced by `field_focus`.  We rename three of the terms and explicitly
 * discard four others.  Any we do not put in the mapping will be brought in
 * with their current name.  This does not currently copy over term description
 * or anything else, only term label.  Perhaps it could be reworked to be both
 * more generic and more powerful with an entity clone.
 */
function example_deploy_design_sector_to_focus_area() {
  $mapping = [
    'Memorial' => 'Public Memory',
    'Housing' => 'Social Cohesion',
    'Health' => 'Health Equity',
    'Education' => FALSE,
    'Equity' => FALSE,
    'Office Space' => FALSE,
    'Other' => FALSE,
  ];
  migration_helpers_move_terms(
    destination_vocabulary: 'focus_area',
    source_field: 'field_design_type',
    destination_field: 'field_focus',
    bundle: 'work',
    mapping: $mapping,
  );
}

Additional Requirements

Requires PHP 8 or above.

Recommended modules/libraries

Drupal core's Migrate module is highly recommended.

Similar projects

• Field Type Converter has a very similar purpose and we learned about it recently, so we have not compared and contrasted with Migration helpers yet.

Anyone else have a collection of utility functions used in migrating content, either within the migration ecosystem or other random helpful functions?

Supporting this Module

You can support Agaric's overall contributions to Drupal and a bit beyond by supporting Drutopia at opencollective.com/drutopia. Thanks!!

Community Documentation

Docs contributions very welcome!