From 98f781e1fd77ad1c39855acfb7b50f61dd0cad44 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?benjamin=20melan=C3=A7on?= <ben@agaric.coop>
Date: Thu, 16 Nov 2023 11:35:30 -0500
Subject: [PATCH] Add help info in an API file

---
 migration_helpers.api.php | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)
 create mode 100644 migration_helpers.api.php

diff --git a/migration_helpers.api.php b/migration_helpers.api.php
new file mode 100644
index 0000000..22b6e79
--- /dev/null
+++ b/migration_helpers.api.php
@@ -0,0 +1,38 @@
+<?php
+
+/**
+ * @file
+ * Examples of how to use migration_helpers functions.
+ */
+
+/**
+ * Rename and move select terms to new vocabulary and term reference field.
+ *
+ * Here we move select terms from the deprecated 'Design sector' vocabulary
+ * (note the source vocabulary does not get specified, as we are only moving
+ * terms that are referenced by the chosen entity type (defaults to node) and
+ * bundle) from the design_type field into the new Focus Areas vocabulary which
+ * is referenced by `field_focus`.  We rename three of the terms and explicitly
+ * discard four others.  Any we do not put in the mapping will be brought in
+ * with their current name.  This does not currently copy over term description
+ * or anything else, only term label.  Perhaps it could be reworked to be both
+ * more generic and more powerful with an entity clone.
+ */
+function example_deploy_design_sector_to_focus_area() {
+  $mapping = [
+    'Memorial' => 'Public Memory',
+    'Housing' => 'Social Cohesion',
+    'Health' => 'Health Equity',
+    'Education' => FALSE,
+    'Equity' => FALSE,
+    'Office Space' => FALSE,
+    'Other' => FALSE,
+  ];
+  migration_helpers_move_terms(
+    destination_vocabulary: 'focus_area',
+    source_field: 'field_design_type',
+    destination_field: 'field_focus',
+    bundle: 'work',
+    mapping: $mapping,
+  );
+}