$migration_dependencies has inconsistent structure

Problem/Motivation

In Drupal\migrate\Plugin\Migration, the 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.

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

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

Proposed resolution

Short version: validate on set, expand on get.

In the following list, $migration_dependencies can be "set" in the constructor or using the set() method.

1. When the variable is set, ensure that it is an array of arrays, with the expected outer keys. Previously, this check was in getMigrationDependencies().
2. Add the optional, boolean parameter $expand to getMigrationDependencies(). The default value is FALSE, corresponding to the current behavior.
3. Deprecate getMigrationDependencies() without setting the new parameter to TRUE.
4. When $expand is set, "expand" the lists. Previously, the lists were expanded when $migration_dependencies is set by createInstances(), but not in set().
5. The method expandPluginIds() in the plugin manager is now public so that it can be called from the Migration class.

Changes to the tests

When expanding the lists of plugin IDs, getMigrationDependencies() now checks with the plugin manager that the IDs are valid. (The check is done in expandPluginIds().) Now, mock the plugin manager in the unit tests. For the functional tests, add a test module that provides several migration plugins.

Expect a deprecation when setting invalid dependencies, not when getting them.

The constructor of the TestMigration class, like the "real" constructor, ensures that $migration_dependencies has at least the expected keys. Previously, this was done in getMigrationDependencies().

Remaining tasks

User interface changes

None

API changes

In Drupal\migrate\Plugin\Migration, deprecate getMigrationDependencies(FALSE). Do NOT add the new parameter to the interface.

In Drupal\migrate\Plugin\MigrationPluginManager, make expandPluginIds() public and add it to the interface.

Release notes snippet

Calling Drupal\migrate\Plugin\Migration::getMigrationDependencies() without expanding the dependencies is deprecated. In most cases, use Drupal\migrate\Plugin\Migration::getMigrationDependencies(TRUE). For more information, see the change record Migration::getMigrationDependencies() is deprecated → .