3 +--------------------------------------------------------------------+
4 | Copyright CiviCRM LLC. All rights reserved. |
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 +--------------------------------------------------------------------+
14 use Civi\ActionSchedule\Event\MailingQueryEvent
;
15 use Civi\Token\Event\TokenRegisterEvent
;
16 use Civi\Token\Event\TokenValueEvent
;
17 use Symfony\Component\EventDispatcher\EventSubscriberInterface
;
20 * Class AbstractTokenSubscriber
23 * AbstractTokenSubscriber is a base class which may be extended to
24 * implement tokens in a somewhat more concise fashion.
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.
30 * 4. Optionally, override others:
34 * + alterActionScheduleMailing()
35 * 5. Register the new class with the event-dispatcher.
37 * Note: There's no obligation to use this base class. You could implement
38 * your own class anew -- just subscribe the proper events.
40 abstract class AbstractTokenSubscriber
implements EventSubscriberInterface
{
42 public static function getSubscribedEvents() {
44 'civi.token.list' => 'registerTokens',
45 'civi.token.eval' => 'evaluateTokens',
46 'civi.actionSchedule.prepareMailingQuery' => 'alterActionScheduleQuery',
52 * Ex: 'contact' or profile' or 'employer'
58 * List of tokens provided by this class
59 * Array(string $fieldName => string $label).
65 * List of active tokens - tokens provided by this class and used in the message
66 * Array(string $tokenName);
72 * @param array $tokenNames
73 * Array(string $tokenName => string $label).
75 public function __construct($entity, $tokenNames = []) {
76 $this->entity
= $entity;
77 $this->tokenNames
= $tokenNames;
81 * Determine whether this token-handler should be used with
82 * the given processor.
84 * To short-circuit token-processing in irrelevant contexts,
87 * @param \Civi\Token\TokenProcessor $processor
90 public function checkActive(\Civi\Token\TokenProcessor
$processor) {
95 * Register the declared tokens.
97 * @param \Civi\Token\Event\TokenRegisterEvent $e
98 * The registration event. Add new tokens using register().
100 public function registerTokens(TokenRegisterEvent
$e) {
101 if (!$this->checkActive($e->getTokenProcessor())) {
104 foreach ($this->tokenNames
as $name => $label) {
106 'entity' => $this->entity
,
114 * Alter the query which prepopulates mailing data
115 * for scheduled reminders.
117 * This is method is not always appropriate, but if you're specifically
118 * focused on scheduled reminders, it can be convenient.
120 * @param \Civi\ActionSchedule\Event\MailingQueryEvent $e
121 * The pending query which may be modified. See discussion on
122 * MailingQueryEvent::$query.
124 public function alterActionScheduleQuery(MailingQueryEvent
$e) {
128 * Populate the token data.
130 * @param \Civi\Token\Event\TokenValueEvent $e
131 * The event, which includes a list of rows and tokens.
133 public function evaluateTokens(TokenValueEvent
$e) {
134 if (!$this->checkActive($e->getTokenProcessor())) {
138 $this->activeTokens
= $this->getActiveTokens($e);
139 if (!$this->activeTokens
) {
142 $prefetch = $this->prefetch($e);
144 foreach ($e->getRows() as $row) {
145 foreach ($this->activeTokens
as $field) {
146 $this->evaluateToken($row, $this->entity
, $field, $prefetch);
152 * To handle variable tokens, override this function and return the active tokens.
154 * @param \Civi\Token\Event\TokenValueEvent $e
158 public function getActiveTokens(TokenValueEvent
$e) {
159 $messageTokens = $e->getTokenProcessor()->getMessageTokens();
160 if (!isset($messageTokens[$this->entity
])) {
163 return array_intersect($messageTokens[$this->entity
], array_keys($this->tokenNames
));
167 * To perform a bulk lookup before rendering tokens, override this
168 * function and return the prefetched data.
170 * @param \Civi\Token\Event\TokenValueEvent $e
174 public function prefetch(TokenValueEvent
$e) {
179 * Evaluate the content of a single token.
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().
191 abstract public function evaluateToken(TokenRow
$row, $entity, $field, $prefetch = NULL);