From 94d4445eddf32f0d434c95d5fa3d85df61ad1205 Mon Sep 17 00:00:00 2001
From: Eileen McNaughton <emcnaughton@wikimedia.org>
Date: Mon, 20 Mar 2023 23:43:19 +1300
Subject: [PATCH] dev/core#3514 Define hook to alter data once it has been
 mapped but before work is done on it.

---
 CRM/Contribute/Import/Parser/Contribution.php | 21 +++++++++++++++
 CRM/Utils/Hook.php                            | 27 +++++++++++++++++++
 .../Member/Import/Parser/MembershipTest.php   |  2 --
 3 files changed, 48 insertions(+), 2 deletions(-)

diff --git a/CRM/Contribute/Import/Parser/Contribution.php b/CRM/Contribute/Import/Parser/Contribution.php
index b0dd2a59f0..7dfcbd8700 100644
--- a/CRM/Contribute/Import/Parser/Contribution.php
+++ b/CRM/Contribute/Import/Parser/Contribution.php
@@ -204,6 +204,25 @@ class CRM_Contribute_Import_Parser_Contribution extends CRM_Import_Parser {
     return $array;
   }
 
+  /**
+   * Validate the import values.
+   *
+   * This overrides the parent to call the hook - cos the other imports are not
+   * yet stable enough to add the hook to. If we add the hook to them now and then
+   * later switch them to APIv4 style keys we will have to worry about hook consumers.
+   *
+   * The values array represents a row in the datasource.
+   *
+   * @param array $values
+   *
+   * @throws \CRM_Core_Exception
+   */
+  public function validateValues(array $values): void {
+    $params = $this->getMappedRow($values);
+    CRM_Utils_Hook::importAlterMappedRow('validate', 'contribution_import', $params, $values, $this->getUserJobID());
+    $this->validateParams($params);
+  }
+
   /**
    * Override parent to cope with params being separated by entity already.
    *
@@ -397,6 +416,8 @@ class CRM_Contribute_Import_Parser_Contribution extends CRM_Import_Parser {
     $rowNumber = (int) ($values[array_key_last($values)]);
     try {
       $params = $this->getMappedRow($values);
+      CRM_Utils_Hook::importAlterMappedRow('import', 'contribution_import', $params, $values, $this->getUserJobID());
+
       $contributionParams = $params['Contribution'];
       //CRM-10994
       if (isset($contributionParams['total_amount']) && $contributionParams['total_amount'] == 0) {
diff --git a/CRM/Utils/Hook.php b/CRM/Utils/Hook.php
index 724a7fe42d..f6ad4278cf 100644
--- a/CRM/Utils/Hook.php
+++ b/CRM/Utils/Hook.php
@@ -1611,6 +1611,8 @@ abstract class CRM_Utils_Hook {
    * This hook is called after a row has been processed and the
    * record (and associated records imported
    *
+   * @deprecated
+   *
    * @param string $object
    *   Object being imported (for now Contact only, later Contribution, Activity,.
    *                               Participant and Member)
@@ -1636,6 +1638,31 @@ abstract class CRM_Utils_Hook {
     );
   }
 
+  /**
+   * Alter import mappings.
+   *
+   * @param string $importType This corresponds to the value in `civicrm_user_job.job_type`.
+   * @param string $context import or validate.
+   *   In validate context only 'cheap' lookups should be done (e.g. using cached information).
+   *   Validate is intended to quickly process a whole file for errors. You should focus on
+   *   setting or unsetting key values to or from `'invalid_import_value'`.
+   *
+   *   During import mode heavier lookups can be done (e.g using custom logic to find the
+   *   relevant contact) as this is then passed to the api functions. If a row is invalid during
+   *   import mode you should throw an exception.
+   * @param array $mappedRow (reference) The rows that have been mapped to an array of params.
+   * @param array $rowValues The row from the data source (non-associative array)
+   * @param int $userJobID id from civicrm_user_job
+   *
+   * @return mixed
+   */
+  public static function importAlterMappedRow(string $importType, string $context, array &$mappedRow, array $rowValues, int $userJobID) {
+    $null = NULL;
+    return self::singleton()->invoke(['importType', 'context', 'mappedRow', 'rowValues', 'userJobID', 'fieldMappings'], $context, $importType, $mappedRow, $rowValues, $userJobID, $null,
+      'civicrm_importAlterMappedRow'
+    );
+  }
+
   /**
    * This hook is called when API permissions are checked (cf. civicrm_api3_api_check_permission()
    * in api/v3/utils.php and _civicrm_api3_permissions() in CRM/Core/DAO/permissions.php).
diff --git a/tests/phpunit/CRM/Member/Import/Parser/MembershipTest.php b/tests/phpunit/CRM/Member/Import/Parser/MembershipTest.php
index 013e8f7c2a..d724395772 100644
--- a/tests/phpunit/CRM/Member/Import/Parser/MembershipTest.php
+++ b/tests/phpunit/CRM/Member/Import/Parser/MembershipTest.php
@@ -370,8 +370,6 @@ class CRM_Member_Import_Parser_MembershipTest extends CiviUnitTestCase {
 
   /**
    * Test importing to a custom field.
-   *
-   * @throws \CRM_Core_Exception
    */
   public function testImportCustomData(): void {
     $donaldDuckID = $this->individualCreate(['first_name' => 'Donald', 'last_name' => 'Duck']);
-- 
2.25.1