3 +--------------------------------------------------------------------+
5 +--------------------------------------------------------------------+
6 | Copyright CiviCRM LLC (c) 2004-2019 |
7 +--------------------------------------------------------------------+
8 | This file is a part of CiviCRM. |
10 | CiviCRM is free software; you can copy, modify, and distribute it |
11 | under the terms of the GNU Affero General Public License |
12 | Version 3, 19 November 2007 and the CiviCRM Licensing Exception. |
14 | CiviCRM is distributed in the hope that it will be useful, but |
15 | WITHOUT ANY WARRANTY; without even the implied warranty of |
16 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. |
17 | See the GNU Affero General Public License for more details. |
19 | You should have received a copy of the GNU Affero General Public |
20 | License and the CiviCRM Licensing Exception along |
21 | with this program; if not, contact CiviCRM LLC |
22 | at info[AT]civicrm[DOT]org. If you have questions about the |
23 | GNU Affero General Public License or the licensing of CiviCRM, |
24 | see the CiviCRM license FAQ at http://civicrm.org/licensing |
25 +--------------------------------------------------------------------+
30 use Civi\ActionSchedule\Event\MailingQueryEvent
;
31 use Civi\Token\Event\TokenRegisterEvent
;
32 use Civi\Token\Event\TokenValueEvent
;
33 use Symfony\Component\EventDispatcher\EventSubscriberInterface
;
36 * Class AbstractTokenSubscriber
39 * AbstractTokenSubscriber is a base class which may be extended to
40 * implement tokens in a somewhat more concise fashion.
42 * To implement a new token handler based on this:
43 * 1. Create a subclass.
44 * 2. Override the constructor and set values for $entity and $tokenNames.
45 * 3. Implement the evaluateToken() method.
46 * 4. Optionally, override others:
50 * + alterActionScheduleMailing()
51 * 5. Register the new class with the event-dispatcher.
53 * Note: There's no obligation to use this base class. You could implement
54 * your own class anew -- just subscribe the proper events.
56 abstract class AbstractTokenSubscriber
implements EventSubscriberInterface
{
58 public static function getSubscribedEvents() {
60 Events
::TOKEN_REGISTER
=> 'registerTokens',
61 Events
::TOKEN_EVALUATE
=> 'evaluateTokens',
62 \Civi\ActionSchedule\Events
::MAILING_QUERY
=> 'alterActionScheduleQuery',
68 * Ex: 'contact' or profile' or 'employer'
74 * List of tokens provided by this class
75 * Array(string $fieldName => string $label).
81 * List of active tokens - tokens provided by this class and used in the message
82 * Array(string $tokenName);
88 * @param array $tokenNames
89 * Array(string $tokenName => string $label).
91 public function __construct($entity, $tokenNames = array()) {
92 $this->entity
= $entity;
93 $this->tokenNames
= $tokenNames;
97 * Determine whether this token-handler should be used with
98 * the given processor.
100 * To short-circuit token-processing in irrelevant contexts,
103 * @param \Civi\Token\TokenProcessor $processor
106 public function checkActive(\Civi\Token\TokenProcessor
$processor) {
111 * Register the declared tokens.
113 * @param TokenRegisterEvent $e
114 * The registration event. Add new tokens using register().
116 public function registerTokens(TokenRegisterEvent
$e) {
117 if (!$this->checkActive($e->getTokenProcessor())) {
120 foreach ($this->tokenNames
as $name => $label) {
122 'entity' => $this->entity
,
130 * Alter the query which prepopulates mailing data
131 * for scheduled reminders.
133 * This is method is not always appropriate, but if you're specifically
134 * focused on scheduled reminders, it can be convenient.
136 * @param MailingQueryEvent $e
137 * The pending query which may be modified. See discussion on
138 * MailingQueryEvent::$query.
140 public function alterActionScheduleQuery(MailingQueryEvent
$e) {
144 * Populate the token data.
146 * @param TokenValueEvent $e
147 * The event, which includes a list of rows and tokens.
149 public function evaluateTokens(TokenValueEvent
$e) {
150 if (!$this->checkActive($e->getTokenProcessor())) {
154 $this->activeTokens
= $this->getActiveTokens($e);
155 if (!$this->activeTokens
) {
158 $prefetch = $this->prefetch($e);
160 foreach ($e->getRows() as $row) {
161 foreach ($this->activeTokens
as $field) {
162 $this->evaluateToken($row, $this->entity
, $field, $prefetch);
168 * To handle variable tokens, override this function and return the active tokens.
170 * @param \Civi\Token\Event\TokenValueEvent $e
174 public function getActiveTokens(TokenValueEvent
$e) {
175 $messageTokens = $e->getTokenProcessor()->getMessageTokens();
176 if (!isset($messageTokens[$this->entity
])) {
179 return array_intersect($messageTokens[$this->entity
], array_keys($this->tokenNames
));
183 * To perform a bulk lookup before rendering tokens, override this
184 * function and return the prefetched data.
186 * @param \Civi\Token\Event\TokenValueEvent $e
190 public function prefetch(TokenValueEvent
$e) {
195 * Evaluate the content of a single token.
197 * @param TokenRow $row
198 * The record for which we want token values.
199 * @param string $entity
200 * The name of the token entity.
201 * @param string $field
202 * The name of the token field.
203 * @param mixed $prefetch
204 * Any data that was returned by the prefetch().
207 public abstract function evaluateToken(TokenRow
$row, $entity, $field, $prefetch = NULL);