3 namespace Drupal\migrate\Plugin;
5 use Drupal\Component\Plugin\PluginInspectionInterface;
6 use Drupal\migrate\MigrateMessageInterface;
7 use Drupal\migrate\Row;
10 * Defines an interface for migrate ID mappings.
12 * Migrate ID mappings maintain a relation between source ID and destination ID
13 * for audit and rollback purposes.
15 interface MigrateIdMapInterface extends \Iterator, PluginInspectionInterface {
18 * Codes reflecting the current status of a map row.
20 const STATUS_IMPORTED = 0;
21 const STATUS_NEEDS_UPDATE = 1;
22 const STATUS_IGNORED = 2;
23 const STATUS_FAILED = 3;
26 * Codes reflecting how to handle the destination item on rollback.
28 const ROLLBACK_DELETE = 0;
29 const ROLLBACK_PRESERVE = 1;
32 * Saves a mapping from the source identifiers to the destination identifiers.
34 * Called upon import of one row, we record a mapping from the source ID to
35 * the destination ID. Also may be called, setting the third parameter to
36 * NEEDS_UPDATE, to signal an existing record should be re-migrated.
38 * @param \Drupal\migrate\Row $row
39 * The raw source data. We use the ID map derived from the source object
40 * to get the source identifier values.
41 * @param array $destination_id_values
42 * An array of destination identifier values.
44 * (optional) Status of the source row in the map. Defaults to
45 * self::STATUS_IMPORTED.
46 * @param int $rollback_action
47 * (optional) How to handle the destination object on rollback. Defaults to
48 * self::ROLLBACK_DELETE.
50 public function saveIdMapping(Row $row, array $destination_id_values, $status = self::STATUS_IMPORTED, $rollback_action = self::ROLLBACK_DELETE);
53 * Saves a message related to a source record in the migration message table.
55 * @param array $source_id_values
56 * The source identifier keyed values of the record, e.g. ['nid' => 5].
57 * @param string $message
58 * The message to record.
60 * (optional) The message severity. Defaults to
61 * MigrationInterface::MESSAGE_ERROR.
63 public function saveMessage(array $source_id_values, $message, $level = MigrationInterface::MESSAGE_ERROR);
66 * Retrieves an iterator over messages relate to source records.
68 * @param array $source_id_values
69 * (optional) The source identifier keyed values of the record, e.g.
70 * ['nid' => 5]. If empty (the default), all messages are retrieved.
72 * (optional) Message severity. If NULL (the default), retrieve messages of
76 * Retrieves an iterator over the message rows.
78 public function getMessageIterator(array $source_id_values = [], $level = NULL);
81 * Prepares to run a full update.
83 * Prepares this migration to run as an update - that is, in addition to
84 * unmigrated content (source records not in the map table) being imported,
85 * previously-migrated content will also be updated in place by marking all
86 * previously-imported content as ready to be re-imported.
88 public function prepareUpdate();
91 * Returns the number of processed items in the map.
94 * The count of records in the map table.
96 public function processedCount();
99 * Returns the number of imported items in the map.
102 * The number of imported items.
104 public function importedCount();
108 * Returns a count of items which are marked as needing update.
111 * The number of items which need updating.
113 public function updateCount();
116 * Returns the number of items that failed to import.
119 * The number of items that errored out.
121 public function errorCount();
124 * Returns the number of messages saved.
127 * The number of messages.
129 public function messageCount();
132 * Deletes the map and message entries for a given source record.
134 * @param array $source_id_values
135 * The source identifier keyed values of the record, e.g. ['nid' => 5].
136 * @param bool $messages_only
137 * (optional) TRUE to only delete the migrate messages. Defaults to FALSE.
139 public function delete(array $source_id_values, $messages_only = FALSE);
142 * Deletes the map and message table entries for a given destination row.
144 * @param array $destination_id_values
145 * The destination identifier key value pairs we should do the deletes for.
147 public function deleteDestination(array $destination_id_values);
150 * Clears all messages from the map.
152 public function clearMessages();
155 * Retrieves a row from the map table based on source identifier values.
157 * @param array $source_id_values
158 * The source identifier keyed values of the record, e.g. ['nid' => 5].
161 * The raw row data as an associative array.
163 public function getRowBySource(array $source_id_values);
166 * Retrieves a row by the destination identifiers.
168 * @param array $destination_id_values
169 * The destination identifier keyed values of the record, e.g. ['nid' => 5].
172 * The row(s) of data.
174 public function getRowByDestination(array $destination_id_values);
177 * Retrieves an array of map rows marked as needing update.
180 * The maximum number of rows to return.
183 * Array of map row objects that need updating.
185 public function getRowsNeedingUpdate($count);
188 * Looks up the source identifier.
190 * Given a (possibly multi-field) destination identifier value, return the
191 * (possibly multi-field) source identifier value mapped to it.
193 * @param array $destination_id_values
194 * The destination identifier keyed values of the record, e.g. ['nid' => 5].
197 * The source identifier keyed values of the record, e.g. ['nid' => 5], or
198 * an empty array on failure.
200 public function lookupSourceID(array $destination_id_values);
203 * Looks up the destination identifier corresponding to a source key.
205 * Given a (possibly multi-field) source identifier value, return the
206 * (possibly multi-field) destination identifier value it is mapped to.
208 * @param array $source_id_values
209 * The source identifier keyed values of the record, e.g. ['nid' => 5].
212 * The destination identifier values of the record, or empty on failure.
214 * @deprecated in Drupal 8.1.x, will be removed before Drupal 9.0.x. Use
215 * lookupDestinationIds() instead.
217 public function lookupDestinationId(array $source_id_values);
220 * Looks up the destination identifiers corresponding to a source key.
222 * This can look up a subset of source keys if only some are provided, and
223 * will return all destination keys that match.
225 * @param array $source_id_values
226 * The source identifier keyed values of the records, e.g. ['nid' => 5].
227 * If unkeyed, the first count($source_id_values) keys will be assumed.
230 * An array of arrays of destination identifier values.
232 * @throws \Drupal\migrate\MigrateException
233 * Thrown when $source_id_values contains unknown keys, or is the wrong
236 public function lookupDestinationIds(array $source_id_values);
239 * Looks up the destination identifier currently being iterated.
242 * The destination identifier values of the record, or NULL on failure.
244 public function currentDestination();
247 * Looks up the source identifier(s) currently being iterated.
250 * The source identifier values of the record, or NULL on failure.
252 public function currentSource();
255 * Removes any persistent storage used by this map.
257 * For example, remove the map and message tables.
259 public function destroy();
262 * Gets the qualified map table.
264 * @todo Remove this as this is SQL only and so doesn't belong to the interface.
266 public function getQualifiedMapTableName();
269 * Sets the migrate message.
271 * @param \Drupal\migrate\MigrateMessageInterface $message
272 * The message to display.
274 public function setMessage(MigrateMessageInterface $message);
277 * Sets a specified record to be updated, if it exists.
279 * @param array $source_id_values
280 * The source identifier values of the record.
282 public function setUpdate(array $source_id_values);