yaffs.net Git - yaffs-website/blob - web/core/modules/migrate/migrate.api.php

   1 <?php
   2
   3 /**
   4  * @file
   5  * Hooks provided by the Migrate module.
   6  */
   7
   8 use Drupal\migrate\Plugin\MigrationInterface;
   9 use Drupal\migrate\Plugin\MigrateSourceInterface;
  10 use Drupal\migrate\Row;
  11
  12 /**
  13  * @defgroup migration Migrate API
  14  * @{
  15  * Overview of the Migrate API, which migrates data into Drupal.
  16  *
  17  * @section overview Overview of a migration
  18  * Migration is an
  19  * @link http://wikipedia.org/wiki/Extract,_transform,_load Extract, Transform, Load @endlink
  20  * (ETL) process. In the Drupal Migrate API, the extract phase is called
  21  * 'source', the transform phase is called 'process', and the load phase is
  22  * called 'destination'. It is important to understand that the term 'load' in
  23  * ETL refers to loading data into the storage while in a typical Drupal context
  24  * the term 'load' refers to loading data from storage.
  25  *
  26  * In the source phase, a set of data, called the row, is retrieved from the
  27  * data source. The data can be migrated from a database, loaded from a file
  28  * (for example CSV, JSON or XML) or fetched from a web service (for example RSS
  29  * or REST). The row is sent to the process phase where it is transformed as
  30  * needed or marked to be skipped. Processing can also determine if a 'stub'
  31  * needs to be created. For example, if a term has a parent term which hasn't
  32  * been migrated yet, a stub term is created so that the parent relation can be
  33  * established, and the stub is updated at a later point. After processing, the
  34  * transformed row is passed to the destination phase where it is loaded (saved)
  35  * into the target Drupal site.
  36  *
  37  * Migrate API uses the Drupal plugin system for many different purposes. Most
  38  * importantly, the overall ETL process is defined as a migration plugin and the
  39  * three phases (source, process and destination) have their own plugin types.
  40  *
  41  * @section sec_migrations Migrate API migration plugins
  42  * Migration plugin definitions are stored in a module's 'migrations' directory.
  43  * The plugin class is \Drupal\migrate\Plugin\Migration, with interface
  44  * \Drupal\migrate\Plugin\MigrationInterface. Migration plugins are managed by
  45  * the \Drupal\migrate\Plugin\MigrationPluginManager class. Migration plugins
  46  * are only available if the providers of their source plugins are installed.
  47  *
  48  * @link https://www.drupal.org/docs/8/api/migrate-api/migrate-destination-plugins-examples Example migrations in Migrate API handbook. @endlink
  49  *
  50  * @section sec_source Migrate API source plugins
  51  * Migrate API source plugins implement
  52  * \Drupal\migrate\Plugin\MigrateSourceInterface and usually extend
  53  * \Drupal\migrate\Plugin\migrate\source\SourcePluginBase. They are annotated
  54  * with \Drupal\migrate\Annotation\MigrateSource annotation and must be in
  55  * namespace subdirectory 'Plugin\migrate\source' under the namespace of the
  56  * module that defines them. Migrate API source plugins are managed by the
  57  * \Drupal\migrate\Plugin\MigrateSourcePluginManager class.
  58  *
  59  * @link https://api.drupal.org/api/drupal/namespace/Drupal!migrate!Plugin!migrate!source List of source plugins provided by the core Migrate module. @endlink
  60  * @link https://www.drupal.org/docs/8/api/migrate-api/migrate-source-plugins Core and contributed source plugin usage examples in Migrate API handbook. @endlink
  61  *
  62  * @section sec_process Migrate API process plugins
  63  * Migrate API process plugins implement
  64  * \Drupal\migrate\Plugin\MigrateProcessInterface and usually extend
  65  * \Drupal\migrate\ProcessPluginBase. They are annotated with
  66  * \Drupal\migrate\Annotation\MigrateProcessPlugin annotation and must be in
  67  * namespace subdirectory 'Plugin\migrate\process' under the namespace of the
  68  * module that defines them. Migrate API process plugins are managed by the
  69  * \Drupal\migrate\Plugin\MigratePluginManager class.
  70  *
  71  * @link https://api.drupal.org/api/drupal/namespace/Drupal!migrate!Plugin!migrate!process List of process plugins for common operations provided by the core Migrate module. @endlink
  72  *
  73  * @section sec_destination Migrate API destination plugins
  74  * Migrate API destination plugins implement
  75  * \Drupal\migrate\Plugin\MigrateDestinationInterface and usually extend
  76  * \Drupal\migrate\Plugin\migrate\destination\DestinationBase. They are
  77  * annotated with \Drupal\migrate\Annotation\MigrateDestination annotation and
  78  * must be in namespace subdirectory 'Plugin\migrate\destination' under the
  79  * namespace of the module that defines them. Migrate API destination plugins
  80  * are managed by the \Drupal\migrate\Plugin\MigrateDestinationPluginManager
  81  * class.
  82  *
  83  * @link https://api.drupal.org/api/drupal/namespace/Drupal!migrate!Plugin!migrate!destination List of destination plugins for Drupal configuration and content entities provided by the core Migrate module. @endlink
  84  *
  85  * @section sec_more_info Documentation handbooks
  86  * @link https://www.drupal.org/docs/8/api/migrate-api Migrate API handbook. @endlink
  87  * @link https://www.drupal.org/docs/8/upgrade Upgrading to Drupal 8 handbook. @endlink
  88  * @}
  89  */
  90
  91 /**
  92  * @addtogroup hooks
  93  * @{
  94  */
  95
  96 /**
  97  * Allows adding data to a row before processing it.
  98  *
  99  * For example, filter module used to store filter format settings in the
 100  * variables table which now needs to be inside the filter format config
 101  * file. So, it needs to be added here.
 102  *
 103  * hook_migrate_MIGRATION_ID_prepare_row() is also available.
 104  *
 105  * @param \Drupal\migrate\Row $row
 106  *   The row being imported.
 107  * @param \Drupal\migrate\Plugin\MigrateSourceInterface $source
 108  *   The source migration.
 109  * @param \Drupal\migrate\Plugin\MigrationInterface $migration
 110  *   The current migration.
 111  *
 112  * @ingroup migration
 113  */
 114 function hook_migrate_prepare_row(Row $row, MigrateSourceInterface $source, MigrationInterface $migration) {
 115   if ($migration->id() == 'd6_filter_formats') {
 116     $value = $source->getDatabase()->query('SELECT value FROM {variable} WHERE name = :name', [':name' => 'mymodule_filter_foo_' . $row->getSourceProperty('format')])->fetchField();
 117     if ($value) {
 118       $row->setSourceProperty('settings:mymodule:foo', unserialize($value));
 119     }
 120   }
 121 }
 122
 123 /**
 124  * Allows adding data to a row for a migration with the specified ID.
 125  *
 126  * This provides the same functionality as hook_migrate_prepare_row() but
 127  * removes the need to check the value of $migration->id().
 128  *
 129  * @param \Drupal\migrate\Row $row
 130  *   The row being imported.
 131  * @param \Drupal\migrate\Plugin\MigrateSourceInterface $source
 132  *   The source migration.
 133  * @param \Drupal\migrate\Plugin\MigrationInterface $migration
 134  *   The current migration.
 135  *
 136  * @ingroup migration
 137  */
 138 function hook_migrate_MIGRATION_ID_prepare_row(Row $row, MigrateSourceInterface $source, MigrationInterface $migration) {
 139   $value = $source->getDatabase()->query('SELECT value FROM {variable} WHERE name = :name', [':name' => 'mymodule_filter_foo_' . $row->getSourceProperty('format')])->fetchField();
 140   if ($value) {
 141     $row->setSourceProperty('settings:mymodule:foo', unserialize($value));
 142   }
 143 }
 144
 145 /**
 146  * Allows altering the list of discovered migration plugins.
 147  *
 148  * Modules are able to alter specific migrations structures or even remove or
 149  * append additional migrations to the discovery. For example, this
 150  * implementation filters out Drupal 6 migrations from the discovered migration
 151  * list. This is done by checking the migration tags.
 152  *
 153  * @param array[] $migrations
 154  *   An associative array of migrations keyed by migration ID. Each value is the
 155  *   migration array, obtained by decoding the migration YAML file and enriched
 156  *   with some meta information added during discovery phase, like migration
 157  *   'class', 'provider' or '_discovered_file_path'.
 158  *
 159  * @ingroup migration
 160  */
 161 function hook_migration_plugins_alter(array &$migrations) {
 162   $migrations = array_filter($migrations, function (array $migration) {
 163     $tags = isset($migration['migration_tags']) ? (array) $migration['migration_tags'] : [];
 164     return !in_array('Drupal 6', $tags);
 165   });
 166 }
 167
 168 /**
 169  * @} End of "addtogroup hooks".
 170  */