Civi/Token/AbstractTokenSubscriber.php

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