tests/events/hook_civicrm_alterMailParams.evch.php

   1 <?php
   2 return new class() extends \Civi\Test\EventCheck implements \Civi\Test\HookInterface {
   3
   4   private $paramSpecs = [
   5
   6     // ## Envelope: Common
   7
   8     'toName' => ['type' => 'string|NULL'],
   9     'toEmail' => ['type' => 'string|NULL'],
  10     'cc' => ['type' => 'string|NULL'],
  11     'bcc' => ['type' => 'string|NULL'],
  12     'headers' => ['type' => 'array'],
  13     'attachments' => ['type' => 'array|NULL'],
  14     'isTest' => ['type' => 'bool|int'],
  15
  16     // ## Envelope: singleEmail/messageTemplate
  17
  18     'from' => ['type' => 'string|NULL', 'for' => ['messageTemplate', 'singleEmail']],
  19     'replyTo' => ['type' => 'string|NULL', 'for' => ['messageTemplate', 'singleEmail']],
  20     'returnPath' => ['type' => 'string|NULL', 'for' => ['messageTemplate', 'singleEmail']],
  21     'isEmailPdf' => ['type' => 'bool', 'for' => 'messageTemplate'],
  22     'PDFFilename' => ['type' => 'string|NULL', 'for' => 'messageTemplate'],
  23     'autoSubmitted' => ['type' => 'bool', 'for' => 'messageTemplate'],
  24     'Message-ID' => ['type' => 'string', 'for' => ['messageTemplate', 'singleEmail']],
  25     'messageId' => ['type' => 'string', 'for' => ['messageTemplate', 'singleEmail']],
  26
  27     // ## Envelope: CiviMail/Flexmailer
  28
  29     'Reply-To' => ['type' => 'string|NULL', 'for' => ['civimail', 'flexmailer']],
  30     'Return-Path' => ['type' => 'string|NULL', 'for' => ['civimail', 'flexmailer']],
  31     'From' => ['type' => 'string|NULL', 'for' => ['civimail', 'flexmailer']],
  32     'Subject' => ['type' => 'string|NULL', 'for' => ['civimail', 'flexmailer']],
  33     'List-Unsubscribe' => ['type' => 'string|NULL', 'for' => ['civimail', 'flexmailer']],
  34     'X-CiviMail-Bounce' => ['type' => 'string|NULL', 'for' => ['civimail', 'flexmailer']],
  35     'Precedence' => ['type' => 'string|NULL', 'for' => ['civimail', 'flexmailer'], 'regex' => '/(bulk|first-class|list)/'],
  36     'job_id' => ['type' => 'int|NULL', 'for' => ['civimail', 'flexmailer']],
  37
  38     // ## Content
  39
  40     'subject' => ['for' => ['messageTemplate', 'singleEmail'], 'type' => 'string'],
  41     'text' => ['type' => 'string|NULL'],
  42     'html' => ['type' => 'string|NULL'],
  43
  44     // ## Model: messageTemplate
  45
  46     'tokenContext' => ['type' => 'array', 'for' => 'messageTemplate'],
  47     'tplParams' => ['type' => 'array', 'for' => 'messageTemplate'],
  48     'contactId' => ['type' => 'int|NULL', 'for' => 'messageTemplate' /* deprecated in favor of tokenContext[contactId] */],
  49     'workflow' => [
  50       'regex' => '/^([a-zA-Z_]+)$/',
  51       'type' => 'string',
  52       'for' => 'messageTemplate',
  53     ],
  54     'valueName' => [
  55       'regex' => '/^([a-zA-Z_]+)$/',
  56       'type' => 'string',
  57       'for' => 'messageTemplate',
  58     ],
  59     'groupName' => [
  60       // This field is generally deprecated. Historically, this was tied to various option-groups (`msg_*`),
  61       // but it also seems to have been used with a few long-form English names.
  62       'regex' => '/^(msg_[a-zA-Z_]+|Scheduled Reminder Sender|Activity Email Sender|Report Email Sender|Mailing Event Welcome|CRM_Core_Config_MailerTest)$/',
  63       'type' => 'string',
  64       'for' => ['messageTemplate', 'singleEmail'],
  65     ],
  66
  67     // The model is not passed into this hook because it would create ambiguity when you alter properties.
  68     // If you want to expose it via hook, add another hook.
  69     'model' => ['for' => 'messageTemplate', 'type' => 'NULL'],
  70     'modelProps' => ['for' => 'messageTemplate', 'type' => 'NULL'],
  71
  72     // ## Model: Adhoc/incomplete/needs attention
  73
  74     'contributionId' => ['type' => 'int', 'for' => 'messageTemplate'],
  75     'petitionId' => ['type' => 'int', 'for' => 'messageTemplate'],
  76     'petitionTitle' => ['type' => 'string', 'for' => 'messageTemplate'],
  77     'table' => ['type' => 'string', 'for' => 'messageTemplate', 'regex' => '/civicrm_msg_template/'],
  78     'entity' => ['type' => 'string|NULL', 'for' => 'singleEmail'],
  79     'entity_id' => ['type' => 'int|NULL', 'for' => 'singleEmail'],
  80
  81     // ## View: messageTemplate
  82
  83     'messageTemplateID' => ['type' => 'int|NULL', 'for' => 'messageTemplate'],
  84     'messageTemplate' => ['type' => 'array|NULL', 'for' => 'messageTemplate'],
  85     'disableSmarty' => ['type' => 'bool|int', 'for' => 'messageTemplate'],
  86   ];
  87
  88   public function isSupported($test) {
  89     // MailTest does intentionally breaky things to provoke+ensure decent error-handling.
  90     //So we will not enforce generic rules on it.
  91     return !($test instanceof CRM_Utils_MailTest);
  92   }
  93
  94   /**
  95    * Ensure that the hook data is always well-formed.
  96    *
  97    * @see \CRM_Utils_Hook::alterMailParams()
  98    */
  99   public function hook_civicrm_alterMailParams(&$params, $context = NULL) {
 100     $msg = "Non-conformant hook_civicrm_alterMailParams(..., $context)";
 101     $dump = print_r($params, 1);
 102
 103     $this->assertRegExp('/^(messageTemplate|civimail|singleEmail|flexmailer)$/',
 104       $context, "$msg: Unrecognized context ($context)\n$dump");
 105
 106     $contexts = [$context];
 107     if ($context === 'singleEmail' && array_key_exists('tokenContext', $params)) {
 108       // Don't look now, but `sendTemplate()` fires this hook twice for the message! Once with $context=messageTemplate; again with $context=singleEmail.
 109       $contexts[] = 'messageTemplate';
 110     }
 111
 112     $paramSpecs = array_filter($this->paramSpecs, function ($f) use ($contexts) {
 113       return !isset($f['for']) || array_intersect((array) $f['for'], $contexts);
 114     });
 115
 116     $unknownKeys = array_diff(array_keys($params), array_keys($paramSpecs));
 117     if ($unknownKeys !== []) {
 118       echo '';
 119     }
 120     $this->assertEquals([], $unknownKeys, "$msg: Unrecognized keys: " . implode(', ', $unknownKeys) . "\n$dump");
 121
 122     foreach ($params as $key => $value) {
 123       if (isset($paramSpecs[$key]['type'])) {
 124         $this->assertType($paramSpecs[$key]['type'], $value, "$msg: Bad data-type found in param ($key)\n$dump");
 125       }
 126       if (isset($paramSpecs[$key]['regex']) && $value !== NULL) {
 127         $this->assertRegExp($paramSpecs[$key]['regex'], $value, "Parameter [$key => $value] should match regex ({$paramSpecs[$key]['regex']})");
 128       }
 129     }
 130
 131     if ($context === 'messageTemplate') {
 132       $this->assertTrue(!empty($params['workflow']), "$msg: Message templates must always specify a symbolic name of the step/task\n$dump");
 133       if (isset($params['valueName'])) {
 134         // This doesn't require that valueName be supplied - but if it is supplied, it must match the workflow name.
 135         $this->assertEquals($params['workflow'], $params['valueName'], "$msg: If given, workflow and valueName must match\n$dump");
 136       }
 137       $this->assertEquals($params['contactId'] ?? NULL, $params['tokenContext']['contactId'] ?? NULL, "$msg: contactId moved to tokenContext, but legacy value should be equivalent\n$dump");
 138
 139       // This assertion is surprising -- yet true. We should perhaps check if it was true in past releases...
 140       $this->assertTrue(empty($params['text']) && empty($params['html']) && empty($params['subject']), "$msg: Content is not given if context==messageTemplate\n$dump");
 141     }
 142
 143     if ($context !== 'messageTemplate') {
 144       $this->assertTrue(!empty($params['text']) || !empty($params['html']) || !empty($params['subject']), "$msg: Must provide at least one of: text, html, subject\n$dump");
 145     }
 146
 147     if (isset($params['groupName']) && $params['groupName'] === 'Scheduled Reminder Sender') {
 148       $this->assertTrue(!empty($params['entity']), "$msg: Scheduled reminders should have entity\n$dump");
 149       $this->assertTrue(!empty($params['entity_id']), "$msg: Scheduled reminders should have entity_id\n$dump");
 150     }
 151   }
 152
 153 };