Migration::getMigrationDependencies() has a new parameter and MigrationPluginManager::expandPluginIds() is made public

In Drupal\migrate\Plugin\Migration, the method getMigrationDependencies() has a new, optional parameter:

  public function getMigrationDependencies(bool $expand = FALSE)

The default behavior is compatible with the existing behavior. Calling the method without $expand = TRUE is now deprecated.

The migration dependencies are expanded when the plugin is created by Drupal\migrate\Plugin\MigrationPluginManager::createInstances(), so the $expand parameter does not make any difference unless the dependencies were updated using Drupal\migrate\Plugin\Migration::set('migration_dependencies', ...).

In Drupal\migrate\Plugin\MigrationPluginManager, the method expandPluginIds() is protected before Drupal 10.1.0. In Drupal 10.1.0, it is public and part of the interface Drupal\migrate\Plugin\MigrationPluginManagerInterface. If a class implements that interface without extending the core implementation, then it will have to provide this method.

Code samples

Before Drupal 10.1.0

    $migration_dependencies = $migration->getMigrationDependencies();

In Drupal 10.1.0 and later

    $migration_dependencies = $migration->getMigrationDependencies(TRUE);

Detailed differences

In Drupal\migrate\Plugin\Migration, the protected variable $migration_dependencies is an array with two keys: 'required' and 'optional'. Each of $migration_dependencies['required'] and $migration_dependencies['optional'] is an indexed array (list) of migration IDs.

Before Drupal 10.1.0

The variable $migration_dependencies can be set when a Migration object is created and changed using the Migration::set() method. It can be accessed using the Migration::getMigrationDependencies() method.

Sometimes, but not always, each of the two lists is "expanded" so that it includes all derivatives of any migration on the list. In detail,

• When a Migration object is created by Drupal\migrate\Plugin\MigrationPluginManager::createInstances(), each of the two lists is expanded.
• When a migration is altered by Migration::set('migration_dependencies', ...), the lists are not expanded. The calling function can set $migration_dependencies to any value.

In Migration::getMigrationDependencies(), there is a check that $migration_dependencies has the expected structure (array of arrays, with the expected keys). If not, the method throws an InvalidPluginDefinitionException.

In Drupal 10.1.0 and later

The check for valid structure is done when $migration_dependencies is set. The two lists are expanded when it is accessed. In detail,

• Both Migration:set() and the constructor check that $migration_dependencies is an array of arrays, with only the expected keys. If not, they trigger a deprecation message. In Drupal 11, they will throw an InvalidPluginDefinitionException.
• Calling Migration::getMigrationDependencies() without the optional parameter, or setting the parameter to FALSE, is deprecated. Calling Migration::getMigrationDependencies(TRUE) expands the two lists. It also checks that $migration_dependencies is an array of arrays, with only the expected keys, but this check will be removed in Drupal 11, when it will be redundant.

Currently, the lists may be expanded twice, if a Migration object is created by MigrationPluginManager::createInstances() and accessed with Migration::getMigrationDependencies(TRUE). When we disallow (not just deprecate) Migration::getMigrationDependencies(FALSE), we can update MigrationPluginManager::createInstances(), removing the code that expands the lists.