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

Add ndrum files
author Chris Cannam
date Wed, 28 Aug 2019 13:14:47 +0100
parents c2387f117808
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\Row;
Chris@0 7
Chris@0 8 /**
Chris@0 9 * Defines an interface for Migration Destination classes.
Chris@0 10 *
Chris@0 11 * Destinations are responsible for persisting source data into the destination
Chris@0 12 * Drupal.
Chris@0 13 *
Chris@16 14 * @see \Drupal\migrate\Plugin\migrate\destination\DestinationBase
Chris@0 15 * @see \Drupal\migrate\Plugin\MigrateDestinationPluginManager
Chris@0 16 * @see \Drupal\migrate\Annotation\MigrateDestination
Chris@0 17 * @see plugin_api
Chris@0 18 *
Chris@0 19 * @ingroup migration
Chris@0 20 */
Chris@0 21 interface MigrateDestinationInterface extends PluginInspectionInterface {
Chris@0 22
Chris@0 23 /**
Chris@0 24 * Gets the destination IDs.
Chris@0 25 *
Chris@0 26 * To support MigrateIdMap maps, derived destination classes should return
Chris@0 27 * field definition(s) corresponding to the primary key of the destination
Chris@0 28 * being implemented. These are used to construct the destination key fields
Chris@0 29 * of the map table for a migration using this destination.
Chris@0 30 *
Chris@0 31 * @return array[]
Chris@0 32 * An associative array of field definitions keyed by field ID. Values are
Chris@0 33 * associative arrays with a structure that contains the field type ('type'
Chris@0 34 * key). The other keys are the field storage settings as they are returned
Chris@0 35 * by FieldStorageDefinitionInterface::getSettings(). As an example, for a
Chris@0 36 * composite destination primary key that is defined by an integer and a
Chris@0 37 * string, the returned value might look like:
Chris@0 38 * @code
Chris@0 39 * return [
Chris@0 40 * 'id' => [
Chris@0 41 * 'type' => 'integer',
Chris@0 42 * 'unsigned' => FALSE,
Chris@0 43 * 'size' => 'big',
Chris@0 44 * ],
Chris@0 45 * 'version' => [
Chris@0 46 * 'type' => 'string',
Chris@0 47 * 'max_length' => 64,
Chris@0 48 * 'is_ascii' => TRUE,
Chris@0 49 * ],
Chris@0 50 * ];
Chris@0 51 * @endcode
Chris@0 52 * If 'type' points to a field plugin with multiple columns and needs to
Chris@0 53 * refer to a column different than 'value', the key of that column will be
Chris@0 54 * appended as a suffix to the plugin name, separated by dot ('.'). Example:
Chris@0 55 * @code
Chris@0 56 * return [
Chris@0 57 * 'format' => [
Chris@0 58 * 'type' => 'text.format',
Chris@0 59 * ],
Chris@0 60 * ];
Chris@0 61 * @endcode
Chris@0 62 * Additional custom keys/values, that are not part of field storage
Chris@0 63 * definition, can be passed in definitions:
Chris@0 64 * @code
Chris@0 65 * return [
Chris@0 66 * 'nid' => [
Chris@0 67 * 'type' => 'integer',
Chris@0 68 * 'custom_setting' => 'some_value',
Chris@0 69 * ],
Chris@0 70 * ];
Chris@0 71 * @endcode
Chris@0 72 *
Chris@0 73 * @see \Drupal\Core\Field\FieldStorageDefinitionInterface::getSettings()
Chris@0 74 * @see \Drupal\Core\Field\Plugin\Field\FieldType\IntegerItem
Chris@0 75 * @see \Drupal\Core\Field\Plugin\Field\FieldType\StringItem
Chris@0 76 * @see \Drupal\text\Plugin\Field\FieldType\TextItem
Chris@0 77 */
Chris@0 78 public function getIds();
Chris@0 79
Chris@0 80 /**
Chris@0 81 * Returns an array of destination fields.
Chris@0 82 *
Chris@0 83 * Derived classes must implement fields(), returning a list of available
Chris@0 84 * destination fields.
Chris@0 85 *
Chris@0 86 * @param \Drupal\migrate\Plugin\MigrationInterface $migration
Chris@0 87 * Unused, will be removed before Drupal 9.0.x. Defaults to NULL.
Chris@0 88 *
Chris@0 89 * @return array
Chris@0 90 * - Keys: machine names of the fields
Chris@0 91 * - Values: Human-friendly descriptions of the fields.
Chris@0 92 */
Chris@0 93 public function fields(MigrationInterface $migration = NULL);
Chris@0 94
Chris@0 95 /**
Chris@0 96 * Import the row.
Chris@0 97 *
Chris@0 98 * Derived classes must implement import(), to construct one new object
Chris@0 99 * (pre-populated) using ID mappings in the Migration.
Chris@0 100 *
Chris@0 101 * @param \Drupal\migrate\Row $row
Chris@0 102 * The row object.
Chris@0 103 * @param array $old_destination_id_values
Chris@0 104 * (optional) The old destination IDs. Defaults to an empty array.
Chris@0 105 *
Chris@0 106 * @return mixed
Chris@0 107 * The entity ID or an indication of success.
Chris@0 108 */
Chris@0 109 public function import(Row $row, array $old_destination_id_values = []);
Chris@0 110
Chris@0 111 /**
Chris@0 112 * Delete the specified destination object from the target Drupal.
Chris@0 113 *
Chris@0 114 * @param array $destination_identifier
Chris@0 115 * The ID of the destination object to delete.
Chris@0 116 */
Chris@0 117 public function rollback(array $destination_identifier);
Chris@0 118
Chris@0 119 /**
Chris@0 120 * Whether the destination can be rolled back or not.
Chris@0 121 *
Chris@0 122 * @return bool
Chris@0 123 * TRUE if rollback is supported, FALSE if not.
Chris@0 124 */
Chris@0 125 public function supportsRollback();
Chris@0 126
Chris@0 127 /**
Chris@0 128 * The rollback action for the last imported item.
Chris@0 129 *
Chris@0 130 * @return int
Chris@0 131 * The MigrateIdMapInterface::ROLLBACK_ constant indicating how an imported
Chris@0 132 * item should be handled on rollback.
Chris@0 133 */
Chris@0 134 public function rollbackAction();
Chris@0 135
Chris@0 136 /**
Chris@0 137 * Gets the destination module handling the destination data.
Chris@0 138 *
Chris@0 139 * @return string|null
Chris@0 140 * The destination module or NULL if not found.
Chris@0 141 */
Chris@0 142 public function getDestinationModule();
Chris@0 143
Chris@0 144 }