Civi/WorkflowMessage/GenericWorkflowMessage.php

   1 <?php
   2
   3 /*
   4  +--------------------------------------------------------------------+
   5  | Copyright CiviCRM LLC. All rights reserved.                        |
   6  |                                                                    |
   7  | This work is published under the GNU AGPLv3 license with some      |
   8  | permitted exceptions and without any warranty. For full license    |
   9  | and copyright information, see https://civicrm.org/licensing       |
  10  +--------------------------------------------------------------------+
  11  */
  12
  13 namespace Civi\WorkflowMessage;
  14
  15 use Civi\Schema\Traits\MagicGetterSetterTrait;
  16 use Civi\WorkflowMessage\Traits\AddressingTrait;
  17 use Civi\WorkflowMessage\Traits\FinalHelperTrait;
  18 use Civi\WorkflowMessage\Traits\LocalizationTrait;
  19 use Civi\WorkflowMessage\Traits\ReflectiveWorkflowTrait;
  20
  21 /**
  22  * Generic base-class for describing the inputs for a workflow email template.
  23  *
  24  * @method $this setContactId(int|null $contactId)
  25  * @method int|null getContactId()
  26  * @method $this setContact(array|null $contact)
  27  * @method array|null getContact()
  28  *
  29  * @support template-only
  30  * GenericWorkflowMessage should aim for "full" support, but it's prudent to keep
  31  * it flexible for the first few months. Consider updating to "full" after Dec 2021.
  32  */
  33 class GenericWorkflowMessage implements WorkflowMessageInterface {
  34
  35   // Implement getFields(), import(), export(), validate() - All methods based on inspecting class properties (`ReflectionClass`).
  36   // Define stub methods exportExtraTokenContext(), exportExtraTplParams(), etc.
  37   use ReflectiveWorkflowTrait;
  38
  39   // Implement __call() - Public and protected properties are automatically given a default getter/setter. These may be overridden/customized.
  40   use MagicGetterSetterTrait;
  41
  42   // Implement assertValid(), renderTemplate(), sendTemplate() - Sugary stub methods that delegate to real APIs.
  43   use FinalHelperTrait;
  44
  45   // Implement setTo(), setReplyTo(), etc
  46   use AddressingTrait;
  47
  48   // Implement setLocale(), etc
  49   use LocalizationTrait;
  50
  51   /**
  52    * WorkflowMessage constructor.
  53    *
  54    * @param array $imports
  55    *   List of values to import.
  56    *   Ex: ['tplParams' => [...tplValues...], 'tokenContext' => [...tokenData...]]
  57    *   Ex: ['modelProps' => [...classProperties...]]
  58    */
  59   public function __construct(array $imports = []) {
  60     WorkflowMessage::importAll($this, $imports);
  61   }
  62
  63   /**
  64    * The contact receiving this message.
  65    *
  66    * @var int|null
  67    * @scope tokenContext, tplParams as contactID
  68    * @fkEntity Contact
  69    */
  70   protected $contactId;
  71
  72   /**
  73    * @var array|null
  74    * @scope tokenContext
  75    */
  76   protected $contact;
  77
  78   /**
  79    * Must provide either 'int $contactId' or 'array $contact'
  80    *
  81    * @param array $errors
  82    * @see ReflectiveWorkflowTrait::validate()
  83    */
  84   protected function validateExtra_contact(array &$errors) {
  85     if (empty($this->contactId) && empty($this->contact['id'])) {
  86       $errors[] = [
  87         'severity' => 'error',
  88         'fields' => ['contactId', 'contact'],
  89         'name' => 'missingContact',
  90         'message' => ts('Message template requires one of these fields (%1)', ['contactId, contact']),
  91       ];
  92     }
  93     if (!empty($this->contactId) && !empty($this->contact)) {
  94       $errors[] = [
  95         'severity' => 'warning',
  96         'fields' => ['contactId', 'contact'],
  97         'name' => 'missingContact',
  98         'message' => ts('Passing both (%1) may lead to ambiguous behavior.', ['contactId, contact']),
  99       ];
 100     }
 101   }
 102
 103   /**
 104    * Define tokens to be exported as smarty values.
 105    *
 106    * @param array $export
 107    */
 108   protected function exportExtraTokenContext(array &$export): void {
 109     // Tax term is exposed at the generic level as so many templates use it
 110     // (e.g. Membership, participant, pledge as well as contributions).
 111     $export['smartyTokenAlias']['taxTerm'] = 'domain.tax_term';
 112   }
 113
 114 }