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    * Returns a count of items which are marked as needing update.
 108    *
 109    * @return int
 110    *   The number of items which need updating.
 111    */
 112   public function updateCount();
 113
 114   /**
 115    * Returns the number of items that failed to import.
 116    *
 117    * @return int
 118    *   The number of items that errored out.
 119    */
 120   public function errorCount();
 121
 122   /**
 123    * Returns the number of messages saved.
 124    *
 125    * @return int
 126    *   The number of messages.
 127    */
 128   public function messageCount();
 129
 130   /**
 131    * Deletes the map and message entries for a given source record.
 132    *
 133    * @param array $source_id_values
 134    *   The source identifier keyed values of the record, e.g. ['nid' => 5].
 135    * @param bool $messages_only
 136    *   (optional) TRUE to only delete the migrate messages. Defaults to FALSE.
 137    */
 138   public function delete(array $source_id_values, $messages_only = FALSE);
 139
 140   /**
 141    * Deletes the map and message table entries for a given destination row.
 142    *
 143    * @param array $destination_id_values
 144    *   The destination identifier key value pairs we should do the deletes for.
 145    */
 146   public function deleteDestination(array $destination_id_values);
 147
 148   /**
 149    * Clears all messages from the map.
 150    */
 151   public function clearMessages();
 152
 153   /**
 154    * Retrieves a row from the map table based on source identifier values.
 155    *
 156    * @param array $source_id_values
 157    *   The source identifier keyed values of the record, e.g. ['nid' => 5].
 158    *
 159    * @return array
 160    *   The raw row data as an associative array.
 161    */
 162   public function getRowBySource(array $source_id_values);
 163
 164   /**
 165    * Retrieves a row by the destination identifiers.
 166    *
 167    * @param array $destination_id_values
 168    *   The destination identifier keyed values of the record, e.g. ['nid' => 5].
 169    *
 170    * @return array
 171    *   The row(s) of data.
 172    */
 173   public function getRowByDestination(array $destination_id_values);
 174
 175   /**
 176    * Retrieves an array of map rows marked as needing update.
 177    *
 178    * @param int $count
 179    *   The maximum number of rows to return.
 180    *
 181    * @return array
 182    *   Array of map row objects that need updating.
 183    */
 184   public function getRowsNeedingUpdate($count);
 185
 186   /**
 187    * Looks up the source identifier.
 188    *
 189    * Given a (possibly multi-field) destination identifier value, return the
 190    * (possibly multi-field) source identifier value mapped to it.
 191    *
 192    * @param array $destination_id_values
 193    *   The destination identifier keyed values of the record, e.g. ['nid' => 5].
 194    *
 195    * @return array
 196    *   The source identifier keyed values of the record, e.g. ['nid' => 5], or
 197    *   an empty array on failure.
 198    */
 199   public function lookupSourceId(array $destination_id_values);
 200
 201   /**
 202    * Looks up the destination identifier corresponding to a source key.
 203    *
 204    * Given a (possibly multi-field) source identifier value, return the
 205    * (possibly multi-field) destination identifier value it is mapped to.
 206    *
 207    * @param array $source_id_values
 208    *   The source identifier keyed values of the record, e.g. ['nid' => 5].
 209    *
 210    * @return array
 211    *   The destination identifier values of the record, or empty on failure.
 212    *
 213    * @deprecated in Drupal 8.1.x, will be removed before Drupal 9.0.x. Use
 214    *   lookupDestinationIds() instead.
 215    *
 216    * @see https://www.drupal.org/node/2725809
 217    */
 218   public function lookupDestinationId(array $source_id_values);
 219
 220   /**
 221    * Looks up the destination identifiers corresponding to a source key.
 222    *
 223    * This can look up a subset of source keys if only some are provided, and
 224    * will return all destination keys that match.
 225    *
 226    * @param array $source_id_values
 227    *   The source identifier keyed values of the records, e.g. ['nid' => 5].
 228    *   If unkeyed, the first count($source_id_values) keys will be assumed.
 229    *
 230    * @return array
 231    *   An array of arrays of destination identifier values.
 232    *
 233    * @throws \Drupal\migrate\MigrateException
 234    *   Thrown when $source_id_values contains unknown keys, or is the wrong
 235    *   length.
 236    */
 237   public function lookupDestinationIds(array $source_id_values);
 238
 239   /**
 240    * Looks up the destination identifier currently being iterated.
 241    *
 242    * @return array
 243    *   The destination identifier values of the record, or NULL on failure.
 244    */
 245   public function currentDestination();
 246
 247   /**
 248    * Looks up the source identifier(s) currently being iterated.
 249    *
 250    * @return array
 251    *   The source identifier values of the record, or NULL on failure.
 252    */
 253   public function currentSource();
 254
 255   /**
 256    * Removes any persistent storage used by this map.
 257    *
 258    * For example, remove the map and message tables.
 259    */
 260   public function destroy();
 261
 262   /**
 263    * Gets the qualified map table.
 264    *
 265    * @todo Remove this as this is SQL only and so doesn't belong to the interface.
 266    */
 267   public function getQualifiedMapTableName();
 268
 269   /**
 270    * Sets the migrate message service.
 271    *
 272    * @param \Drupal\migrate\MigrateMessageInterface $message
 273    *   The migrate message service.
 274    */
 275   public function setMessage(MigrateMessageInterface $message);
 276
 277   /**
 278    * Sets a specified record to be updated, if it exists.
 279    *
 280    * @param array $source_id_values
 281    *   The source identifier values of the record.
 282    */
 283   public function setUpdate(array $source_id_values);
 284
 285 }