From 8985d47e304fc6095593633ad4041577836ac348 Mon Sep 17 00:00:00 2001
From: Tim Otten <totten@civicrm.org>
Date: Thu, 19 May 2022 22:20:18 -0700
Subject: [PATCH] CRM/Upgrade - Add basic support for snapshots to the upgrade
 framework

---
 CRM/Upgrade/Form.php                |  9 +++++++++
 CRM/Upgrade/Incremental/Base.php    | 30 +++++++++++++++++++++++++++++
 CRM/Upgrade/Incremental/General.php | 13 +++++++++++++
 3 files changed, 52 insertions(+)

diff --git a/CRM/Upgrade/Form.php b/CRM/Upgrade/Form.php
index 18acacd007..cc8c8d4352 100644
--- a/CRM/Upgrade/Form.php
+++ b/CRM/Upgrade/Form.php
@@ -536,6 +536,15 @@ SET    version = '$version'
     );
     $queue->createItem($task, ['weight' => 0]);
 
+    if (empty(CRM_Upgrade_Snapshot::getActivationIssues())) {
+      $task = new CRM_Queue_Task(
+        ['CRM_Upgrade_Snapshot', 'cleanupTask'],
+        [],
+        "Cleanup old upgrade snapshots"
+      );
+      $queue->createItem($task, ['weight' => 0]);
+    }
+
     $task = new CRM_Queue_Task(
       ['CRM_Upgrade_Form', 'disableOldExtensions'],
       [$postUpgradeMessageFile],
diff --git a/CRM/Upgrade/Incremental/Base.php b/CRM/Upgrade/Incremental/Base.php
index 7e8cae3aed..b4e3b567ca 100644
--- a/CRM/Upgrade/Incremental/Base.php
+++ b/CRM/Upgrade/Incremental/Base.php
@@ -158,6 +158,36 @@ class CRM_Upgrade_Incremental_Base {
     $queue->createItem($task, ['weight' => -1]);
   }
 
+  /**
+   * Add a task to store a snapshot of some data (if upgrade-snapshots are supported).
+   *
+   * If there is a large amount of data, this may actually add multiple tasks.
+   *
+   * Ex :$this->addSnapshotTask('event_dates', CRM_Utils_SQL_Select::from('civicrm_event')
+   *      ->select('id, start_date, end_date'));
+   *
+   * @param string $name
+   *   Logical name for the snapshot. This will become part of the table.
+   * @param \CRM_Utils_SQL_Select $select
+   * @throws \CRM_Core_Exception
+   */
+  protected function addSnapshotTask(string $name, CRM_Utils_SQL_Select $select): void {
+    if (!preg_match(';^[a-z0-9_]+$;', $name)) {
+      throw new \CRM_Core_Exception("Malformed snapshot name: $name");
+    }
+    if (!empty(CRM_Upgrade_Snapshot::getActivationIssues())) {
+      return;
+    }
+
+    $queue = CRM_Queue_Service::singleton()->load([
+      'type' => 'Sql',
+      'name' => CRM_Upgrade_Form::QUEUE_NAME,
+    ]);
+    foreach (CRM_Upgrade_Snapshot::createTasks($this->getMajorMinor(), $name, $select) as $task) {
+      $queue->createItem($task, ['weight' => -1]);
+    }
+  }
+
   /**
    * Add a task to activate an extension. This task will run post-upgrade (after all
    * changes to core DB are settled).
diff --git a/CRM/Upgrade/Incremental/General.php b/CRM/Upgrade/Incremental/General.php
index 3b95537b40..e8880665fe 100644
--- a/CRM/Upgrade/Incremental/General.php
+++ b/CRM/Upgrade/Incremental/General.php
@@ -129,6 +129,19 @@ class CRM_Upgrade_Incremental_General {
         2 => 'https://github.com/JMAConsulting/biz.jmaconsulting.financialaclreport',
       ]);
     }
+
+    $snapshotIssues = CRM_Upgrade_Snapshot::getActivationIssues();
+    if ($snapshotIssues) {
+      $preUpgradeMessage .= '<details>';
+      $preUpgradeMessage .= '<summary>' . ts('This upgrade will NOT use automatic snapshots.') . '</summary>';
+      $preUpgradeMessage .= '<p>' . ts('If an upgrade problem is discovered in the future, automatic snapshots may help recover. However, they also require additional storage and may not be available or appropriate in all configurations.') . '</p>';
+      $preUpgradeMessage .= ts('Here are the reasons why automatic snapshots are disabled:');
+      $preUpgradeMessage .= '<ul>' . implode("", array_map(
+          function($issue) {
+            return sprintf('<li>%s</li>', $issue);
+          }, $snapshotIssues)) . '</ul>';
+      $preUpgradeMessage .= '</details>';
+    }
   }
 
   /**
-- 
2.25.1