www.aleph1.co.uk 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 Migration API
  14  * @{
  15  * Overview of the Migration API, which migrates data into Drupal.
  16  *
  17  * @section overview Overview of migration
  18  * Migration is an
  19  * @link http://wikipedia.org/wiki/Extract,_transform,_load Extract, Transform, Load @endlink
  20  * (ETL) process. In the Drupal migration 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 "load" in ETL
  23  * means to load data into storage, while traditionally Drupal uses "load" to
  24  * mean load data from storage into memory.
  25  *
  26  * In the source phase, a set of data, called the row, is retrieved from the
  27  * data source, typically a database but it can be a CSV, JSON or XML file. The
  28  * row is sent to the process phase where it is transformed as needed by the
  29  * destination, or marked to be skipped. Processing can also determine that a
  30  * stub needs to be created, for example, if a term has a parent term that does
  31  * not yet exist. After processing the transformed row is passed to the
  32  * destination phase where it is loaded (saved) into the Drupal 8 site.
  33  *
  34  * The ETL process is configured by the migration plugin. The different phases:
  35  * source, process, and destination are also plugins, and are managed by the
  36  * Migration plugin. So there are four types of plugins in the migration
  37  * process: migration, source, process and destination.
  38  *
  39  * @section sec_migrations Migration plugins
  40  * Migration plugin definitions are stored in a module's 'migrations' directory.
  41  * For backwards compatibility we also scan the 'migration_templates' directory.
  42  * Examples of migration plugin definitions can be found in
  43  * 'core/modules/action/migration_templates'. The plugin class is
  44  * \Drupal\migrate\Plugin\Migration, with interface
  45  * \Drupal\migrate\Plugin\MigrationInterface. Migration plugins are managed by
  46  * the \Drupal\migrate\Plugin\MigrationPluginManager class. Migration plugins
  47  * are only available if the providers of their source plugins are installed.
  48  *
  49  * @section sec_source Source plugins
  50  * Migration source plugins implement
  51  * \Drupal\migrate\Plugin\MigrateSourceInterface and usually extend
  52  * \Drupal\migrate\Plugin\migrate\source\SourcePluginBase. They are annotated
  53  * with \Drupal\migrate\Annotation\MigrateSource annotation, and must be in
  54  * namespace subdirectory Plugin\migrate\source under the namespace of the
  55  * module that defines them. Migration source plugins are managed by the
  56  * \Drupal\migrate\Plugin\MigrateSourcePluginManager class. Source plugin
  57  * providers are determined by their and their parents namespaces.
  58  *
  59  * @section sec_process Process plugins
  60  * Migration process plugins implement
  61  * \Drupal\migrate\Plugin\MigrateProcessInterface and usually extend
  62  * \Drupal\migrate\ProcessPluginBase. They are annotated
  63  * with \Drupal\migrate\Annotation\MigrateProcessPlugin annotation, and must be
  64  * in namespace subdirectory Plugin\migrate\process under the namespace of the
  65  * module that defines them. Migration process plugins are managed by the
  66  * \Drupal\migrate\Plugin\MigratePluginManager class. The Migrate module
  67  * provides process plugins for common operations (setting default values,
  68  * mapping values, etc.).
  69  *
  70  * @section sec_destination Destination plugins
  71  * Migration destination plugins implement
  72  * \Drupal\migrate\Plugin\MigrateDestinationInterface and usually extend
  73  * \Drupal\migrate\Plugin\migrate\destination\DestinationBase. They are
  74  * annotated with \Drupal\migrate\Annotation\MigrateDestination annotation, and
  75  * must be in namespace subdirectory Plugin\migrate\destination under the
  76  * namespace of the module that defines them. Migration destination plugins
  77  * are managed by the \Drupal\migrate\Plugin\MigrateDestinationPluginManager
  78  * class. The Migrate module provides destination plugins for Drupal core
  79  * objects (configuration and entity).
  80  *
  81  * @section sec_more_info More information
  82  * @link https://www.drupal.org/node/2127611 Migration API documentation. @endlink
  83  *
  84  * @see update_api
  85  * @}
  86  */
  87
  88 /**
  89  * @addtogroup hooks
  90  * @{
  91  */
  92
  93 /**
  94  * Allows adding data to a row before processing it.
  95  *
  96  * For example, filter module used to store filter format settings in the
  97  * variables table which now needs to be inside the filter format config
  98  * file. So, it needs to be added here.
  99  *
 100  * hook_migrate_MIGRATION_ID_prepare_row() is also available.
 101  *
 102  * @ingroup migration
 103  */
 104 function hook_migrate_prepare_row(Row $row, MigrateSourceInterface $source, MigrationInterface $migration) {
 105   if ($migration->id() == 'd6_filter_formats') {
 106     $value = $source->getDatabase()->query('SELECT value FROM {variable} WHERE name = :name', [':name' => 'mymodule_filter_foo_' . $row->getSourceProperty('format')])->fetchField();
 107     if ($value) {
 108       $row->setSourceProperty('settings:mymodule:foo', unserialize($value));
 109     }
 110   }
 111 }
 112
 113 /**
 114  * Allows altering the list of discovered migration plugins.
 115  *
 116  * Modules are able to alter specific migrations structures or even remove or
 117  * append additional migrations to the discovery. For example, this
 118  * implementation filters out Drupal 6 migrations from the discovered migration
 119  * list. This is done by checking the migration tags.
 120  *
 121  * @param array[] $migrations
 122  *   An associative array of migrations keyed by migration ID. Each value is the
 123  *   migration array, obtained by decoding the migration YAML file and enriched
 124  *   with some meta information added during discovery phase, like migration
 125  *   'class', 'provider' or '_discovered_file_path'.
 126  *
 127  * @ingroup migration
 128  */
 129 function hook_migration_plugins_alter(array &$migrations) {
 130   $migrations = array_filter($migrations, function (array $migration) {
 131     $tags = isset($migration['migration_tags']) ? (array) $migration['migration_tags'] : [];
 132     return !in_array('Drupal 6', $tags);
 133   });
 134 }
 135
 136 /**
 137  * @} End of "addtogroup hooks".
 138  */