dev/core#2547 - Add base-upgrader to core

CRM/Extension/Info.php

@@ -65,6 +65,13 @@ class CRM_Extension_Info {
    */
   public $maintainer = NULL;
 
+  /**
+   * @var string|null
+   *  The name of a class which handles the install/upgrade lifecycle.
+   * @see \CRM_Extension_Upgrader_Interface
+   */
+  public $upgrader = NULL;
+
   /**
    * Load extension info an XML file.
    *
@@ -150,6 +157,7 @@ public function parse($info) {
     $this->type = (string) $info->attributes()->type;
     $this->file = (string) $info->file;
     $this->label = (string) $info->name;
+    $this->upgrader = (string) $info->upgrader;
 
     // Convert first level variables to CRM_Core_Extension properties
     // and deeper into arrays. An exception for URLS section, since

CRM/Extension/Manager/Module.php

@@ -60,6 +60,9 @@ private function callHook(CRM_Extension_Info $info, $hookName) {
     if (function_exists($fnName)) {
       $fnName();
     }
+    if ($info->upgrader) {
+      $this->mapper->getUpgrader($info->key)->notify($hookName);
+    }
   }
 
   /**

CRM/Extension/Mapper.php

@@ -66,6 +66,12 @@ class CRM_Extension_Mapper {
 
   protected $civicrmUrl;
 
+  /**
+   * @var array
+   *   Array(string $extKey => CRM_Extension_Upgrader_Interface $upgrader)
+   */
+  protected $upgraders = [];
+
   /**
    * @param CRM_Extension_Container_Interface $container
    * @param CRM_Utils_Cache_Interface $cache
@@ -555,4 +561,36 @@ public function getUpgradeLink($remoteExtensionInfo, $localExtensionInfo) {
     }
   }
 
+  /**
+   * @param string $key
+   *   Long name of the extension.
+   *   Ex: 'org.example.myext'
+   *
+   * @return \CRM_Extension_Upgrader_Interface
+   */
+  public function getUpgrader(string $key) {
+    if (!array_key_exists($key, $this->upgraders)) {
+      $this->upgraders[$key] = NULL;
+
+      try {
+        $info = $this->keyToInfo($key);
+      }
+      catch (CRM_Extension_Exception_ParseException $e) {
+        CRM_Core_Session::setStatus(ts('Parse error in extension: %1', [
+          1 => $e->getMessage(),
+        ]), '', 'error');
+        CRM_Core_Error::debug_log_message("Parse error in extension: " . $e->getMessage());
+        return NULL;
+      }
+
+      if (!empty($info->upgrader)) {
+        $class = $info->upgrader;
+        $u = new $class();
+        $u->init(['key' => $key]);
+        $this->upgraders[$key] = $u;
+      }
+    }
+    return $this->upgraders[$key];
+  }
+
 }

CRM/Extension/Upgrader/Base.php

@@ -0,0 +1,134 @@
+<?php
+
+/**
+ * Base class which provides helpers to execute upgrade logic.
+ *
+ * LIFECYCLE METHODS: Subclasses may optionally define install(), postInstall(),
+ * uninstall(), enable(), disable().
+ *
+ * UPGRADE METHODS: Subclasses may define any number of methods named "upgrade_NNNN()".
+ * Each value of NNNN is treated as a new schema revision. (See also: RevisionsTrait)
+ *
+ * QUEUE METHODS: Upgrade tasks execute within a queue. If an upgrader needs to perform
+ * a large amount of work, it can use "addTask()" / "prependTask()" / "appendTask()".
+ * (See also: QueueTrait)
+ *
+ * EXECUTE METHODS: When writing lifecycle methods, upgrade methods, or queue
+ * tasks, you may wish to execute common steps like "run a SQL file".
+ * (See also: TasksTrait)
+ */
+class CRM_Extension_Upgrader_Base implements CRM_Extension_Upgrader_Interface {
+
+  use CRM_Extension_Upgrader_IdentityTrait;
+  use CRM_Extension_Upgrader_QueueTrait;
+  use CRM_Extension_Upgrader_RevisionsTrait;
+  use CRM_Extension_Upgrader_TasksTrait;
+
+  /**
+   * {@inheritDoc}
+   */
+  public function notify(string $event, array $params = []) {
+    $cb = [$this, 'on' . ucfirst($event)];
+    return is_callable($cb) ? call_user_func_array($cb, $params) : NULL;
+  }
+
+  // ******** Hook delegates ********
+
+  /**
+   * @see https://docs.civicrm.org/dev/en/latest/hooks/hook_civicrm_install
+   */
+  public function onInstall() {
+    $files = glob($this->getExtensionDir() . '/sql/*_install.sql');
+    if (is_array($files)) {
+      foreach ($files as $file) {
+        CRM_Utils_File::sourceSQLFile(CIVICRM_DSN, $file);
+      }
+    }
+    $files = glob($this->getExtensionDir() . '/sql/*_install.mysql.tpl');
+    if (is_array($files)) {
+      foreach ($files as $file) {
+        $this->executeSqlTemplate($file);
+      }
+    }
+    $files = glob($this->getExtensionDir() . '/xml/*_install.xml');
+    if (is_array($files)) {
+      foreach ($files as $file) {
+        $this->executeCustomDataFileByAbsPath($file);
+      }
+    }
+    if (is_callable([$this, 'install'])) {
+      $this->install();
+    }
+  }
+
+  /**
+   * @see https://docs.civicrm.org/dev/en/latest/hooks/hook_civicrm_postInstall
+   */
+  public function onPostInstall() {
+    $revisions = $this->getRevisions();
+    if (!empty($revisions)) {
+      $this->setCurrentRevision(max($revisions));
+    }
+    if (is_callable([$this, 'postInstall'])) {
+      $this->postInstall();
+    }
+  }
+
+  /**
+   * @see https://docs.civicrm.org/dev/en/latest/hooks/hook_civicrm_unnstall
+   */
+  public function onUninstall() {
+    $files = glob($this->getExtensionDir() . '/sql/*_uninstall.mysql.tpl');
+    if (is_array($files)) {
+      foreach ($files as $file) {
+        $this->executeSqlTemplate($file);
+      }
+    }
+    if (is_callable([$this, 'uninstall'])) {
+      $this->uninstall();
+    }
+    $files = glob($this->getExtensionDir() . '/sql/*_uninstall.sql');
+    if (is_array($files)) {
+      foreach ($files as $file) {
+        CRM_Utils_File::sourceSQLFile(CIVICRM_DSN, $file);
+      }
+    }
+  }
+
+  /**
+   * @see https://docs.civicrm.org/dev/en/latest/hooks/hook_civicrm_enable
+   */
+  public function onEnable() {
+    // stub for possible future use
+    if (is_callable([$this, 'enable'])) {
+      $this->enable();
+    }
+  }
+
+  /**
+   * @see https://docs.civicrm.org/dev/en/latest/hooks/hook_civicrm_disable
+   */
+  public function onDisable() {
+    // stub for possible future use
+    if (is_callable([$this, 'disable'])) {
+      $this->disable();
+    }
+  }
+
+  /**
+   * @see https://docs.civicrm.org/dev/en/latest/hooks/hook_civicrm_upgrade
+   */
+  public function onUpgrade($op, CRM_Queue_Queue $queue = NULL) {
+    switch ($op) {
+      case 'check':
+        return [$this->hasPendingRevisions()];
+
+      case 'enqueue':
+        $this->setQueue($queue);
+        return $this->enqueuePendingRevisions();
+
+      default:
+    }
+  }
+
+}

CRM/Extension/Upgrader/IdentityTrait.php

@@ -0,0 +1,55 @@
+<?php
+/*
+ +--------------------------------------------------------------------+
+ | Copyright CiviCRM LLC. All rights reserved.                        |
+ |                                                                    |
+ | This work is published under the GNU AGPLv3 license with some      |
+ | permitted exceptions and without any warranty. For full license    |
+ | and copyright information, see https://civicrm.org/licensing       |
+ +--------------------------------------------------------------------+
+ */
+
+/**
+ * Track minimal information which identifies the target extension.
+ */
+trait CRM_Extension_Upgrader_IdentityTrait {
+
+  /**
+   * @var string
+   *   eg 'com.example.myextension'
+   */
+  protected $extensionName;
+
+  /**
+   * @var string
+   *   full path to the extension's source tree
+   */
+  protected $extensionDir;
+
+  /**
+   * {@inheritDoc}
+   */
+  public function init(array $params) {
+    $this->extensionName = $params['key'];
+    $system = CRM_Extension_System::singleton();
+    $mapper = $system->getMapper();
+    $this->extensionDir = $mapper->keyToBasePath($this->extensionName);
+  }
+
+  /**
+   * @return string
+   *   Ex: 'org.example.foobar'
+   */
+  public function getExtensionKey() {
+    return $this->extensionName;
+  }
+
+  /**
+   * @return string
+   *   Ex: '/var/www/sites/default/ext/org.example.foobar'
+   */
+  public function getExtensionDir() {
+    return $this->extensionDir;
+  }
+
+}

CRM/Extension/Upgrader/Interface.php

@@ -0,0 +1,29 @@
+<?php
+
+/**
+ * An "upgrader" is a class that handles the DB install+upgrade lifecycle
+ * for an extension.
+ */
+interface CRM_Extension_Upgrader_Interface {
+
+  /**
+   * @param array $params
+   *   - string $key: Long form name ('org.example.myext')
+   */
+  public function init(array $params);
+
+  /**
+   * Notify the upgrader about a key lifecycle event, such as installation or uninstallation.
+   *
+   * Each event corresponds to a hook, such as `hook_civicrm_install` or `hook_civicrm_upgrade`.
+   *
+   * @param string $event
+   *   One of the following: 'install', 'onPostInstall', 'enable', 'disable', 'uninstall', 'upgrade'
+   * @param array $params
+   *   Any data that would ordinarily be provided via the equivalent hook.
+   *
+   * @return mixed
+   */
+  public function notify(string $event, array $params = []);
+
+}