A new 'weight' field has been added to the MigrateField plugin annotation. MigrateFieldPluginManager will now sort plugins by weight before determining which one to return from ::getPluginIdFromFieldType().
Prior to this change, MigrateFieldPluginManager returned the first MigrateField plugin it found in the plugin definition list that applied to the requested field type and core version. This made it difficult or impossible to deprecate and replace field plugins while ensuring the new plugin would be used. It was also difficult or impossible for contrib to override the core field plugins for a field type.
With this change, the new 'weight' annotation field will be used to sort plugins prior to determining which plugin to use for a given field and core version. All non-deprecated core MigrateField plugins will use the default weight of 0. Deprecated core plugins will be weighted to 9999999 to ensure their replacements are used instead. Contrib may override a core plugin for a field type by adding the field type to the type_map array and setting the weight of the custom plugin to a negative number.
Before:
Given the below situation, the deprecated 'date' plugin would still be used, despite it being deprecated if it appeared first in the discovery list.
/**
* @MigrateField(
* id = "date",
* type_map = {
* "date" = "datetime",
* "datestamp" = "timestamp",
* "datetime" = "datetime",
* },
* core = {6},
* source_module = "date",
* destination_module = "datetime"
* )
*
* @deprecated in Drupal 8.4.x, to be removed before Drupal 9.0.x. Use
* \Drupal\datetime\Plugin\migrate\field\DateField instead.
*/
---
/**
* @MigrateField(
* id = "datetime",
* type_map = {
* "date" = "datetime",
* "datestamp" = "timestamp",
* "datetime" = "datetime",
* },
* core = {6,7},
* source_module = "date",
* destination_module = "datetime"
* )
*/
After:
The deprecated plugin can be weighted so that it is no longer used by default.
/**
* @MigrateField(
* id = "date",
* type_map = {
* "date" = "datetime",
* "datestamp" = "timestamp",
* "datetime" = "datetime",
* },
* core = {6},
* source_module = "date",
* destination_module = "datetime",
* weight = 9999999
* )
*
* @deprecated in Drupal 8.4.x, to be removed before Drupal 9.0.x. Use
* \Drupal\datetime\Plugin\migrate\field\DateField instead.
*/
---
/**
* @MigrateField(
* id = "datetime",
* type_map = {
* "date" = "datetime",
* "datestamp" = "timestamp",
* "datetime" = "datetime",
* },
* core = {6,7},
* source_module = "date",
* destination_module = "datetime"
* )
*/
