Civi/Token/AbstractTokenSubscriber.php

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