CRM/Extension/Upgrader/QueueTrait.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | Copyright CiviCRM LLC. All rights reserved.                        |
   5  |                                                                    |
   6  | This work is published under the GNU AGPLv3 license with some      |
   7  | permitted exceptions and without any warranty. For full license    |
   8  | and copyright information, see https://civicrm.org/licensing       |
   9  +--------------------------------------------------------------------+
  10  */
  11
  12 /**
  13  * The QueueTrait provides helper methods for adding new tasks to a queue.
  14  */
  15 trait CRM_Extension_Upgrader_QueueTrait {
  16
  17   abstract public function getExtensionKey();
  18
  19   /**
  20    * @var \CRM_Queue_Queue
  21    */
  22   protected $queue;
  23
  24   /**
  25    * @var \CRM_Queue_TaskContext
  26    */
  27   protected $ctx;
  28
  29   /**
  30    * Adapter that lets you add normal (non-static) member functions to the queue.
  31    *
  32    * While working through a task-queue, the _queueAdapter is called statically. It looks up
  33    * the appropriate object and invokes the expected method.
  34    *
  35    * ```
  36    * CRM_Extension_Upgrader::_queueAdapter($ctx, 'org.example.myext', 'methodName', 'arg1', 'arg2');
  37    * ```
  38    */
  39   public static function _queueAdapter(CRM_Queue_TaskContext $ctx, string $extensionKey, string $method, ...$args) {
  40     /** @var static $upgrader */
  41     $upgrader = \CRM_Extension_System::singleton()->getMapper()->getUpgrader($extensionKey);
  42     if ($upgrader->ctx !== NULL) {
  43       throw new \RuntimeException(sprintf("Cannot execute task for %s (%s::%s) - task already active.", $extensionKey, get_class($upgrader), $method));
  44     }
  45
  46     $upgrader->ctx = $ctx;
  47     $upgrader->queue = $ctx->queue;
  48     try {
  49       return call_user_func_array([$upgrader, $method], $args);
  50     } finally {
  51       $upgrader->ctx = NULL;
  52     }
  53   }
  54
  55   public function addTask(string $title, string $funcName, ...$options) {
  56     return $this->prependTask($title, $funcName, ...$options);
  57   }
  58
  59   /**
  60    * Enqueue a task based on a method in this class.
  61    *
  62    * The task is weighted so that it is processed as part of the currently-pending revision.
  63    *
  64    * After passing the $funcName, you can also pass parameters that will go to
  65    * the function. Note that all params must be serializable.
  66    */
  67   public function prependTask(string $title, string $funcName, ...$options) {
  68     $task = new CRM_Queue_Task(
  69       [get_class($this), '_queueAdapter'],
  70       array_merge([$this->getExtensionKey(), $funcName], $options),
  71       $title
  72     );
  73     return $this->queue->createItem($task, ['weight' => -1]);
  74   }
  75
  76   /**
  77    * Enqueue a task based on a method in this class.
  78    *
  79    * The task has a default weight.
  80    *
  81    * @return mixed
  82    */
  83   protected function appendTask(string $title, string $funcName, ...$options) {
  84     $task = new CRM_Queue_Task(
  85       [get_class($this), '_queueAdapter'],
  86       array_merge([$this->getExtensionKey(), $funcName], $options),
  87       $title
  88     );
  89     return $this->queue->createItem($task);
  90   }
  91
  92   // ******** Basic getters/setters ********
  93
  94   /**
  95    * @return \CRM_Queue_Queue
  96    */
  97   public function getQueue(): \CRM_Queue_Queue {
  98     return $this->queue;
  99   }
 100
 101   /**
 102    * @param \CRM_Queue_Queue $queue
 103    */
 104   public function setQueue(\CRM_Queue_Queue $queue): void {
 105     $this->queue = $queue;
 106   }
 107
 108 }