Chris@0
|
1 <?php
|
Chris@0
|
2
|
Chris@0
|
3 namespace Drupal\migrate\Plugin;
|
Chris@0
|
4
|
Chris@0
|
5 use Drupal\Component\Plugin\PluginInspectionInterface;
|
Chris@0
|
6 use Drupal\migrate\MigrateMessageInterface;
|
Chris@0
|
7 use Drupal\migrate\Row;
|
Chris@0
|
8
|
Chris@0
|
9 /**
|
Chris@0
|
10 * Defines an interface for migrate ID mappings.
|
Chris@0
|
11 *
|
Chris@0
|
12 * Migrate ID mappings maintain a relation between source ID and destination ID
|
Chris@0
|
13 * for audit and rollback purposes.
|
Chris@0
|
14 */
|
Chris@0
|
15 interface MigrateIdMapInterface extends \Iterator, PluginInspectionInterface {
|
Chris@0
|
16
|
Chris@0
|
17 /**
|
Chris@0
|
18 * Codes reflecting the current status of a map row.
|
Chris@0
|
19 */
|
Chris@0
|
20 const STATUS_IMPORTED = 0;
|
Chris@0
|
21 const STATUS_NEEDS_UPDATE = 1;
|
Chris@0
|
22 const STATUS_IGNORED = 2;
|
Chris@0
|
23 const STATUS_FAILED = 3;
|
Chris@0
|
24
|
Chris@0
|
25 /**
|
Chris@0
|
26 * Codes reflecting how to handle the destination item on rollback.
|
Chris@0
|
27 */
|
Chris@0
|
28 const ROLLBACK_DELETE = 0;
|
Chris@0
|
29 const ROLLBACK_PRESERVE = 1;
|
Chris@0
|
30
|
Chris@0
|
31 /**
|
Chris@0
|
32 * Saves a mapping from the source identifiers to the destination identifiers.
|
Chris@0
|
33 *
|
Chris@0
|
34 * Called upon import of one row, we record a mapping from the source ID to
|
Chris@0
|
35 * the destination ID. Also may be called, setting the third parameter to
|
Chris@0
|
36 * NEEDS_UPDATE, to signal an existing record should be re-migrated.
|
Chris@0
|
37 *
|
Chris@0
|
38 * @param \Drupal\migrate\Row $row
|
Chris@0
|
39 * The raw source data. We use the ID map derived from the source object
|
Chris@0
|
40 * to get the source identifier values.
|
Chris@0
|
41 * @param array $destination_id_values
|
Chris@0
|
42 * An array of destination identifier values.
|
Chris@0
|
43 * @param int $status
|
Chris@0
|
44 * (optional) Status of the source row in the map. Defaults to
|
Chris@0
|
45 * self::STATUS_IMPORTED.
|
Chris@0
|
46 * @param int $rollback_action
|
Chris@0
|
47 * (optional) How to handle the destination object on rollback. Defaults to
|
Chris@0
|
48 * self::ROLLBACK_DELETE.
|
Chris@0
|
49 */
|
Chris@0
|
50 public function saveIdMapping(Row $row, array $destination_id_values, $status = self::STATUS_IMPORTED, $rollback_action = self::ROLLBACK_DELETE);
|
Chris@0
|
51
|
Chris@0
|
52 /**
|
Chris@0
|
53 * Saves a message related to a source record in the migration message table.
|
Chris@0
|
54 *
|
Chris@0
|
55 * @param array $source_id_values
|
Chris@0
|
56 * The source identifier keyed values of the record, e.g. ['nid' => 5].
|
Chris@0
|
57 * @param string $message
|
Chris@0
|
58 * The message to record.
|
Chris@0
|
59 * @param int $level
|
Chris@0
|
60 * (optional) The message severity. Defaults to
|
Chris@0
|
61 * MigrationInterface::MESSAGE_ERROR.
|
Chris@0
|
62 */
|
Chris@0
|
63 public function saveMessage(array $source_id_values, $message, $level = MigrationInterface::MESSAGE_ERROR);
|
Chris@0
|
64
|
Chris@0
|
65 /**
|
Chris@0
|
66 * Retrieves an iterator over messages relate to source records.
|
Chris@0
|
67 *
|
Chris@0
|
68 * @param array $source_id_values
|
Chris@0
|
69 * (optional) The source identifier keyed values of the record, e.g.
|
Chris@0
|
70 * ['nid' => 5]. If empty (the default), all messages are retrieved.
|
Chris@0
|
71 * @param int $level
|
Chris@0
|
72 * (optional) Message severity. If NULL (the default), retrieve messages of
|
Chris@0
|
73 * all severities.
|
Chris@0
|
74 *
|
Chris@0
|
75 * @return \Iterator
|
Chris@0
|
76 * Retrieves an iterator over the message rows.
|
Chris@0
|
77 */
|
Chris@0
|
78 public function getMessageIterator(array $source_id_values = [], $level = NULL);
|
Chris@0
|
79
|
Chris@0
|
80 /**
|
Chris@0
|
81 * Prepares to run a full update.
|
Chris@0
|
82 *
|
Chris@0
|
83 * Prepares this migration to run as an update - that is, in addition to
|
Chris@0
|
84 * unmigrated content (source records not in the map table) being imported,
|
Chris@0
|
85 * previously-migrated content will also be updated in place by marking all
|
Chris@0
|
86 * previously-imported content as ready to be re-imported.
|
Chris@0
|
87 */
|
Chris@0
|
88 public function prepareUpdate();
|
Chris@0
|
89
|
Chris@0
|
90 /**
|
Chris@0
|
91 * Returns the number of processed items in the map.
|
Chris@0
|
92 *
|
Chris@0
|
93 * @return int
|
Chris@0
|
94 * The count of records in the map table.
|
Chris@0
|
95 */
|
Chris@0
|
96 public function processedCount();
|
Chris@0
|
97
|
Chris@0
|
98 /**
|
Chris@0
|
99 * Returns the number of imported items in the map.
|
Chris@0
|
100 *
|
Chris@0
|
101 * @return int
|
Chris@0
|
102 * The number of imported items.
|
Chris@0
|
103 */
|
Chris@0
|
104 public function importedCount();
|
Chris@0
|
105
|
Chris@0
|
106 /**
|
Chris@0
|
107 * Returns a count of items which are marked as needing update.
|
Chris@0
|
108 *
|
Chris@0
|
109 * @return int
|
Chris@0
|
110 * The number of items which need updating.
|
Chris@0
|
111 */
|
Chris@0
|
112 public function updateCount();
|
Chris@0
|
113
|
Chris@0
|
114 /**
|
Chris@0
|
115 * Returns the number of items that failed to import.
|
Chris@0
|
116 *
|
Chris@0
|
117 * @return int
|
Chris@0
|
118 * The number of items that errored out.
|
Chris@0
|
119 */
|
Chris@0
|
120 public function errorCount();
|
Chris@0
|
121
|
Chris@0
|
122 /**
|
Chris@0
|
123 * Returns the number of messages saved.
|
Chris@0
|
124 *
|
Chris@0
|
125 * @return int
|
Chris@0
|
126 * The number of messages.
|
Chris@0
|
127 */
|
Chris@0
|
128 public function messageCount();
|
Chris@0
|
129
|
Chris@0
|
130 /**
|
Chris@0
|
131 * Deletes the map and message entries for a given source record.
|
Chris@0
|
132 *
|
Chris@0
|
133 * @param array $source_id_values
|
Chris@0
|
134 * The source identifier keyed values of the record, e.g. ['nid' => 5].
|
Chris@0
|
135 * @param bool $messages_only
|
Chris@0
|
136 * (optional) TRUE to only delete the migrate messages. Defaults to FALSE.
|
Chris@0
|
137 */
|
Chris@0
|
138 public function delete(array $source_id_values, $messages_only = FALSE);
|
Chris@0
|
139
|
Chris@0
|
140 /**
|
Chris@0
|
141 * Deletes the map and message table entries for a given destination row.
|
Chris@0
|
142 *
|
Chris@0
|
143 * @param array $destination_id_values
|
Chris@0
|
144 * The destination identifier key value pairs we should do the deletes for.
|
Chris@0
|
145 */
|
Chris@0
|
146 public function deleteDestination(array $destination_id_values);
|
Chris@0
|
147
|
Chris@0
|
148 /**
|
Chris@0
|
149 * Clears all messages from the map.
|
Chris@0
|
150 */
|
Chris@0
|
151 public function clearMessages();
|
Chris@0
|
152
|
Chris@0
|
153 /**
|
Chris@0
|
154 * Retrieves a row from the map table based on source identifier values.
|
Chris@0
|
155 *
|
Chris@0
|
156 * @param array $source_id_values
|
Chris@0
|
157 * The source identifier keyed values of the record, e.g. ['nid' => 5].
|
Chris@0
|
158 *
|
Chris@0
|
159 * @return array
|
Chris@0
|
160 * The raw row data as an associative array.
|
Chris@0
|
161 */
|
Chris@0
|
162 public function getRowBySource(array $source_id_values);
|
Chris@0
|
163
|
Chris@0
|
164 /**
|
Chris@0
|
165 * Retrieves a row by the destination identifiers.
|
Chris@0
|
166 *
|
Chris@0
|
167 * @param array $destination_id_values
|
Chris@0
|
168 * The destination identifier keyed values of the record, e.g. ['nid' => 5].
|
Chris@0
|
169 *
|
Chris@0
|
170 * @return array
|
Chris@0
|
171 * The row(s) of data.
|
Chris@0
|
172 */
|
Chris@0
|
173 public function getRowByDestination(array $destination_id_values);
|
Chris@0
|
174
|
Chris@0
|
175 /**
|
Chris@0
|
176 * Retrieves an array of map rows marked as needing update.
|
Chris@0
|
177 *
|
Chris@0
|
178 * @param int $count
|
Chris@0
|
179 * The maximum number of rows to return.
|
Chris@0
|
180 *
|
Chris@0
|
181 * @return array
|
Chris@0
|
182 * Array of map row objects that need updating.
|
Chris@0
|
183 */
|
Chris@0
|
184 public function getRowsNeedingUpdate($count);
|
Chris@0
|
185
|
Chris@0
|
186 /**
|
Chris@0
|
187 * Looks up the source identifier.
|
Chris@0
|
188 *
|
Chris@0
|
189 * Given a (possibly multi-field) destination identifier value, return the
|
Chris@0
|
190 * (possibly multi-field) source identifier value mapped to it.
|
Chris@0
|
191 *
|
Chris@0
|
192 * @param array $destination_id_values
|
Chris@0
|
193 * The destination identifier keyed values of the record, e.g. ['nid' => 5].
|
Chris@0
|
194 *
|
Chris@0
|
195 * @return array
|
Chris@0
|
196 * The source identifier keyed values of the record, e.g. ['nid' => 5], or
|
Chris@0
|
197 * an empty array on failure.
|
Chris@0
|
198 */
|
Chris@16
|
199 public function lookupSourceId(array $destination_id_values);
|
Chris@0
|
200
|
Chris@0
|
201 /**
|
Chris@0
|
202 * Looks up the destination identifier corresponding to a source key.
|
Chris@0
|
203 *
|
Chris@0
|
204 * Given a (possibly multi-field) source identifier value, return the
|
Chris@0
|
205 * (possibly multi-field) destination identifier value it is mapped to.
|
Chris@0
|
206 *
|
Chris@0
|
207 * @param array $source_id_values
|
Chris@0
|
208 * The source identifier keyed values of the record, e.g. ['nid' => 5].
|
Chris@0
|
209 *
|
Chris@0
|
210 * @return array
|
Chris@0
|
211 * The destination identifier values of the record, or empty on failure.
|
Chris@0
|
212 *
|
Chris@0
|
213 * @deprecated in Drupal 8.1.x, will be removed before Drupal 9.0.x. Use
|
Chris@0
|
214 * lookupDestinationIds() instead.
|
Chris@0
|
215 *
|
Chris@0
|
216 * @see https://www.drupal.org/node/2725809
|
Chris@0
|
217 */
|
Chris@0
|
218 public function lookupDestinationId(array $source_id_values);
|
Chris@0
|
219
|
Chris@0
|
220 /**
|
Chris@0
|
221 * Looks up the destination identifiers corresponding to a source key.
|
Chris@0
|
222 *
|
Chris@0
|
223 * This can look up a subset of source keys if only some are provided, and
|
Chris@0
|
224 * will return all destination keys that match.
|
Chris@0
|
225 *
|
Chris@0
|
226 * @param array $source_id_values
|
Chris@0
|
227 * The source identifier keyed values of the records, e.g. ['nid' => 5].
|
Chris@0
|
228 * If unkeyed, the first count($source_id_values) keys will be assumed.
|
Chris@0
|
229 *
|
Chris@0
|
230 * @return array
|
Chris@0
|
231 * An array of arrays of destination identifier values.
|
Chris@0
|
232 *
|
Chris@0
|
233 * @throws \Drupal\migrate\MigrateException
|
Chris@0
|
234 * Thrown when $source_id_values contains unknown keys, or is the wrong
|
Chris@0
|
235 * length.
|
Chris@0
|
236 */
|
Chris@0
|
237 public function lookupDestinationIds(array $source_id_values);
|
Chris@0
|
238
|
Chris@0
|
239 /**
|
Chris@0
|
240 * Looks up the destination identifier currently being iterated.
|
Chris@0
|
241 *
|
Chris@0
|
242 * @return array
|
Chris@0
|
243 * The destination identifier values of the record, or NULL on failure.
|
Chris@0
|
244 */
|
Chris@0
|
245 public function currentDestination();
|
Chris@0
|
246
|
Chris@0
|
247 /**
|
Chris@0
|
248 * Looks up the source identifier(s) currently being iterated.
|
Chris@0
|
249 *
|
Chris@0
|
250 * @return array
|
Chris@0
|
251 * The source identifier values of the record, or NULL on failure.
|
Chris@0
|
252 */
|
Chris@0
|
253 public function currentSource();
|
Chris@0
|
254
|
Chris@0
|
255 /**
|
Chris@0
|
256 * Removes any persistent storage used by this map.
|
Chris@0
|
257 *
|
Chris@0
|
258 * For example, remove the map and message tables.
|
Chris@0
|
259 */
|
Chris@0
|
260 public function destroy();
|
Chris@0
|
261
|
Chris@0
|
262 /**
|
Chris@0
|
263 * Gets the qualified map table.
|
Chris@0
|
264 *
|
Chris@0
|
265 * @todo Remove this as this is SQL only and so doesn't belong to the interface.
|
Chris@0
|
266 */
|
Chris@0
|
267 public function getQualifiedMapTableName();
|
Chris@0
|
268
|
Chris@0
|
269 /**
|
Chris@0
|
270 * Sets the migrate message service.
|
Chris@0
|
271 *
|
Chris@0
|
272 * @param \Drupal\migrate\MigrateMessageInterface $message
|
Chris@0
|
273 * The migrate message service.
|
Chris@0
|
274 */
|
Chris@0
|
275 public function setMessage(MigrateMessageInterface $message);
|
Chris@0
|
276
|
Chris@0
|
277 /**
|
Chris@0
|
278 * Sets a specified record to be updated, if it exists.
|
Chris@0
|
279 *
|
Chris@0
|
280 * @param array $source_id_values
|
Chris@0
|
281 * The source identifier values of the record.
|
Chris@0
|
282 */
|
Chris@0
|
283 public function setUpdate(array $source_id_values);
|
Chris@0
|
284
|
Chris@0
|
285 }
|