1. interface
  2. Drupal
  3. \
  4. migrate
  5. \
  6. Plugin
  7. \
  8. MigrateIdMapInterface

MigrateIdMapInterface

interface MigrateIdMapInterface implements Iterator, PluginInspectionInterface (View source)

Defines an interface for migrate ID mappings.

Migrate ID mappings maintain a relation between source ID and destination ID for audit and rollback purposes. The keys used in the migrate_map table are of the form sourceidN and destidN for the source and destination values respectively.

The mappings are stored in a migrate_map table with properties:

  • source_ids_hash: A hash of the source IDs.
  • sourceidN: Any number of source IDs defined by a source plugin, where N starts at 1, for example, sourceid1, sourceid2 ... sourceidN.
  • destidN: Any number of destination IDs defined by a destination plugin, where N starts at 1, for example, destid1, destid2 ... destidN.
  • source_row_status: Indicates current status of the source row, valid values are self::STATUS_IMPORTED, self::STATUS_NEEDS_UPDATE, self::STATUS_IGNORED or self::STATUS_FAILED.
  • rollback_action: Flag indicating what to do for this item on rollback. This property is set in destination plugins. Valid values are self::ROLLBACK_DELETE and self::ROLLBACK_PRESERVE.
  • last_imported: UNIX timestamp of the last time the row was imported.
  • hash: A hash of the source row data that is used to detect changes in the source data.

Constants

STATUS_IMPORTED

Indicates that the import of the row was successful.
STATUS_NEEDS_UPDATE

Indicates that the row needs to be updated.
STATUS_IGNORED

Indicates that the import of the row was ignored.
STATUS_FAILED

Indicates that the import of the row failed.
ROLLBACK_DELETE

Indicates that the data for the row is to be deleted.
ROLLBACK_PRESERVE

Indicates that the data for the row is to be preserved.

Rows that refer to entities that already exist on the destination and are being updated are preserved.

Methods

string
getPluginId()

Gets the plugin_id of the plugin instance.

from  PluginInspectionInterface
array
getPluginDefinition()

Gets the definition of the plugin implementation.

from  PluginInspectionInterface
saveIdMapping(Row $row, array $destination_id_values, int $status = self::STATUS_IMPORTED, int $rollback_action = self::ROLLBACK_DELETE)

Saves a mapping from the source identifiers to the destination identifiers.

saveMessage(array $source_id_values, string $message, int $level = MigrationInterface::MESSAGE_ERROR)

Saves a message related to a source record in the migration message table.

Traversable
getMessages(array $source_id_values = [], int $level = NULL)

Retrieves a traversable object of messages related to source records.

Iterator
getMessageIterator(array $source_id_values = [], int $level = NULL) deprecated

Retrieves an iterator over messages relate to source records.

prepareUpdate()

Prepares to run a full update.

int
processedCount()

Returns the number of processed items in the map.

int
importedCount()

Returns the number of imported items in the map.

int
updateCount()

Returns a count of items which are marked as needing update.

int
errorCount()

Returns the number of items that failed to import.

int
messageCount()

Returns the number of messages saved.

delete(array $source_id_values, bool $messages_only = FALSE)

Deletes the map and message entries for a given source record.

deleteDestination(array $destination_id_values)

Deletes the map and message table entries for a given destination row.

clearMessages()

Clears all messages from the map.

array
getRowBySource(array $source_id_values)

Retrieves a row from the map table based on source identifier values.

array
getRowByDestination(array $destination_id_values)

Retrieves a row by the destination identifiers.

array
getRowsNeedingUpdate(int $count)

Retrieves an array of map rows marked as needing update.

array
lookupSourceId(array $destination_id_values)

Looks up the source identifier.

array
lookupDestinationId(array $source_id_values) deprecated

Looks up the destination identifier corresponding to a source key.

array
lookupDestinationIds(array $source_id_values)

Looks up the destination identifiers corresponding to a source key.

array
currentDestination()

Looks up the destination identifier currently being iterated.

array
currentSource()

Looks up the source identifier(s) currently being iterated.

destroy()

Removes any persistent storage used by this map.

getQualifiedMapTableName()

Gets the qualified map table.

setMessage(MigrateMessageInterface $message)

Sets the migrate message service.

setUpdate(array $source_id_values)

Sets a specified record to be updated, if it exists.

Details

in PluginInspectionInterface at line 21
string getPluginId()

Gets the plugin_id of the plugin instance.

Return Value

string

The plugin_id of the plugin instance.

in PluginInspectionInterface at line 30
array getPluginDefinition()

Gets the definition of the plugin implementation.

Return Value

array

The plugin definition, as returned by the discovery object used by the plugin manager.

at line 87
saveIdMapping(Row $row, array $destination_id_values, int $status = self::STATUS_IMPORTED, int $rollback_action = self::ROLLBACK_DELETE)

Saves a mapping from the source identifiers to the destination identifiers.

Called upon import of one row, we record a mapping from the source ID to the destination ID. Also may be called, setting the third parameter to NEEDS_UPDATE, to signal an existing record should be re-migrated.

Parameters

Row $row

The raw source data. We use the ID map derived from the source object to get the source identifier values.
array $destination_id_values

An array of destination identifier values.
int $status

(optional) Status of the source row in the map. Defaults to self::STATUS_IMPORTED.
int $rollback_action

(optional) How to handle the destination object on rollback. Defaults to self::ROLLBACK_DELETE.

at line 100
saveMessage(array $source_id_values, string $message, int $level = MigrationInterface::MESSAGE_ERROR)

Saves a message related to a source record in the migration message table.

Parameters

array $source_id_values

The source identifier keyed values of the record, e.g. ['nid' => 5].
string $message

The message to record.
int $level

(optional) The message severity. Defaults to MigrationInterface::MESSAGE_ERROR.

at line 121
Traversable getMessages(array $source_id_values = [], int $level = NULL)

Retrieves a traversable object of messages related to source records.

Parameters

array $source_id_values

(optional) The source identifier keyed values of the record, e.g. ['nid' => 5]. If empty (the default), all messages are retrieved.
int $level

(optional) Message severity. If NULL (the default), retrieve messages of all severities.

Return Value

Traversable

Retrieves a traversable object of message objects of unspecified class. Each object has the following public properties:

  • source_row_hash: the hash of the entire serialized source row data.
  • message: the text of the message.
  • level: one of MigrationInterface::MESSAGE_ERROR, MigrationInterface::MESSAGE_WARNING, MigrationInterface::MESSAGE_NOTICE, MigrationInterface::MESSAGE_INFORMATIONAL.

at line 141
Iterator getMessageIterator(array $source_id_values = [], int $level = NULL) deprecated

deprecated in drupal:8.8.0 and is removed from drupal:9.0.0. Use \Drupal\migrate\Plugin\MigrateIdMapInterface::getMessages() instead.

Retrieves an iterator over messages relate to source records.

Parameters

array $source_id_values

(optional) The source identifier keyed values of the record, e.g. ['nid' => 5]. If empty (the default), all messages are retrieved.
int $level

(optional) Message severity. If NULL (the default), retrieve messages of all severities.

Return Value

Iterator

Retrieves an iterator over the message rows.

See also

https://www.drupal.org/node/3060969

at line 151
prepareUpdate()

Prepares to run a full update.

Prepares this migration to run as an update - that is, in addition to unmigrated content (source records not in the map table) being imported, previously-migrated content will also be updated in place by marking all previously-imported content as ready to be re-imported.

at line 159
int processedCount()

Returns the number of processed items in the map.

Return Value

int

The count of records in the map table.

at line 167
int importedCount()

Returns the number of imported items in the map.

Return Value

int

The number of imported items.

at line 175
int updateCount()

Returns a count of items which are marked as needing update.

Return Value

int

The number of items which need updating.

at line 183
int errorCount()

Returns the number of items that failed to import.

Return Value

int

The number of items that errored out.

at line 191
int messageCount()

Returns the number of messages saved.

Return Value

int

The number of messages.

at line 201
delete(array $source_id_values, bool $messages_only = FALSE)

Deletes the map and message entries for a given source record.

Parameters

array $source_id_values

The source identifier keyed values of the record, e.g. ['nid' => 5].
bool $messages_only

(optional) TRUE to only delete the migrate messages. Defaults to FALSE.

at line 209
deleteDestination(array $destination_id_values)

Deletes the map and message table entries for a given destination row.

Parameters

array $destination_id_values

The destination identifier key value pairs we should do the deletes for.

at line 214
clearMessages()

Clears all messages from the map.

at line 225
array getRowBySource(array $source_id_values)

Retrieves a row from the map table based on source identifier values.

Parameters

array $source_id_values

The source identifier keyed values of the record, e.g. ['nid' => 5].

Return Value

array

The raw row data as an associative array.

at line 236
array getRowByDestination(array $destination_id_values)

Retrieves a row by the destination identifiers.

Parameters

array $destination_id_values

The destination identifier keyed values of the record, e.g. ['nid' => 5].

Return Value

array

The row(s) of data.

at line 247
array getRowsNeedingUpdate(int $count)

Retrieves an array of map rows marked as needing update.

Parameters

int $count

The maximum number of rows to return.

Return Value

array

Array of map row objects that need updating.

at line 262
array lookupSourceId(array $destination_id_values)

Looks up the source identifier.

Given a (possibly multi-field) destination identifier value, return the (possibly multi-field) source identifier value mapped to it.

Parameters

array $destination_id_values

The destination identifier keyed values of the record, e.g. ['nid' => 5].

Return Value

array

The source identifier keyed values of the record, e.g. ['nid' => 5], or an empty array on failure.

at line 281
array lookupDestinationId(array $source_id_values) deprecated

deprecated in drupal:8.1.0 and is removed from drupal:9.0.0. Use lookupDestinationIds() instead.

Looks up the destination identifier corresponding to a source key.

Given a (possibly multi-field) source identifier value, return the (possibly multi-field) destination identifier value it is mapped to.

Parameters

array $source_id_values

The source identifier keyed values of the record, e.g. ['nid' => 5].

Return Value

array

The destination identifier values of the record, or empty on failure.

See also

https://www.drupal.org/node/2725809

at line 300
array lookupDestinationIds(array $source_id_values)

Looks up the destination identifiers corresponding to a source key.

This can look up a subset of source keys if only some are provided, and will return all destination keys that match.

Parameters

array $source_id_values

The source identifier keyed values of the records, e.g. ['nid' => 5]. If unkeyed, the first count($source_id_values) keys will be assumed.

Return Value

array

An array of arrays of destination identifier values.

Exceptions

MigrateException

at line 308
array currentDestination()

Looks up the destination identifier currently being iterated.

Return Value

array

The destination identifier values of the record, or NULL on failure.

at line 316
array currentSource()

Looks up the source identifier(s) currently being iterated.

Return Value

array

The source identifier values of the record, or NULL on failure.

at line 323
destroy()

Removes any persistent storage used by this map.

For example, remove the map and message tables.

at line 330
getQualifiedMapTableName()

Gets the qualified map table.

Remove this as this is SQL only and so doesn't belong to the interface.

at line 338
setMessage(MigrateMessageInterface $message)

Sets the migrate message service.

Parameters

MigrateMessageInterface $message

The migrate message service.

at line 346
setUpdate(array $source_id_values)

Sets a specified record to be updated, if it exists.

Parameters

array $source_id_values

The source identifier values of the record.