This post is a copy of the MigMagLookup documentation on Drupal.org

MigMagLookup (migmag_lookup) is a Drupal core compatible migration lookup plugin which creates migration stubs only for existing source IDs, and which is able to identify which migration should create the stub entity.

Why might you need this plugin?

Drupal core’s migration_lookup migrate process plugin has some limitations in regard of content stubbing which cannot be worked around (imho):

  • Core’s MigrationLookup is not able to identify which migration contains a source record (row) with the matching IDs.
  • Because of this, it creates stubs entities with the wrong migrations – for example in the current migration. Or, if the current migration isn’t specified in the given lookup migrations configuration, then in the first lookup migration.
  • The plugin might create stubs which aren’t represented in the lookup migration(s) source (we call them “invalid stubs”). These stubs can’t ever be updated, because they don’t exist in the source data.
  • The plugin cannot create stubs from partial (not fully specified) source row IDs
  • You cannot pass destination property values to the migrate stub service, although it would be able to handle them appropriately.

However, MigMagLookup overcomes the limitations above:

  • MigMagLookup is able to identify which migrations may contain the row specified with the source plugin IDs.
  • Because of this, it is able to create stubs in the right migrations. If the row specified with its source IDs can be found in more lookup migrations, then it creates stubs for every matching source record…
  • …so it creates only valid stubs.
  • Stub creation only fails if the underlying migration plugin instance makes it to fail, because it invokes SourcePluginInterface::prepareRow()
  • From version 1.2.0, you can pass destination property values to the migrate stub service with the stub_default_values configuration. The configuration is an array of row properties, keyed by the stub migration’s destination properties. Row properties are fetched from the host migration’s row.
  • And the best one: it is able to create stubs based on not-fully-specified source row IDs. If you need the destination ID of a node (e.g. referenced from an entity reference field), you only have to use the information you have from the original field value: the ID of the source node. You don’t have to worry about how to get a revision ID (or a language code) if you are looking for only the migrated node’s ID.

If you specify the stub migration ID (which should store the stub) with the stub_id configuration key, then the original behavior is kept, so if you’re unlucky (or you want to do so), you might have invalid stubs.

If you want to create invalid stubs only when none of the provided lookup migrations contain the specified source record, you should specify the fallback stub migration’s plugin ID with the fallback_stub_id configuration key.

Some usage examples can be found on the documentation page.