From fa78ca246cec8463a237e6e4cb1b94f81282110e Mon Sep 17 00:00:00 2001
From: Tim Otten <totten@civicrm.org>
Date: Sun, 11 Jul 2021 21:24:38 -0700
Subject: [PATCH] MessageTemplate - Deprecate renderMessageTemplate(). Prefer
 renderTemplate() and TokenSmarty::render(). Add tests

---
 CRM/Core/BAO/MessageTemplate.php              | 43 ++++++++++++++++++-
 .../CRM/Core/BAO/MessageTemplateTest.php      | 23 ++++++++++
 2 files changed, 64 insertions(+), 2 deletions(-)

diff --git a/CRM/Core/BAO/MessageTemplate.php b/CRM/Core/BAO/MessageTemplate.php
index 0025b80e54..b8f8619afd 100644
--- a/CRM/Core/BAO/MessageTemplate.php
+++ b/CRM/Core/BAO/MessageTemplate.php
@@ -364,6 +364,37 @@ class CRM_Core_BAO_MessageTemplate extends CRM_Core_DAO_MessageTemplate {
     $diverted->save();
   }
 
+  /**
+   * Render a message template.
+   *
+   * This method is very similar to `sendTemplate()` - accepting most of the same arguments
+   * and emitting similar hooks. However, it specifically precludes the possibility of
+   * sending a message. It only renders.
+   *
+   * @param $params
+   *  Mixed render parameters. See sendTemplate() for more details.
+   * @return array
+   *   Rendered message, consistent of 'subject', 'text', 'html'
+   *   Ex: ['subject' => 'Hello Bob', 'text' => 'It\'s been so long since we sent you an automated notification!']
+   * @throws \API_Exception
+   * @throws \CRM_Core_Exception
+   * @see sendTemplate()
+   */
+  public static function renderTemplate($params) {
+    $forbidden = ['from', 'toName', 'toEmail', 'cc', 'bcc', 'replyTo'];
+    $intersect = array_intersect($forbidden, array_keys($params));
+    if (!empty($intersect)) {
+      throw new \CRM_Core_Exception(sprintf("renderTemplate() received forbidden fields (%s)",
+        implode(',', $intersect)));
+    }
+
+    $mailContent = [];
+    // sendTemplate has had an obscure feature - if you omit `toEmail`, then it merely renders.
+    // At some point, we may want to invert the relation between renderTemplate/sendTemplate, but for now this is a smaller patch.
+    [$sent, $mailContent['subject'], $mailContent['text'], $mailContent['html']] = static::sendTemplate($params);
+    return $mailContent;
+  }
+
   /**
    * Send an email from the specified template based on an array of params.
    *
@@ -583,9 +614,17 @@ class CRM_Core_BAO_MessageTemplate extends CRM_Core_DAO_MessageTemplate {
   /**
    * Render the message template, resolving tokens and smarty tokens.
    *
-   * As with all BAO methods this should not be called directly outside
-   * of tested core code and is highly likely to change.
+   * This method has been deprecated in favor of two alternatives:
+   *  - Use CRM_Core_BAO_MessageTemplate::renderTemplate() if you want a high-level
+   *    trial-run of sendTemplate(). This will use the loaders, filters, hooks, etc
+   *    but stop short of delivery.
+   *  - Use CRM_Core_TokenSmarty::render() if you want a low-level utility to
+   *    render a template with the hybrid Token-Smarty template format.
    *
+   * @internal
+   * @deprecated
+   * @see CRM_Core_BAO_MessageTemplate::renderTemplate()
+   * @see CRM_Core_TokenSmarty::render()
    * @param array $mailContent
    * @param bool $disableSmarty
    * @param int|NULL $contactID
diff --git a/tests/phpunit/CRM/Core/BAO/MessageTemplateTest.php b/tests/phpunit/CRM/Core/BAO/MessageTemplateTest.php
index 08edc85ca5..4c286f528f 100644
--- a/tests/phpunit/CRM/Core/BAO/MessageTemplateTest.php
+++ b/tests/phpunit/CRM/Core/BAO/MessageTemplateTest.php
@@ -22,6 +22,29 @@ class CRM_Core_BAO_MessageTemplateTest extends CiviUnitTestCase {
     parent::tearDown();
   }
 
+  public function testRenderTemplate() {
+    $contactId = $this->individualCreate([
+      'first_name' => 'Abba',
+      'last_name' => 'Baab',
+      'prefix_id' => NULL,
+      'suffix_id' => NULL,
+    ]);
+    $rendered = CRM_Core_BAO_MessageTemplate::renderTemplate([
+      'valueName' => 'case_activity',
+      'tokenContext' => [
+        'contactId' => $contactId,
+      ],
+      'messageTemplate' => [
+        'msg_subject' => 'Hello testRenderTemplate {contact.display_name}!',
+        'msg_text' => 'Hello testRenderTemplate {contact.display_name}!',
+        'msg_html' => '<p>Hello testRenderTemplate {contact.display_name}!</p>',
+      ],
+    ]);
+    $this->assertEquals('Hello testRenderTemplate Abba Baab!', $rendered['subject']);
+    $this->assertEquals('Hello testRenderTemplate Abba Baab!', $rendered['text']);
+    $this->assertStringContainsString('<p>Hello testRenderTemplate Abba Baab!</p>', $rendered['html']);
+  }
+
   public function testSendTemplate_RenderMode_OpenTemplate() {
     $contactId = $this->individualCreate([
       'first_name' => 'Abba',
-- 
2.25.1