Commit | Line | Data |
---|---|---|
92f656cb TO |
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 | ||
1972897e TO |
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 | ||
92f656cb | 114 | } |