migrate.api.php 7.01 KB
Newer Older
1
2
<?php

3
4
5
6
7
/**
 * @file
 * Hooks provided by the Migrate module.
 */

8
use Drupal\migrate\Plugin\MigrationInterface;
9
10
11
12
use Drupal\migrate\Plugin\MigrateSourceInterface;
use Drupal\migrate\Row;

/**
13
14
15
16
17
18
19
 * @defgroup migration Migration API
 * @{
 * Overview of the Migration API, which migrates data into Drupal.
 *
 * @section overview Overview of migration
 * Migration is an
 * @link http://wikipedia.org/wiki/Extract,_transform,_load Extract, Transform, Load @endlink
20
21
22
23
24
 * (ETL) process. In the Drupal migration API the extract phase is called
 * "source", the transform phase is called "process", and the load phase is
 * called "destination". It is important to understand that the "load" in ETL
 * means to load data into storage, while traditionally Drupal uses "load" to
 * mean load data from storage into memory.
25
 *
26
27
28
29
30
31
32
 * In the source phase, a set of data, called the row, is retrieved from the
 * data source, typically a database but it can be a CSV, JSON or XML file. The
 * row is sent to the process phase where it is transformed as needed by the
 * destination, or marked to be skipped. Processing can also determine that a
 * stub needs to be created, for example, if a term has a parent term that does
 * not yet exist. After processing the transformed row is passed to the
 * destination phase where it is loaded (saved) into the Drupal 8 site.
33
 *
34
35
36
37
 * The ETL process is configured by the migration plugin. The different phases:
 * source, process, and destination are also plugins, and are managed by the
 * Migration plugin. So there are four types of plugins in the migration
 * process: migration, source, process and destination.
38
 *
39
40
41
 * @section sec_migrations Migration plugins
 * Migration plugin definitions are stored in a module's 'migrations' directory.
 * Examples of migration plugin definitions can be found in
42
 * 'core/modules/action/migrations'. The plugin class is
43
44
 * \Drupal\migrate\Plugin\Migration, with interface
 * \Drupal\migrate\Plugin\MigrationInterface. Migration plugins are managed by
45
46
 * the \Drupal\migrate\Plugin\MigrationPluginManager class. Migration plugins
 * are only available if the providers of their source plugins are installed.
47
48
49
50
51
52
53
54
 *
 * @section sec_source Source plugins
 * Migration source plugins implement
 * \Drupal\migrate\Plugin\MigrateSourceInterface and usually extend
 * \Drupal\migrate\Plugin\migrate\source\SourcePluginBase. They are annotated
 * with \Drupal\migrate\Annotation\MigrateSource annotation, and must be in
 * namespace subdirectory Plugin\migrate\source under the namespace of the
 * module that defines them. Migration source plugins are managed by the
55
56
 * \Drupal\migrate\Plugin\MigrateSourcePluginManager class. Source plugin
 * providers are determined by their and their parents namespaces.
57
58
59
60
61
62
63
64
 *
 * @section sec_process Process plugins
 * Migration process plugins implement
 * \Drupal\migrate\Plugin\MigrateProcessInterface and usually extend
 * \Drupal\migrate\ProcessPluginBase. They are annotated
 * with \Drupal\migrate\Annotation\MigrateProcessPlugin annotation, and must be
 * in namespace subdirectory Plugin\migrate\process under the namespace of the
 * module that defines them. Migration process plugins are managed by the
65
66
67
 * \Drupal\migrate\Plugin\MigratePluginManager class. The Migrate module
 * provides process plugins for common operations (setting default values,
 * mapping values, etc.).
68
69
70
71
72
73
74
75
 *
 * @section sec_destination Destination plugins
 * Migration destination plugins implement
 * \Drupal\migrate\Plugin\MigrateDestinationInterface and usually extend
 * \Drupal\migrate\Plugin\migrate\destination\DestinationBase. They are
 * annotated with \Drupal\migrate\Annotation\MigrateDestination annotation, and
 * must be in namespace subdirectory Plugin\migrate\destination under the
 * namespace of the module that defines them. Migration destination plugins
76
77
78
 * are managed by the \Drupal\migrate\Plugin\MigrateDestinationPluginManager
 * class. The Migrate module provides destination plugins for Drupal core
 * objects (configuration and entity).
79
 *
80
81
 * @section sec_more_info More information
 * @link https://www.drupal.org/node/2127611 Migration API documentation. @endlink
82
83
 *
 * @see update_api
84
 * @}
85
86
87
88
89
90
91
92
93
94
95
96
97
98
 */

/**
 * @addtogroup hooks
 * @{
 */

/**
 * Allows adding data to a row before processing it.
 *
 * For example, filter module used to store filter format settings in the
 * variables table which now needs to be inside the filter format config
 * file. So, it needs to be added here.
 *
99
100
 * hook_migrate_MIGRATION_ID_prepare_row() is also available.
 *
101
102
103
104
105
106
107
 * @param \Drupal\migrate\Row $row
 *   The row being imported.
 * @param \Drupal\migrate\Plugin\MigrateSourceInterface $source
 *   The source migration.
 * @param \Drupal\migrate\Plugin\MigrationInterface $migration
 *   The current migration.
 *
108
 * @ingroup migration
109
110
 */
function hook_migrate_prepare_row(Row $row, MigrateSourceInterface $source, MigrationInterface $migration) {
111
  if ($migration->id() == 'd6_filter_formats') {
112
    $value = $source->getDatabase()->query('SELECT value FROM {variable} WHERE name = :name', [':name' => 'mymodule_filter_foo_' . $row->getSourceProperty('format')])->fetchField();
113
114
115
116
    if ($value) {
      $row->setSourceProperty('settings:mymodule:foo', unserialize($value));
    }
  }
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
}

/**
 * Allows adding data to a row for a migration with the specified ID.
 *
 * This provides the same functionality as hook_migrate_prepare_row() but
 * removes the need to check the value of $migration->id().
 *
 * @param \Drupal\migrate\Row $row
 *   The row being imported.
 * @param \Drupal\migrate\Plugin\MigrateSourceInterface $source
 *   The source migration.
 * @param \Drupal\migrate\Plugin\MigrationInterface $migration
 *   The current migration.
 *
 * @ingroup migration
 */
function hook_migrate_MIGRATION_ID_prepare_row(Row $row, MigrateSourceInterface $source, MigrationInterface $migration) {
  $value = $source->getDatabase()->query('SELECT value FROM {variable} WHERE name = :name', [':name' => 'mymodule_filter_foo_' . $row->getSourceProperty('format')])->fetchField();
  if ($value) {
    $row->setSourceProperty('settings:mymodule:foo', unserialize($value));
  }
139
140
}

141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
/**
 * Allows altering the list of discovered migration plugins.
 *
 * Modules are able to alter specific migrations structures or even remove or
 * append additional migrations to the discovery. For example, this
 * implementation filters out Drupal 6 migrations from the discovered migration
 * list. This is done by checking the migration tags.
 *
 * @param array[] $migrations
 *   An associative array of migrations keyed by migration ID. Each value is the
 *   migration array, obtained by decoding the migration YAML file and enriched
 *   with some meta information added during discovery phase, like migration
 *   'class', 'provider' or '_discovered_file_path'.
 *
 * @ingroup migration
 */
function hook_migration_plugins_alter(array &$migrations) {
  $migrations = array_filter($migrations, function (array $migration) {
    $tags = isset($migration['migration_tags']) ? (array) $migration['migration_tags'] : [];
    return !in_array('Drupal 6', $tags);
  });
}

164
165
166
/**
 * @} End of "addtogroup hooks".
 */