Commit | Line | Data |
---|---|---|
46f5566c TO |
1 | <?php |
2 | /* | |
3 | +--------------------------------------------------------------------+ | |
41498ac5 | 4 | | Copyright CiviCRM LLC. All rights reserved. | |
46f5566c | 5 | | | |
41498ac5 TO |
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 | | |
46f5566c TO |
9 | +--------------------------------------------------------------------+ |
10 | */ | |
11 | ||
12 | namespace Civi\Token; | |
13 | ||
f9ec2da6 | 14 | use Civi\ActionSchedule\Event\MailingQueryEvent; |
46f5566c TO |
15 | use Civi\Token\Event\TokenRegisterEvent; |
16 | use Civi\Token\Event\TokenValueEvent; | |
17 | use Symfony\Component\EventDispatcher\EventSubscriberInterface; | |
18 | ||
19 | /** | |
20 | * Class AbstractTokenSubscriber | |
21 | * @package Civi\Token | |
22 | * | |
23 | * AbstractTokenSubscriber is a base class which may be extended to | |
24 | * implement tokens in a somewhat more concise fashion. | |
25 | * | |
26 | * To implement a new token handler based on this: | |
27 | * 1. Create a subclass. | |
28 | * 2. Override the constructor and set values for $entity and $tokenNames. | |
29 | * 3. Implement the evaluateToken() method. | |
f9ec2da6 TO |
30 | * 4. Optionally, override others: |
31 | * + checkActive() | |
eb969099 | 32 | * + getActiveTokens() |
f9ec2da6 TO |
33 | * + prefetch() |
34 | * + alterActionScheduleMailing() | |
35 | * 5. Register the new class with the event-dispatcher. | |
46f5566c TO |
36 | * |
37 | * Note: There's no obligation to use this base class. You could implement | |
38 | * your own class anew -- just subscribe the proper events. | |
39 | */ | |
40 | abstract class AbstractTokenSubscriber implements EventSubscriberInterface { | |
41 | ||
42 | public static function getSubscribedEvents() { | |
c64f69d9 | 43 | return [ |
4c367668 TO |
44 | 'civi.token.list' => 'registerTokens', |
45 | 'civi.token.eval' => 'evaluateTokens', | |
bc2feeb1 | 46 | 'civi.actionSchedule.prepareMailingQuery' => 'alterActionScheduleQuery', |
c64f69d9 | 47 | ]; |
46f5566c TO |
48 | } |
49 | ||
50 | /** | |
51 | * @var string | |
52 | * Ex: 'contact' or profile' or 'employer' | |
53 | */ | |
54 | public $entity; | |
55 | ||
56 | /** | |
57 | * @var array | |
52883911 AS |
58 | * List of tokens provided by this class |
59 | * Array(string $fieldName => string $label). | |
46f5566c TO |
60 | */ |
61 | public $tokenNames; | |
62 | ||
52883911 AS |
63 | /** |
64 | * @var array | |
65 | * List of active tokens - tokens provided by this class and used in the message | |
66 | * Array(string $tokenName); | |
67 | */ | |
68 | public $activeTokens; | |
69 | ||
46f5566c TO |
70 | /** |
71 | * @param $entity | |
72 | * @param array $tokenNames | |
52883911 | 73 | * Array(string $tokenName => string $label). |
46f5566c | 74 | */ |
c64f69d9 | 75 | public function __construct($entity, $tokenNames = []) { |
46f5566c TO |
76 | $this->entity = $entity; |
77 | $this->tokenNames = $tokenNames; | |
78 | } | |
79 | ||
80 | /** | |
81 | * Determine whether this token-handler should be used with | |
82 | * the given processor. | |
83 | * | |
84 | * To short-circuit token-processing in irrelevant contexts, | |
85 | * override this. | |
86 | * | |
87 | * @param \Civi\Token\TokenProcessor $processor | |
88 | * @return bool | |
89 | */ | |
90 | public function checkActive(\Civi\Token\TokenProcessor $processor) { | |
91 | return TRUE; | |
92 | } | |
93 | ||
94 | /** | |
95 | * Register the declared tokens. | |
96 | * | |
34f3bbd9 | 97 | * @param \Civi\Token\Event\TokenRegisterEvent $e |
46f5566c TO |
98 | * The registration event. Add new tokens using register(). |
99 | */ | |
100 | public function registerTokens(TokenRegisterEvent $e) { | |
101 | if (!$this->checkActive($e->getTokenProcessor())) { | |
102 | return; | |
103 | } | |
104 | foreach ($this->tokenNames as $name => $label) { | |
c64f69d9 | 105 | $e->register([ |
46f5566c TO |
106 | 'entity' => $this->entity, |
107 | 'field' => $name, | |
108 | 'label' => $label, | |
c64f69d9 | 109 | ]); |
46f5566c TO |
110 | } |
111 | } | |
112 | ||
f9ec2da6 TO |
113 | /** |
114 | * Alter the query which prepopulates mailing data | |
115 | * for scheduled reminders. | |
116 | * | |
117 | * This is method is not always appropriate, but if you're specifically | |
118 | * focused on scheduled reminders, it can be convenient. | |
119 | * | |
34f3bbd9 | 120 | * @param \Civi\ActionSchedule\Event\MailingQueryEvent $e |
f9ec2da6 TO |
121 | * The pending query which may be modified. See discussion on |
122 | * MailingQueryEvent::$query. | |
123 | */ | |
124 | public function alterActionScheduleQuery(MailingQueryEvent $e) { | |
125 | } | |
126 | ||
46f5566c TO |
127 | /** |
128 | * Populate the token data. | |
129 | * | |
34f3bbd9 | 130 | * @param \Civi\Token\Event\TokenValueEvent $e |
46f5566c TO |
131 | * The event, which includes a list of rows and tokens. |
132 | */ | |
133 | public function evaluateTokens(TokenValueEvent $e) { | |
134 | if (!$this->checkActive($e->getTokenProcessor())) { | |
135 | return; | |
136 | } | |
e0c75385 | 137 | |
52883911 AS |
138 | $this->activeTokens = $this->getActiveTokens($e); |
139 | if (!$this->activeTokens) { | |
e0c75385 TO |
140 | return; |
141 | } | |
46f5566c | 142 | $prefetch = $this->prefetch($e); |
e0c75385 | 143 | |
46f5566c | 144 | foreach ($e->getRows() as $row) { |
52883911 | 145 | foreach ($this->activeTokens as $field) { |
46f5566c TO |
146 | $this->evaluateToken($row, $this->entity, $field, $prefetch); |
147 | } | |
148 | } | |
149 | } | |
150 | ||
eb969099 AS |
151 | /** |
152 | * To handle variable tokens, override this function and return the active tokens. | |
153 | * | |
154 | * @param \Civi\Token\Event\TokenValueEvent $e | |
155 | * | |
156 | * @return mixed | |
157 | */ | |
158 | public function getActiveTokens(TokenValueEvent $e) { | |
159 | $messageTokens = $e->getTokenProcessor()->getMessageTokens(); | |
160 | if (!isset($messageTokens[$this->entity])) { | |
161 | return FALSE; | |
162 | } | |
163 | return array_intersect($messageTokens[$this->entity], array_keys($this->tokenNames)); | |
164 | } | |
165 | ||
46f5566c TO |
166 | /** |
167 | * To perform a bulk lookup before rendering tokens, override this | |
168 | * function and return the prefetched data. | |
169 | * | |
54957108 | 170 | * @param \Civi\Token\Event\TokenValueEvent $e |
171 | * | |
46f5566c TO |
172 | * @return mixed |
173 | */ | |
174 | public function prefetch(TokenValueEvent $e) { | |
175 | return NULL; | |
176 | } | |
177 | ||
178 | /** | |
179 | * Evaluate the content of a single token. | |
180 | * | |
181 | * @param TokenRow $row | |
182 | * The record for which we want token values. | |
183 | * @param string $entity | |
184 | * The name of the token entity. | |
185 | * @param string $field | |
186 | * The name of the token field. | |
187 | * @param mixed $prefetch | |
188 | * Any data that was returned by the prefetch(). | |
46f5566c | 189 | */ |
34f3bbd9 | 190 | abstract public function evaluateToken(TokenRow $row, $entity, $field, $prefetch = NULL); |
46f5566c TO |
191 | |
192 | } |