annotate core/modules/migrate/src/Plugin/MigrateIdMapInterface.php @ 19:fa3358dc1485 tip

Add ndrum files
author Chris Cannam
date Wed, 28 Aug 2019 13:14:47 +0100
parents 129ea1e6d783
children
rev   line source
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 }