Upgrader - Implement addSimpleExtensionTask(). Update docblocks.

diff --git a/CRM/Upgrade/Incremental/Base.php b/CRM/Upgrade/Incremental/Base.php
index d1c767dba4e84616a4196f6be3d72907d54ad056..e88b61dc9f3efad5fb1415ffb2317bd86484f0e0 100644 (file)
--- a/CRM/Upgrade/Incremental/Base.php
+++ b/CRM/Upgrade/Incremental/Base.php
@@ -188,8 +188,13 @@ class CRM_Upgrade_Incremental_Base {
   }
 
   /**
-   * Add a task to activate an extension. This task will run post-upgrade (after all
-   * changes to core DB are settled).
+   * Add a task to activate an extension. It will use the full, normal installation process
+   * (invoking `hook_install`, `hook_enable`, and so on). To ensure that the installation process
+   * can rely on regular core services and APIs, it will run after the core-upgrade-steps.
+   *
+   * This is more suited to green-field extensions (which started life as an extension).
+   * If you have a brown-field extension which doesn't have install-logic (i.e. it arises from
+   * rearranging pre-existing core-core functionality), then consider `addSimpleExtensionTask()`.
    *
    * @param string $title
    * @param string[] $keys
@@ -206,6 +211,24 @@ class CRM_Upgrade_Incremental_Base {
     );
   }
 
+  /**
+   * Add a task to activate an extension. It will use a simple (low-tech) installation process
+   * (skipping events like `hook_install`; instead, it merely updates `civicrm_extension` and
+   * `CRM_Extension_ClassLoader`). The extension should not now (or in the future) use
+   * `hook_install`. Simple installations can run at any point during the upgrade process.
+   *
+   * This is more suited to brown-field extensions (which arise from rearranging pre-existing
+   * core-core functionality). If you have a green-field extension (which has always been an
+   * extension), then consider `addExtensionTask()` instead.
+   *
+   * @param string $title
+   * @param string|string[] $keys
+   *   List of extensions to enable.
+   */
+  protected function addSimpleExtensionTask(string $title, $keys): void {
+    $this->addTask($title, 'enableSimpleExtension', $keys);
+  }
+
   /**
    * This callback is used to enable one or more extensions which have no install or upgrade code,
    * and whose autoloaders are needed right away.