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 */
|