At Liip, we started several Drupal 8 projects a while ago, when the media module was not yet part of Drupal Core. Back then, we decided, to use normal file / image fields for media uploads in our content types.

A few months later, our clients prefered a media library using Drupal Media in Core and an Entity Browser to search and find their media assets.

The question is: Is it possible to convert my old-fashioned image fields to new shiny media entities?
The answer is: Yes, there is a way out of your misery!

We created a module called: "Migrate File Entities to Media Entities".
https://www.drupal.org/project/migrate_file_to_media

The module allows you, to migrate Drupal 8.0 file entities to Drupal 8.5 media entities, using the migrate module.

The main features of the module?

  • It provides a drush command that automatically detects all file / image fields and creates the corresponding media reference field.
  • Before migrating the files to media entities, a binary hash of all images is calculated, and duplicate files are recognized. If the same file was uploaded multiple times on different nodes, only one media entity will be created.
  • Migration of translated file / image fields is supported. Having different images per language will create a translated media entity with the corresponding image.
  • Using migrate to file module allows drush processing, rollback and track changes.

How to migrate images to media entities

Prepare target media fields

  • Prepare the media fields based on the existing file fields using the following drush command:
    drush migrate:file-media-fields <entity_type> <bundle> <source_field_type> <target_media_bundle>

    Example

    drush migrate:file-media-fields node article image image

    For all file fields the corresponding media entity reference field will be automatically created suffixed by {field_name}_media.

Prepare duplicate file / image detection

In order to detect duplicate files / images, run the following drush command to calculate a binary hash for all files. The data will be saved to the table "migrate_file_to_media_mapping". You need to run this drush command to be able to import media entities.

drush migrate:duplicate-file-detection

Create a custom migration per content type based on the migrate_file_to_media_example module

  • Create a custom module
  • Create your own migration templates based on the examples in migrate_file_to_media_example.

The module provided a custom migrate source plugin called "media_entity_generator".

id: article_images
label: Article Image to Media Migration
migration_group: media
source:
  plugin: media_entity_generator
  entity_type: node
  bundle: article
  langcode: 'en'

  # provide a list of all field names you want to migrate
  field_names:
  - field_image
  - field_image2

destination:
  plugin: entity:media

You need to create a migration per entity bundle and provide a list of all field names, you want to migrate. The source plugin will query the database and find all files / images linked with these fields.

Step-by-step instruction how to migrate your own files / images.

Step 1: Create media entities.

File migrate_file_to_media_example/config/install/migrate_plus.migration.article_images.yml

This is the starting point. This migration creates a unique media entity from all files / images referenced by fields in the configuration field_names of the source plugin.
In the example, we have two image fields called: "field_image" and "field_image2".

Important:
The drush command to calculate the binary hash needs to be run before you can use the media_entity_generator source plugin.

Using rokka.io on Step 1:

File migrate_file_to_media_example/config/install/migrate_plus.migration.article_images_rokka.yml

This is an example migration, how to move all images to the rokka.io image content delivery network. You need to install the
drupal rokka module.

Step 2: Create media entity translations.

File migrate_file_to_media_example/config/install/migrate_plus.migration.article_images_de.yml

This migration adds a translation to existing media entities if a translated file / image field is found.

Step 3: Link media entities with media reference field on target bundle.

File migrate_file_to_media_example/config/install/migrate_plus.migration.article_media.yml

This migration links the newly created media entities with entity reference field on the target bundle.

Step 4: Check the migration status.

drush migrate:status

Step 5: Run the migration.

drush migrate:import <migration_name>