[Closed (won't fix)]

In Drupal 8.6 and before the migration_lookup plugin had very inconsistent return values. If the destination plugin of the migration only had a single id, the plugin would return the single id as a scalar. If there were more than one id associated with the destination plugin, and the lookup succeeded, then the ids would be returned in an indexed array ordered in the same order the keys were defined in the destination plugins 'getIds' method. If the lookup failed, and a stub entity was created, then the ids would be returned in an associative array keyed by the names of the id fields, as defined by the destination plugin.

The purpose of this change record is to create consistency in the return format of the migration_lookup plugin. Beginning with Drupal 8.7, a new boolean configuration option is defined, 'return_associative'. When set to true, the plugin will return the destination ids in an associative array, regardless of whether there is one or multiple keys, or whether the lookup succeeded or resulted in a stub creation. Beginning in Drupal 8.7 it is deprecated to omit this key or set it to anything other than true if the migration lookup would otherwise return an indexed array or scalar. Setting the value to false is not supported and will trigger an error.

Beginning in Drupal 9.0, this behavior will be the default functionality of the plugin and the configuration key will be ignored if present.

Before:

process:
  roles:
    plugin: migration_lookup
    migration: d7_user_role
    source: roles

Beginning in Drupal 8.7:

process:
  roles:
    -
      plugin: migration_lookup
      migration: d7_user_role
      source: roles
      return_associative: true
    -
      plugin: extract
      index:
        - id

Beginning in Drupal 9.0

process:
  roles:
    -
      plugin: migration_lookup
      migration: d7_user_role
      source: roles
    -
      plugin: extract
      index:
        - id