CRM/Queue/Task.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  * A task is an item that can be enqueued and later executed
  14  */
  15 class CRM_Queue_Task {
  16
  17   /**
  18    * Task was performed successfully.
  19    */
  20   const TASK_SUCCESS = 1;
  21
  22   /**
  23    * Task failed and should not be retried.
  24    */
  25   const TASK_FAIL = 2;
  26
  27   /**
  28    * @var mixed
  29    * serializable
  30    */
  31   public $callback;
  32
  33   /**
  34    * @var array
  35    * serializable
  36    */
  37   public $arguments;
  38
  39   /**
  40    * @var string|null
  41    */
  42   public $title;
  43
  44   /**
  45    * @var array|null
  46    * serializable
  47    *
  48    * If specified, it may include these keys:
  49    *   - contactId: int|null
  50    *   - domainId: int|null
  51    */
  52   public $runAs;
  53
  54   /**
  55    * @param mixed $callback
  56    *   Serializable, a callable PHP item; must accept at least one argument
  57    *   (CRM_Queue_TaskContext).
  58    * @param array $arguments
  59    *   Serializable, extra arguments to pass to the callback (in order).
  60    * @param string|null $title
  61    *   A printable string which describes this task.
  62    */
  63   public function __construct($callback, array $arguments = [], ?string $title = NULL) {
  64     $this->callback = $callback;
  65     $this->arguments = $arguments;
  66     $this->title = $title;
  67   }
  68
  69   /**
  70    * Perform the task.
  71    *
  72    * @param \CRM_Queue_TaskContext $taskCtx
  73    * @throws Exception
  74    * @return bool
  75    *   TRUE if task completes successfully.
  76    *   FALSE or exception if task fails.
  77    */
  78   public function run($taskCtx) {
  79     $args = $this->arguments;
  80     array_unshift($args, $taskCtx);
  81
  82     if ($this->runAs !== NULL) {
  83       $equals = function($a, $b) {
  84         return $a === $b || (is_numeric($a) && is_numeric($b) && $a == $b);
  85       };
  86       if (array_key_exists('contactId', $this->runAs) && !$equals(CRM_Core_Session::getLoggedInContactID(), $this->runAs['contactId'])) {
  87         throw new Exception(sprintf('Cannot execute queue task. Unexpected contact "%s" for job "%s"', CRM_Core_Session::getLoggedInContactID(), $this->getSummary()));
  88       }
  89       if (array_key_exists('domainId', $this->runAs) && !$equals(CRM_Core_BAO_Domain::getDomain()->id, $this->runAs['domainId'])) {
  90         throw new Exception(sprintf('Cannot execute queue task. Unexpected domain "%s" for job "%s"', CRM_Core_BAO_Domain::getDomain()->id, $this->getSummary()));
  91       }
  92     }
  93
  94     if (is_callable($this->callback)) {
  95       $result = call_user_func_array($this->callback, $args);
  96       return $result;
  97     }
  98     else {
  99       throw new Exception('Failed to call callback: ' . $this->getSummary());
 100     }
 101   }
 102
 103   private function getSummary(): string {
 104     return json_encode(['title' => $this->title, 'runAs' => $this->runAs, 'callback' => $this->callback], JSON_UNESCAPED_SLASHES);
 105   }
 106
 107 }