Civi/Token/TokenProcessor.php

   1 <?php
   2 namespace Civi\Token;
   3
   4 use Civi\Token\Event\TokenRegisterEvent;
   5 use Civi\Token\Event\TokenRenderEvent;
   6 use Civi\Token\Event\TokenValueEvent;
   7 use Symfony\Component\EventDispatcher\EventDispatcherInterface;
   8 use Traversable;
   9
  10 class TokenProcessor {
  11
  12   /**
  13    * @var array
  14    *   Description of the context in which the tokens are being processed.
  15    *   Ex: Array('class'=>'CRM_Core_BAO_ActionSchedule', 'schedule' => $dao, 'mapping' => $dao).
  16    *   Ex: Array('class'=>'CRM_Mailing_BAO_MailingJob', 'mailing' => $dao).
  17    *
  18    * For lack of a better place, here's a list of known/intended context values:
  19    *
  20    *   - controller: string, the class which is managing the mail-merge.
  21    *   - smarty: bool, whether to enable smarty support.
  22    *   - contactId: int, the main person/org discussed in the message.
  23    *   - contact: array, the main person/org discussed in the message.
  24    *     (Optional for performance tweaking; if omitted, will load
  25    *     automatically from contactId.)
  26    *   - actionSchedule: DAO, the rule which triggered the mailing
  27    *     [for CRM_Core_BAO_ActionScheduler].
  28    */
  29   public $context;
  30
  31   /**
  32    * @var EventDispatcherInterface
  33    */
  34   protected $dispatcher;
  35
  36   /**
  37    * @var array
  38    *   Each message is an array with keys:
  39    *    - string: Unprocessed message (eg "Hello, {display_name}.").
  40    *    - format: Media type (eg "text/plain").
  41    *    - tokens: List of tokens which are actually used in this message.
  42    */
  43   protected $messages;
  44
  45   /**
  46    * DO NOT access field this directly. Use TokenRow. This is
  47    * marked as public only to benefit TokenRow.
  48    *
  49    * @var array
  50    *   Array(int $pos => array $keyValues);
  51    */
  52   public $rowContexts;
  53
  54   /**
  55    * DO NOT access field this directly. Use TokenRow. This is
  56    * marked as public only to benefit TokenRow.
  57    *
  58    * @var array
  59    *   Ex: $rowValues[$rowPos][$format][$entity][$field] = 'something';
  60    *    Ex: $rowValues[3]['text/plain']['contact']['display_name'] = 'something';
  61    */
  62   public $rowValues;
  63
  64   /**
  65    * A list of available tokens
  66    * @var array
  67    *   Array(string $dottedName => array('entity'=>string, 'field'=>string, 'label'=>string)).
  68    */
  69   protected $tokens = NULL;
  70
  71   protected $next = 0;
  72
  73   /**
  74    * @param EventDispatcherInterface $dispatcher
  75    * @param array $context
  76    */
  77   public function __construct($dispatcher, $context) {
  78     $this->dispatcher = $dispatcher;
  79     $this->context = $context;
  80   }
  81
  82   /**
  83    * Register a string for which we'll need to merge in tokens.
  84    *
  85    * @param string $name
  86    *   Ex: 'subject', 'body_html'.
  87    * @param string $value
  88    *   Ex: '<p>Hello {contact.name}</p>'.
  89    * @param string $format
  90    *   Ex: 'text/html'.
  91    * @return TokenProcessor
  92    */
  93   public function addMessage($name, $value, $format) {
  94     $this->messages[$name] = array(
  95       'string' => $value,
  96       'format' => $format,
  97       'tokens' => \CRM_Utils_Token::getTokens($value),
  98     );
  99     return $this;
 100   }
 101
 102   /**
 103    * Add a row of data.
 104    *
 105    * @return TokenRow
 106    */
 107   public function addRow() {
 108     $key = $this->next++;
 109     $this->rowContexts[$key] = array();
 110     $this->rowValues[$key] = array(
 111       'text/plain' => array(),
 112       'text/html' => array(),
 113     );
 114
 115     return new TokenRow($this, $key);
 116   }
 117
 118   /**
 119    * @param array $params
 120    *   Array with keys:
 121    *    - entity: string, e.g. "profile".
 122    *    - field: string, e.g. "viewUrl".
 123    *    - label: string, e.g. "Default Profile URL (View Mode)".
 124    * @return TokenProcessor
 125    */
 126   public function addToken($params) {
 127     $key = $params['entity'] . '.' . $params['field'];
 128     $this->tokens[$key] = $params;
 129     return $this;
 130   }
 131
 132   /**
 133    * @param string $name
 134    * @return array
 135    *   Keys:
 136    *    - string: Unprocessed message (eg "Hello, {display_name}.").
 137    *    - format: Media type (eg "text/plain").
 138    */
 139   public function getMessage($name) {
 140     return $this->messages[$name];
 141   }
 142
 143   /**
 144    * Get a list of all tokens used in registered messages.
 145    *
 146    * @return array
 147    */
 148   public function getMessageTokens() {
 149     $tokens = array();
 150     foreach ($this->messages as $message) {
 151       $tokens = \CRM_Utils_Array::crmArrayMerge($tokens, $message['tokens']);
 152     }
 153     foreach (array_keys($tokens) as $e) {
 154       $tokens[$e] = array_unique($tokens[$e]);
 155       sort($tokens[$e]);
 156     }
 157     return $tokens;
 158   }
 159
 160   public function getRow($key) {
 161     return new TokenRow($this, $key);
 162   }
 163
 164   /**
 165    * @return \Traversable<TokenRow>
 166    */
 167   public function getRows() {
 168     return new TokenRowIterator($this, new \ArrayIterator($this->rowContexts));
 169   }
 170
 171   /**
 172    * Get a list of all unique values for a given context field,
 173    * whether defined at the processor or row level.
 174    *
 175    * @param string $field
 176    *   Ex: 'contactId'.
 177    * @return array
 178    *   Ex: [12, 34, 56].
 179    */
 180   public function getContextValues($field, $subfield = NULL) {
 181     $values = [];
 182     if (isset($this->context[$field])) {
 183       if ($subfield) {
 184         if (isset($this->context[$field]->$subfield)) {
 185           $values[] = $this->context[$field]->$subfield;
 186         }
 187       }
 188       else {
 189         $values[] = $this->context[$field];
 190       }
 191     }
 192     foreach ($this->getRows() as $row) {
 193       if (isset($row->context[$field])) {
 194         if ($subfield) {
 195           if (isset($row->context[$field]->$subfield)) {
 196             $values[] = $row->context[$field]->$subfield;
 197           }
 198         }
 199         else {
 200           $values[] = $row->context[$field];
 201         }
 202       }
 203     }
 204     $values = array_unique($values);
 205     return $values;
 206   }
 207
 208   /**
 209    * Get the list of available tokens.
 210    *
 211    * @return array
 212    *   Ex: $tokens['event'] = array('location', 'start_date', 'end_date').
 213    */
 214   public function getTokens() {
 215     if ($this->tokens === NULL) {
 216       $this->tokens = array();
 217       $event = new TokenRegisterEvent($this, array('entity' => 'undefined'));
 218       $this->dispatcher->dispatch(Events::TOKEN_REGISTER, $event);
 219     }
 220     return $this->tokens;
 221   }
 222
 223   /**
 224    * Compute and store token values.
 225    */
 226   public function evaluate() {
 227     $event = new TokenValueEvent($this);
 228     $this->dispatcher->dispatch(Events::TOKEN_EVALUATE, $event);
 229     return $this;
 230   }
 231
 232   /**
 233    * Render a message.
 234    *
 235    * @param string $name
 236    *   The name previously registered with addMessage().
 237    * @param TokenRow|int $row
 238    *   The object or ID for the row previously registered with addRow().
 239    * @return string
 240    *   Fully rendered message, with tokens merged.
 241    */
 242   public function render($name, $row) {
 243     if (!is_object($row)) {
 244       $row = $this->getRow($row);
 245     }
 246
 247     $message = $this->getMessage($name);
 248     $row->fill($message['format']);
 249     $useSmarty = !empty($row->context['smarty']);
 250
 251     // FIXME preg_callback.
 252     $tokens = $this->rowValues[$row->tokenRow][$message['format']];
 253     $flatTokens = array();
 254     \CRM_Utils_Array::flatten($tokens, $flatTokens, '', '.');
 255     $filteredTokens = array();
 256     foreach ($flatTokens as $k => $v) {
 257       $filteredTokens['{' . $k . '}'] = ($useSmarty ? \CRM_Utils_Token::tokenEscapeSmarty($v) : $v);
 258     }
 259
 260     $event = new TokenRenderEvent($this);
 261     $event->message = $message;
 262     $event->context = $row->context;
 263     $event->row = $row;
 264     $event->string = strtr($message['string'], $filteredTokens);
 265     $this->dispatcher->dispatch(Events::TOKEN_RENDER, $event);
 266     return $event->string;
 267   }
 268
 269 }
 270
 271 class TokenRowIterator extends \IteratorIterator {
 272
 273   protected $tokenProcessor;
 274
 275   /**
 276    * @param TokenProcessor $tokenProcessor
 277    * @param Traversable $iterator
 278    */
 279   public function __construct(TokenProcessor $tokenProcessor, Traversable $iterator) {
 280     parent::__construct($iterator); // TODO: Change the autogenerated stub
 281     $this->tokenProcessor = $tokenProcessor;
 282   }
 283
 284   public function current() {
 285     return new TokenRow($this->tokenProcessor, parent::key());
 286   }
 287
 288 }