Chris@0: <?php
Chris@0: 
Chris@0: namespace Drupal\migrate\Plugin;
Chris@0: 
Chris@0: use Drupal\Component\Plugin\PluginInspectionInterface;
Chris@0: use Drupal\migrate\MigrateMessageInterface;
Chris@0: use Drupal\migrate\Row;
Chris@0: 
Chris@0: /**
Chris@0:  * Defines an interface for migrate ID mappings.
Chris@0:  *
Chris@0:  * Migrate ID mappings maintain a relation between source ID and destination ID
Chris@0:  * for audit and rollback purposes.
Chris@0:  */
Chris@0: interface MigrateIdMapInterface extends \Iterator, PluginInspectionInterface {
Chris@0: 
Chris@0:   /**
Chris@0:    * Codes reflecting the current status of a map row.
Chris@0:    */
Chris@0:   const STATUS_IMPORTED = 0;
Chris@0:   const STATUS_NEEDS_UPDATE = 1;
Chris@0:   const STATUS_IGNORED = 2;
Chris@0:   const STATUS_FAILED = 3;
Chris@0: 
Chris@0:   /**
Chris@0:    * Codes reflecting how to handle the destination item on rollback.
Chris@0:    */
Chris@0:   const ROLLBACK_DELETE = 0;
Chris@0:   const ROLLBACK_PRESERVE = 1;
Chris@0: 
Chris@0:   /**
Chris@0:    * Saves a mapping from the source identifiers to the destination identifiers.
Chris@0:    *
Chris@0:    * Called upon import of one row, we record a mapping from the source ID to
Chris@0:    * the destination ID. Also may be called, setting the third parameter to
Chris@0:    * NEEDS_UPDATE, to signal an existing record should be re-migrated.
Chris@0:    *
Chris@0:    * @param \Drupal\migrate\Row $row
Chris@0:    *   The raw source data. We use the ID map derived from the source object
Chris@0:    *   to get the source identifier values.
Chris@0:    * @param array $destination_id_values
Chris@0:    *   An array of destination identifier values.
Chris@0:    * @param int $status
Chris@0:    *   (optional) Status of the source row in the map. Defaults to
Chris@0:    *   self::STATUS_IMPORTED.
Chris@0:    * @param int $rollback_action
Chris@0:    *   (optional) How to handle the destination object on rollback. Defaults to
Chris@0:    *   self::ROLLBACK_DELETE.
Chris@0:    */
Chris@0:   public function saveIdMapping(Row $row, array $destination_id_values, $status = self::STATUS_IMPORTED, $rollback_action = self::ROLLBACK_DELETE);
Chris@0: 
Chris@0:   /**
Chris@0:    * Saves a message related to a source record in the migration message table.
Chris@0:    *
Chris@0:    * @param array $source_id_values
Chris@0:    *   The source identifier keyed values of the record, e.g. ['nid' => 5].
Chris@0:    * @param string $message
Chris@0:    *   The message to record.
Chris@0:    * @param int $level
Chris@0:    *   (optional) The message severity. Defaults to
Chris@0:    *   MigrationInterface::MESSAGE_ERROR.
Chris@0:    */
Chris@0:   public function saveMessage(array $source_id_values, $message, $level = MigrationInterface::MESSAGE_ERROR);
Chris@0: 
Chris@0:   /**
Chris@0:    * Retrieves an iterator over messages relate to source records.
Chris@0:    *
Chris@0:    * @param array $source_id_values
Chris@0:    *   (optional) The source identifier keyed values of the record, e.g.
Chris@0:    *   ['nid' => 5]. If empty (the default), all messages are retrieved.
Chris@0:    * @param int $level
Chris@0:    *   (optional) Message severity. If NULL (the default), retrieve messages of
Chris@0:    *   all severities.
Chris@0:    *
Chris@0:    * @return \Iterator
Chris@0:    *   Retrieves an iterator over the message rows.
Chris@0:    */
Chris@0:   public function getMessageIterator(array $source_id_values = [], $level = NULL);
Chris@0: 
Chris@0:   /**
Chris@0:    * Prepares to run a full update.
Chris@0:    *
Chris@0:    * Prepares this migration to run as an update - that is, in addition to
Chris@0:    * unmigrated content (source records not in the map table) being imported,
Chris@0:    * previously-migrated content will also be updated in place by marking all
Chris@0:    * previously-imported content as ready to be re-imported.
Chris@0:    */
Chris@0:   public function prepareUpdate();
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns the number of processed items in the map.
Chris@0:    *
Chris@0:    * @return int
Chris@0:    *   The count of records in the map table.
Chris@0:    */
Chris@0:   public function processedCount();
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns the number of imported items in the map.
Chris@0:    *
Chris@0:    * @return int
Chris@0:    *   The number of imported items.
Chris@0:    */
Chris@0:   public function importedCount();
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns a count of items which are marked as needing update.
Chris@0:    *
Chris@0:    * @return int
Chris@0:    *   The number of items which need updating.
Chris@0:    */
Chris@0:   public function updateCount();
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns the number of items that failed to import.
Chris@0:    *
Chris@0:    * @return int
Chris@0:    *   The number of items that errored out.
Chris@0:    */
Chris@0:   public function errorCount();
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns the number of messages saved.
Chris@0:    *
Chris@0:    * @return int
Chris@0:    *   The number of messages.
Chris@0:    */
Chris@0:   public function messageCount();
Chris@0: 
Chris@0:   /**
Chris@0:    * Deletes the map and message entries for a given source record.
Chris@0:    *
Chris@0:    * @param array $source_id_values
Chris@0:    *   The source identifier keyed values of the record, e.g. ['nid' => 5].
Chris@0:    * @param bool $messages_only
Chris@0:    *   (optional) TRUE to only delete the migrate messages. Defaults to FALSE.
Chris@0:    */
Chris@0:   public function delete(array $source_id_values, $messages_only = FALSE);
Chris@0: 
Chris@0:   /**
Chris@0:    * Deletes the map and message table entries for a given destination row.
Chris@0:    *
Chris@0:    * @param array $destination_id_values
Chris@0:    *   The destination identifier key value pairs we should do the deletes for.
Chris@0:    */
Chris@0:   public function deleteDestination(array $destination_id_values);
Chris@0: 
Chris@0:   /**
Chris@0:    * Clears all messages from the map.
Chris@0:    */
Chris@0:   public function clearMessages();
Chris@0: 
Chris@0:   /**
Chris@0:    * Retrieves a row from the map table based on source identifier values.
Chris@0:    *
Chris@0:    * @param array $source_id_values
Chris@0:    *   The source identifier keyed values of the record, e.g. ['nid' => 5].
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   The raw row data as an associative array.
Chris@0:    */
Chris@0:   public function getRowBySource(array $source_id_values);
Chris@0: 
Chris@0:   /**
Chris@0:    * Retrieves a row by the destination identifiers.
Chris@0:    *
Chris@0:    * @param array $destination_id_values
Chris@0:    *   The destination identifier keyed values of the record, e.g. ['nid' => 5].
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   The row(s) of data.
Chris@0:    */
Chris@0:   public function getRowByDestination(array $destination_id_values);
Chris@0: 
Chris@0:   /**
Chris@0:    * Retrieves an array of map rows marked as needing update.
Chris@0:    *
Chris@0:    * @param int $count
Chris@0:    *   The maximum number of rows to return.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   Array of map row objects that need updating.
Chris@0:    */
Chris@0:   public function getRowsNeedingUpdate($count);
Chris@0: 
Chris@0:   /**
Chris@0:    * Looks up the source identifier.
Chris@0:    *
Chris@0:    * Given a (possibly multi-field) destination identifier value, return the
Chris@0:    * (possibly multi-field) source identifier value mapped to it.
Chris@0:    *
Chris@0:    * @param array $destination_id_values
Chris@0:    *   The destination identifier keyed values of the record, e.g. ['nid' => 5].
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   The source identifier keyed values of the record, e.g. ['nid' => 5], or
Chris@0:    *   an empty array on failure.
Chris@0:    */
Chris@16:   public function lookupSourceId(array $destination_id_values);
Chris@0: 
Chris@0:   /**
Chris@0:    * Looks up the destination identifier corresponding to a source key.
Chris@0:    *
Chris@0:    * Given a (possibly multi-field) source identifier value, return the
Chris@0:    * (possibly multi-field) destination identifier value it is mapped to.
Chris@0:    *
Chris@0:    * @param array $source_id_values
Chris@0:    *   The source identifier keyed values of the record, e.g. ['nid' => 5].
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   The destination identifier values of the record, or empty on failure.
Chris@0:    *
Chris@0:    * @deprecated in Drupal 8.1.x, will be removed before Drupal 9.0.x. Use
Chris@0:    *   lookupDestinationIds() instead.
Chris@0:    *
Chris@0:    * @see https://www.drupal.org/node/2725809
Chris@0:    */
Chris@0:   public function lookupDestinationId(array $source_id_values);
Chris@0: 
Chris@0:   /**
Chris@0:    * Looks up the destination identifiers corresponding to a source key.
Chris@0:    *
Chris@0:    * This can look up a subset of source keys if only some are provided, and
Chris@0:    * will return all destination keys that match.
Chris@0:    *
Chris@0:    * @param array $source_id_values
Chris@0:    *   The source identifier keyed values of the records, e.g. ['nid' => 5].
Chris@0:    *   If unkeyed, the first count($source_id_values) keys will be assumed.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   An array of arrays of destination identifier values.
Chris@0:    *
Chris@0:    * @throws \Drupal\migrate\MigrateException
Chris@0:    *   Thrown when $source_id_values contains unknown keys, or is the wrong
Chris@0:    *   length.
Chris@0:    */
Chris@0:   public function lookupDestinationIds(array $source_id_values);
Chris@0: 
Chris@0:   /**
Chris@0:    * Looks up the destination identifier currently being iterated.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   The destination identifier values of the record, or NULL on failure.
Chris@0:    */
Chris@0:   public function currentDestination();
Chris@0: 
Chris@0:   /**
Chris@0:    * Looks up the source identifier(s) currently being iterated.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   The source identifier values of the record, or NULL on failure.
Chris@0:    */
Chris@0:   public function currentSource();
Chris@0: 
Chris@0:   /**
Chris@0:    * Removes any persistent storage used by this map.
Chris@0:    *
Chris@0:    * For example, remove the map and message tables.
Chris@0:    */
Chris@0:   public function destroy();
Chris@0: 
Chris@0:   /**
Chris@0:    * Gets the qualified map table.
Chris@0:    *
Chris@0:    * @todo Remove this as this is SQL only and so doesn't belong to the interface.
Chris@0:    */
Chris@0:   public function getQualifiedMapTableName();
Chris@0: 
Chris@0:   /**
Chris@0:    * Sets the migrate message service.
Chris@0:    *
Chris@0:    * @param \Drupal\migrate\MigrateMessageInterface $message
Chris@0:    *   The migrate message service.
Chris@0:    */
Chris@0:   public function setMessage(MigrateMessageInterface $message);
Chris@0: 
Chris@0:   /**
Chris@0:    * Sets a specified record to be updated, if it exists.
Chris@0:    *
Chris@0:    * @param array $source_id_values
Chris@0:    *   The source identifier values of the record.
Chris@0:    */
Chris@0:   public function setUpdate(array $source_id_values);
Chris@0: 
Chris@0: }