From 372a1fe0b78cb8fca7321aa088093db8d381869e Mon Sep 17 00:00:00 2001
From: Alex Pott <alex.a.pott@googlemail.com>
Date: Mon, 24 Jan 2022 23:44:17 +0000
Subject: [PATCH] Issue #3226401 by quietone, joachim, huzooka: Add
documentation of migration yml files
(cherry picked from commit ce85149c33679b657a3fe6f43e36b585c2a3827d)
---
core/modules/migrate/src/Plugin/Migration.php | 82 ++++++++++++++++++-
1 file changed, 79 insertions(+), 3 deletions(-)
diff --git a/core/modules/migrate/src/Plugin/Migration.php b/core/modules/migrate/src/Plugin/Migration.php
index 0891311cfa46..01ae6aea583c 100644
--- a/core/modules/migrate/src/Plugin/Migration.php
+++ b/core/modules/migrate/src/Plugin/Migration.php
@@ -15,9 +15,85 @@
/**
* Defines the Migration plugin.
*
- * The migration plugin represents one single migration and acts like a
- * container for the information about a single migration such as the source,
- * process and destination plugins.
+ * A migration plugin instance that represents one single migration and acts
+ * like a container for the information about a single migration such as the
+ * source, process and destination plugins.
+ *
+ * The configuration of a migration is defined using YAML format and placed in
+ * the directory MODULENAME/migrations.
+ *
+ * Available definition keys:
+ * - id: The migration ID.
+ * - label: The human-readable label for the migration.
+ * - source: The definition for a migrate source plugin.
+ * - process: The definition for the migrate process pipelines for the
+ * destination properties.
+ * - destination: The definition a migrate destination plugin.
+ * - audit: (optional) Audit the migration for conflicts with existing content.
+ * - deriver: (optional) The fully qualified path to a deriver class.
+ * - idMap: (optional) The definition for a migrate idMap plugin.
+ * - migration_dependencies: (optional) An array with two keys 'required' and
+ * 'optional' listing the migrations that this migration depends on. The
+ * required migrations must be run first and completed successfully. The
+ * optional migrations will be executed if they are present.
+ * - migration_tags: (optional) An array of tags for this migration.
+ * - provider: (optional) The name of the module that provides the plugin.
+ *
+ * Example with all keys:
+ *
+ * @code
+ * id: d7_taxonomy_term_example
+ * label: Taxonomy terms
+ * audit: true
+ * migration_tags:
+ * - Drupal 7
+ * - Content
+ * - Term example
+ * deriver: Drupal\taxonomy\Plugin\migrate\D7TaxonomyTermDeriver
+ * provider: custom_module
+ * source:
+ * plugin: d7_taxonomy_term
+ * process:
+ * tid: tid
+ * vid:
+ * plugin: migration_lookup
+ * migration: d7_taxonomy_vocabulary
+ * source: vid
+ * name: name
+ * 'description/value': description
+ * 'description/format': format
+ * weight: weight
+ * parent_id:
+ * -
+ * plugin: skip_on_empty
+ * method: process
+ * source: parent
+ * -
+ * plugin: migration_lookup
+ * migration: d7_taxonomy_term
+ * parent:
+ * plugin: default_value
+ * default_value: 0
+ * source: '@parent_id'
+ * destination:
+ * plugin: entity:taxonomy_term
+ * migration_dependencies:
+ * required:
+ * - d7_taxonomy_vocabulary
+ * optional:
+ * - d7_field_instance
+ * @endcode
+ *
+ * For additional configuration keys, refer to these Migrate classes.
+ *
+ * @see \Drupal\migrate\Plugin\migrate\source\SourcePluginBase
+ * @see \Drupal\migrate\Plugin\migrate\source\SqlBase
+ * @see \Drupal\migrate\Plugin\migrate\destination\Config
+ * @see \Drupal\migrate\Plugin\migrate\destination\EntityConfigBase
+ * @see \Drupal\migrate\Plugin\migrate\destination\EntityContentBase
+ * @see \Drupal\Core\Plugin\PluginBase
+ *
+ * @link https://www.drupal.org/docs/8/api/migrate-api Migrate API handbook. @endlink
*/
class Migration extends PluginBase implements MigrationInterface, RequirementsInterface, ContainerFactoryPluginInterface {
--
GitLab