Civi/Token/AbstractTokenSubscriber.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 4.7                                                |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2015                                |
   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    * Alter the query which prepopulates mailing data
 122    * for scheduled reminders.
 123    *
 124    * This is method is not always appropriate, but if you're specifically
 125    * focused on scheduled reminders, it can be convenient.
 126    *
 127    * @param MailingQueryEvent $e
 128    *   The pending query which may be modified. See discussion on
 129    *   MailingQueryEvent::$query.
 130    */
 131   public function alterActionScheduleQuery(MailingQueryEvent $e) {
 132   }
 133
 134   /**
 135    * Populate the token data.
 136    *
 137    * @param TokenValueEvent $e
 138    *   The event, which includes a list of rows and tokens.
 139    */
 140   public function evaluateTokens(TokenValueEvent $e) {
 141     if (!$this->checkActive($e->getTokenProcessor())) {
 142       return;
 143     }
 144     // TODO: check if any tokens for $entity are actually used; short-circuit.
 145     $prefetch = $this->prefetch($e);
 146     foreach ($e->getRows() as $row) {
 147       foreach ($this->tokenNames as $field => $label) {
 148         $this->evaluateToken($row, $this->entity, $field, $prefetch);
 149       }
 150     }
 151   }
 152
 153   /**
 154    * To perform a bulk lookup before rendering tokens, override this
 155    * function and return the prefetched data.
 156    *
 157    * @param \Civi\Token\Event\TokenValueEvent $e
 158    *
 159    * @return mixed
 160    */
 161   public function prefetch(TokenValueEvent $e) {
 162     return NULL;
 163   }
 164
 165   /**
 166    * Evaluate the content of a single token.
 167    *
 168    * @param TokenRow $row
 169    *   The record for which we want token values.
 170    * @param string $entity
 171    *   The name of the token entity.
 172    * @param string $field
 173    *   The name of the token field.
 174    * @param mixed $prefetch
 175    *   Any data that was returned by the prefetch().
 176    * @return mixed
 177    */
 178   public abstract function evaluateToken(TokenRow $row, $entity, $field, $prefetch = NULL);
 179
 180 }