www.aleph1.co.uk Git - yaffs-website/blob - web/core/modules/migrate/src/Plugin/MigrateIdMapInterface.php

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