annotate core/modules/migrate/migrate.api.php @ 19:fa3358dc1485 tip

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