MessageTemplate::sendTemplate() - Accept `array $messsageTemplate` option

When using `sendTemplate()`, how does it resolve the literal content of the template?

* (Before+After) You may give `string $valueName` (identify+load template by workflow-name)
* (Before+After) You may give `int $messageTemplateID` (identify+load template by ID)
* (Before+After) You may give `string $subject` (override the msg_subject)
* (After) You may give `array $messageTemplate` (specify the content for any/all fields;
  eg msg_subject, msg_text, msg_html)
* (After) Using `string $subject` is deprecated

diff --git a/CRM/Core/BAO/MessageTemplate.php b/CRM/Core/BAO/MessageTemplate.php
index ec6e83627eec103d226b8469bb632f689f6f72a6..15b3012f8765d75cc00defa1ade7e1c1e7be7ef0 100644 (file)
--- a/CRM/Core/BAO/MessageTemplate.php
+++ b/CRM/Core/BAO/MessageTemplate.php
@@ -381,6 +381,9 @@ class CRM_Core_BAO_MessageTemplate extends CRM_Core_DAO_MessageTemplate {
       'valueName' => NULL,
       // ID of the template
       'messageTemplateID' => NULL,
+      // content of the message template
+      // Ex: ['msg_subject' => 'Hello {contact.display_name}', 'msg_html' => '...', 'msg_text' => '...']
+      'messageTemplate' => NULL,
       // contact id if contact tokens are to be replaced
       'contactId' => NULL,
       // additional template params (other than the ones already set in the template singleton)
@@ -420,12 +423,7 @@ class CRM_Core_BAO_MessageTemplate extends CRM_Core_DAO_MessageTemplate {
       CRM_Core_Error::deprecatedWarning('message template id should be an integer');
       $params['messageTemplateID'] = (int) $params['messageTemplateID'];
     }
-    $mailContent = self::loadTemplate((string) $params['valueName'], $params['isTest'], $params['messageTemplateID'] ?? NULL, $params['groupName'] ?? '');
-
-    // Overwrite subject from form field
-    if (!empty($params['subject'])) {
-      $mailContent['subject'] = $params['subject'];
-    }
+    $mailContent = self::loadTemplate((string) $params['valueName'], $params['isTest'], $params['messageTemplateID'] ?? NULL, $params['groupName'] ?? '', $params['messageTemplate'], $params['subject'] ?? NULL);
 
     $mailContent = self::renderMessageTemplate($mailContent, (bool) $params['disableSmarty'], $params['contactId'] ?? NULL, $params['tplParams'], $params['tokenContext']);
 
@@ -504,12 +502,18 @@ class CRM_Core_BAO_MessageTemplate extends CRM_Core_DAO_MessageTemplate {
    * @param bool $isTest
    * @param int|null $messageTemplateID
    * @param string $groupName
+   * @param array|null $messageTemplateOverride
+   *   Optionally, record with msg_subject, msg_text, msg_html.
+   *   If omitted, the record will be loaded from workflowName/messageTemplateID.
+   * @param string|null $subjectOverride
+   *   This option is the older, wonkier version of $messageTemplate['msg_subject']...
    *
    * @return array
    * @throws \API_Exception
    * @throws \CRM_Core_Exception
    */
-  protected static function loadTemplate(string $workflowName, bool $isTest, int $messageTemplateID = NULL, $groupName = NULL): array {
+  protected static function loadTemplate(string $workflowName, bool $isTest, int $messageTemplateID = NULL, $groupName = NULL, ?array $messageTemplateOverride = NULL, ?string $subjectOverride = NULL): array {
+    $base = ['msg_subject' => NULL, 'msg_text' => NULL, 'msg_html' => NULL, 'pdf_format_id' => NULL];
     if (!$workflowName && !$messageTemplateID) {
       throw new CRM_Core_Exception(ts("Message template's option value or ID missing."));
     }
@@ -524,12 +528,12 @@ class CRM_Core_BAO_MessageTemplate extends CRM_Core_DAO_MessageTemplate {
     else {
       $apiCall->addWhere('workflow_name', '=', $workflowName);
     }
-    $messageTemplate = $apiCall->execute()->first();
-    if (empty($messageTemplate['id'])) {
+    $messageTemplate = array_merge($base, $apiCall->execute()->first() ?: [], $messageTemplateOverride ?: []);
+    if (empty($messageTemplate['id']) && empty($messageTemplateOverride)) {
       if ($messageTemplateID) {
         throw new CRM_Core_Exception(ts('No such message template: id=%1.', [1 => $messageTemplateID]));
       }
-      throw new CRM_Core_Exception(ts('No message template with workflow name %2.', [2 => $workflowName]));
+      throw new CRM_Core_Exception(ts('No message template with workflow name %1.', [1 => $workflowName]));
     }
 
     $mailContent = [
@@ -566,6 +570,11 @@ class CRM_Core_BAO_MessageTemplate extends CRM_Core_DAO_MessageTemplate {
       $mailContent['html'] = preg_replace('/<body(.*)$/im', "<body\\1\n{$testText['msg_html']}", $mailContent['html']);
     }
 
+    if (!empty($subjectOverride)) {
+      CRM_Core_Error::deprecatedWarning('CRM_Core_BAO_MessageTemplate: $params[subject] is deprecated. Use $params[messageTemplate][msg_subject] instead.');
+      $mailContent['subject'] = $subjectOverride;
+    }
+
     return $mailContent;
   }