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\Row;
Chris@0: 
Chris@0: /**
Chris@0:  * Defines an interface for Migration Destination classes.
Chris@0:  *
Chris@0:  * Destinations are responsible for persisting source data into the destination
Chris@0:  * Drupal.
Chris@0:  *
Chris@16:  * @see \Drupal\migrate\Plugin\migrate\destination\DestinationBase
Chris@0:  * @see \Drupal\migrate\Plugin\MigrateDestinationPluginManager
Chris@0:  * @see \Drupal\migrate\Annotation\MigrateDestination
Chris@0:  * @see plugin_api
Chris@0:  *
Chris@0:  * @ingroup migration
Chris@0:  */
Chris@0: interface MigrateDestinationInterface extends PluginInspectionInterface {
Chris@0: 
Chris@0:   /**
Chris@0:    * Gets the destination IDs.
Chris@0:    *
Chris@0:    * To support MigrateIdMap maps, derived destination classes should return
Chris@0:    * field definition(s) corresponding to the primary key of the destination
Chris@0:    * being implemented. These are used to construct the destination key fields
Chris@0:    * of the map table for a migration using this destination.
Chris@0:    *
Chris@0:    * @return array[]
Chris@0:    *   An associative array of field definitions keyed by field ID. Values are
Chris@0:    *   associative arrays with a structure that contains the field type ('type'
Chris@0:    *   key). The other keys are the field storage settings as they are returned
Chris@0:    *   by FieldStorageDefinitionInterface::getSettings(). As an example, for a
Chris@0:    *   composite destination primary key that is defined by an integer and a
Chris@0:    *   string, the returned value might look like:
Chris@0:    *   @code
Chris@0:    *     return [
Chris@0:    *       'id' => [
Chris@0:    *         'type' => 'integer',
Chris@0:    *         'unsigned' => FALSE,
Chris@0:    *         'size' => 'big',
Chris@0:    *       ],
Chris@0:    *       'version' => [
Chris@0:    *         'type' => 'string',
Chris@0:    *         'max_length' => 64,
Chris@0:    *         'is_ascii' => TRUE,
Chris@0:    *       ],
Chris@0:    *     ];
Chris@0:    *   @endcode
Chris@0:    *   If 'type' points to a field plugin with multiple columns and needs to
Chris@0:    *   refer to a column different than 'value', the key of that column will be
Chris@0:    *   appended as a suffix to the plugin name, separated by dot ('.'). Example:
Chris@0:    *   @code
Chris@0:    *     return [
Chris@0:    *       'format' => [
Chris@0:    *         'type' => 'text.format',
Chris@0:    *       ],
Chris@0:    *     ];
Chris@0:    *   @endcode
Chris@0:    *   Additional custom keys/values, that are not part of field storage
Chris@0:    *   definition, can be passed in definitions:
Chris@0:    *   @code
Chris@0:    *     return [
Chris@0:    *       'nid' => [
Chris@0:    *         'type' => 'integer',
Chris@0:    *         'custom_setting' => 'some_value',
Chris@0:    *       ],
Chris@0:    *     ];
Chris@0:    *   @endcode
Chris@0:    *
Chris@0:    * @see \Drupal\Core\Field\FieldStorageDefinitionInterface::getSettings()
Chris@0:    * @see \Drupal\Core\Field\Plugin\Field\FieldType\IntegerItem
Chris@0:    * @see \Drupal\Core\Field\Plugin\Field\FieldType\StringItem
Chris@0:    * @see \Drupal\text\Plugin\Field\FieldType\TextItem
Chris@0:    */
Chris@0:   public function getIds();
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns an array of destination fields.
Chris@0:    *
Chris@0:    * Derived classes must implement fields(), returning a list of available
Chris@0:    * destination fields.
Chris@0:    *
Chris@0:    * @param \Drupal\migrate\Plugin\MigrationInterface $migration
Chris@0:    *   Unused, will be removed before Drupal 9.0.x. Defaults to NULL.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   - Keys: machine names of the fields
Chris@0:    *   - Values: Human-friendly descriptions of the fields.
Chris@0:    */
Chris@0:   public function fields(MigrationInterface $migration = NULL);
Chris@0: 
Chris@0:   /**
Chris@0:    * Import the row.
Chris@0:    *
Chris@0:    * Derived classes must implement import(), to construct one new object
Chris@0:    * (pre-populated) using ID mappings in the Migration.
Chris@0:    *
Chris@0:    * @param \Drupal\migrate\Row $row
Chris@0:    *   The row object.
Chris@0:    * @param array $old_destination_id_values
Chris@0:    *   (optional) The old destination IDs. Defaults to an empty array.
Chris@0:    *
Chris@0:    * @return mixed
Chris@0:    *   The entity ID or an indication of success.
Chris@0:    */
Chris@0:   public function import(Row $row, array $old_destination_id_values = []);
Chris@0: 
Chris@0:   /**
Chris@0:    * Delete the specified destination object from the target Drupal.
Chris@0:    *
Chris@0:    * @param array $destination_identifier
Chris@0:    *   The ID of the destination object to delete.
Chris@0:    */
Chris@0:   public function rollback(array $destination_identifier);
Chris@0: 
Chris@0:   /**
Chris@0:    * Whether the destination can be rolled back or not.
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    *   TRUE if rollback is supported, FALSE if not.
Chris@0:    */
Chris@0:   public function supportsRollback();
Chris@0: 
Chris@0:   /**
Chris@0:    * The rollback action for the last imported item.
Chris@0:    *
Chris@0:    * @return int
Chris@0:    *   The MigrateIdMapInterface::ROLLBACK_ constant indicating how an imported
Chris@0:    *   item should be handled on rollback.
Chris@0:    */
Chris@0:   public function rollbackAction();
Chris@0: 
Chris@0:   /**
Chris@0:    * Gets the destination module handling the destination data.
Chris@0:    *
Chris@0:    * @return string|null
Chris@0:    *   The destination module or NULL if not found.
Chris@0:    */
Chris@0:   public function getDestinationModule();
Chris@0: 
Chris@0: }