Civi/WorkflowMessage/WorkflowMessageInterface.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 namespace Civi\WorkflowMessage;
  13
  14 interface WorkflowMessageInterface {
  15
  16   /**
  17    * @return \Civi\WorkflowMessage\FieldSpec[]
  18    *   A list of field-specs that are used in the given format, keyed by their name in that format.
  19    *   If the implementation does not understand a specific format, return NULL.
  20    */
  21   public function getFields(): array;
  22
  23   /**
  24    * @param string $format
  25    *   Ex: 'tplParams', 'tokenContext', 'modelProps', 'envelope'
  26    * @return array|null
  27    *   A list of field-values that are used in the given format, keyed by their name in that format.
  28    *   If the implementation does not understand a specific format, return NULL.
  29    * @see \Civi\WorkflowMessage\Traits\ReflectiveWorkflowTrait::export()
  30    */
  31   public function export(string $format = NULL): ?array;
  32
  33   /**
  34    * Import values from some scope.
  35    *
  36    * Ex: $message->import('tplParams', ['sm_art_stuff' => 123]);
  37    *
  38    * @param string $format
  39    *   Ex: 'tplParams', 'tokenContext', 'modelProps', 'envelope'
  40    * @param array $values
  41    *
  42    * @return $this
  43    * @see \Civi\WorkflowMessage\Traits\ReflectiveWorkflowTrait::import()
  44    */
  45   public function import(string $format, array $values);
  46
  47   /**
  48    * Determine if the data for this workflow message is complete/well-formed.
  49    *
  50    * @return array
  51    *   A list of errors and warnings. Each record defines
  52    *   - severity: string, 'error' or 'warning'
  53    *   - fields: string[], list of fields implicated in the error
  54    *   - name: string, symbolic name of the error/warning
  55    *   - message: string, printable message describing the problem
  56    */
  57   public function validate(): array;
  58
  59   // These additional methods are sugar-coating - they're part of the interface to
  60   // make it easier to work with, but implementers should not differentiate themselves
  61   // using this methods. Instead, use FinalHelperTrait as a thin implementation.
  62
  63   /**
  64    * Assert that the current message data is valid/sufficient.
  65    *
  66    * TIP: Do not implement directly. Use FinalHelperTrait.
  67    *
  68    * @param bool $strict
  69    *   If TRUE, then warnings will raise exceptions.
  70    *   If FALSE, then only errors will raise exceptions.
  71    * @return $this
  72    * @throws \CRM_Core_Exception
  73    */
  74   public function assertValid($strict = FALSE);
  75
  76   /**
  77    * Render a message template.
  78    *
  79    * TIP: Do not implement directly. Use FinalHelperTrait.
  80    *
  81    * @param array $params
  82    *   Options for loading the message template.
  83    *   If none given, the default for this workflow will be loaded.
  84    *   Ex: ['messageTemplate' => ['msg_subject' => 'Hello {contact.first_name}']]
  85    *   Ex: ['messageTemplateID' => 123]
  86    * @return array
  87    *   Rendered message, consistent of 'subject', 'text', 'html'
  88    *   Ex: ['subject' => 'Hello Bob', 'text' => 'It\'s been so long since we sent you an automated notification!']
  89    * @see \CRM_Core_BAO_MessageTemplate::renderTemplate()
  90    */
  91   public function renderTemplate(array $params = []): array;
  92
  93   /**
  94    * Send an email using a message template.
  95    *
  96    * TIP: Do not implement directly. Use FinalHelperTrait.
  97    *
  98    * @param array $params
  99    *   List of extra parameters to pass to `sendTemplate()`. Ex:
 100    *   - from
 101    *   - toName
 102    *   - toEmail
 103    *   - cc
 104    *   - bcc
 105    *   - replyTo
 106    *   - isTest
 107    *
 108    * @return array
 109    *   Array of four parameters: a boolean whether the email was sent, and the subject, text and HTML templates
 110    * @see \CRM_Core_BAO_MessageTemplate::sendTemplate()
 111    */
 112   public function sendTemplate(array $params = []): array;
 113
 114 }