Civi/Token/TokenRow.php

   1 <?php
   2 namespace Civi\Token;
   3
   4 /**
   5  * Class TokenRow
   6  * @package Civi\Token
   7  *
   8  * A TokenRow is a helper providing simplified access to the
   9  * TokenProcessor.
  10  *
  11  * A TokenRow combines two elements:
  12  *   - context: This is backend data provided by the controller.
  13  *   - tokens: This is frontend data that can be mail-merged.
  14  *
  15  * The context and tokens can be accessed using either methods
  16  * or attributes. The methods are appropriate for updates
  17  * (and generally accept a mix of arrays), and the attributes
  18  * are appropriate for reads.
  19  *
  20  * To update the context or the tokens, use the methods.
  21  * Note that the methods are fairly flexible about accepting
  22  * single values or arrays. If given an array, the values
  23  * will be merged recursively.
  24  *
  25  * @code
  26  * $row
  27  *   ->context('contact_id', 123)
  28  *   ->context(array('contact_id' => 123))
  29  *   ->tokens('profile', array('viewUrl' => 'http://example.com'))
  30  *   ->tokens('profile', 'viewUrl, 'http://example.com');
  31  *
  32  * echo $row->context['contact_id'];
  33  * echo $row->tokens['profile']['viewUrl'];
  34  *
  35  * $row->tokens('profile', array(
  36  *   'viewUrl' => 'http://example.com/view/' . urlencode($row->context['contact_id'];
  37  * ));
  38  * @endcode
  39  */
  40 class TokenRow {
  41
  42   /**
  43    * @var TokenProcessor
  44    */
  45   public $tokenProcessor;
  46
  47   public $tokenRow;
  48
  49   public $format;
  50
  51   /**
  52    * @var array|\ArrayAccess
  53    *   List of token values.
  54    *   Ex: array('contact' => array('display_name' => 'Alice')).
  55    */
  56   public $tokens;
  57
  58   /**
  59    * @var array|\ArrayAccess
  60    *   List of context values.
  61    *   Ex: array('controller' => 'CRM_Foo_Bar').
  62    */
  63   public $context;
  64
  65   public function __construct(TokenProcessor $tokenProcessor, $key) {
  66     $this->tokenProcessor = $tokenProcessor;
  67     $this->tokenRow = $key;
  68     $this->format('text/plain'); // Set a default.
  69     $this->context = new TokenRowContext($tokenProcessor, $key);
  70   }
  71
  72   /**
  73    * @param string $format
  74    * @return TokenRow
  75    */
  76   public function format($format) {
  77     $this->format = $format;
  78     $this->tokens = &$this->tokenProcessor->rowValues[$this->tokenRow][$format];
  79     return $this;
  80   }
  81
  82   /**
  83    * Update the value of a context element.
  84    *
  85    * @param string|array $a
  86    * @param mixed $b
  87    * @return TokenRow
  88    */
  89   public function context($a = NULL, $b = NULL) {
  90     if (is_array($a)) {
  91       \CRM_Utils_Array::extend($this->tokenProcessor->rowContexts[$this->tokenRow], $a);
  92     }
  93     elseif (is_array($b)) {
  94       \CRM_Utils_Array::extend($this->tokenProcessor->rowContexts[$this->tokenRow][$a], $b);
  95     }
  96     else {
  97       $this->tokenProcessor->rowContexts[$this->tokenRow][$a] = $b;
  98     }
  99     return $this;
 100   }
 101
 102   /**
 103    * Update the value of a token.
 104    *
 105    * @param string|array $a
 106    * @param string|array $b
 107    * @param mixed $c
 108    * @return TokenRow
 109    */
 110   public function tokens($a = NULL, $b = NULL, $c = NULL) {
 111     if (is_array($a)) {
 112       \CRM_Utils_Array::extend($this->tokens, $a);
 113     }
 114     elseif (is_array($b)) {
 115       \CRM_Utils_Array::extend($this->tokens[$a], $b);
 116     }
 117     elseif (is_array($c)) {
 118       \CRM_Utils_Array::extend($this->tokens[$a][$b], $c);
 119     }
 120     elseif ($c === NULL) {
 121       $this->tokens[$a] = $b;
 122     }
 123     else {
 124       $this->tokens[$a][$b] = $c;
 125     }
 126     return $this;
 127   }
 128
 129   /**
 130    * Update the value of a token. Apply formatting based on DB schema.
 131    *
 132    * @param string $tokenEntity
 133    * @param string $tokenField
 134    * @param string $baoName
 135    * @param array $baoField
 136    * @param mixed $fieldValue
 137    */
 138   public function dbToken($tokenEntity, $tokenField, $baoName, $baoField, $fieldValue) {
 139     if ($fieldValue === NULL || $fieldValue === '') {
 140       return $this->tokens($tokenEntity, $tokenField, '');
 141     }
 142
 143     $fields = $baoName::fields();
 144     if (!empty($fields[$baoField]['pseudoconstant'])) {
 145       $options = $baoName::buildOptions($baoField, 'get');
 146       return $this->format('text/plain')->tokens($tokenEntity, $tokenField, $options[$fieldValue]);
 147     }
 148
 149     switch ($fields[$baoField]['type']) {
 150       case \CRM_Utils_Type::T_DATE + \CRM_Utils_Type::T_TIME:
 151         return $this->format('text/plain')->tokens($tokenEntity, $tokenField, \CRM_Utils_Date::customFormat($fieldValue));
 152
 153       case \CRM_Utils_Type::T_MONEY:
 154         // Is this something you should ever use? Seems like you need more context
 155         // to know which currency to use.
 156         return $this->format('text/plain')->tokens($tokenEntity, $tokenField, \CRM_Utils_Money::format($fieldValue));
 157
 158       case \CRM_Utils_Type::T_STRING:
 159       case \CRM_Utils_Type::T_BOOLEAN:
 160       case \CRM_Utils_Type::T_INT:
 161       case \CRM_Utils_Type::T_TEXT:
 162         return $this->format('text/plain')->tokens($tokenEntity, $tokenField, $fieldValue);
 163
 164     }
 165
 166     throw new \CRM_Core_Exception("Cannot format token for field '$baoField' in '$baoName'");
 167   }
 168
 169   /**
 170    * Auto-convert between different formats
 171    *
 172    * @param string $format
 173    *
 174    * @return TokenRow
 175    */
 176   public function fill($format = NULL) {
 177     if ($format === NULL) {
 178       $format = $this->format;
 179     }
 180
 181     if (!isset($this->tokenProcessor->rowValues[$this->tokenRow]['text/html'])) {
 182       $this->tokenProcessor->rowValues[$this->tokenRow]['text/html'] = array();
 183     }
 184     if (!isset($this->tokenProcessor->rowValues[$this->tokenRow]['text/plain'])) {
 185       $this->tokenProcessor->rowValues[$this->tokenRow]['text/plain'] = array();
 186     }
 187
 188     $htmlTokens = &$this->tokenProcessor->rowValues[$this->tokenRow]['text/html'];
 189     $textTokens = &$this->tokenProcessor->rowValues[$this->tokenRow]['text/plain'];
 190
 191     switch ($format) {
 192       case 'text/html':
 193         // Plain => HTML.
 194         foreach ($textTokens as $entity => $values) {
 195           foreach ($values as $field => $value) {
 196             if (!isset($htmlTokens[$entity][$field])) {
 197               // CRM-18420 - Activity Details Field are enclosed within <p>,
 198               // hence if $body_text is empty, htmlentities will lead to
 199               // conversion of these tags resulting in raw HTML.
 200               if ($entity == 'activity' && $field == 'details') {
 201                 $htmlTokens[$entity][$field] = $value;
 202               }
 203               else {
 204                 $htmlTokens[$entity][$field] = htmlentities($value);
 205               }
 206             }
 207           }
 208         }
 209         break;
 210
 211       case 'text/plain':
 212         // HTML => Plain.
 213         foreach ($htmlTokens as $entity => $values) {
 214           foreach ($values as $field => $value) {
 215             if (!isset($textTokens[$entity][$field])) {
 216               $textTokens[$entity][$field] = html_entity_decode(strip_tags($value));
 217             }
 218           }
 219         }
 220         break;
 221
 222       default:
 223         throw new \RuntimeException("Invalid format");
 224     }
 225
 226     return $this;
 227   }
 228
 229   /**
 230    * Render a message.
 231    *
 232    * @param string $name
 233    *   The name previously registered with TokenProcessor::addMessage.
 234    * @return string
 235    *   Fully rendered message, with tokens merged.
 236    */
 237   public function render($name) {
 238     return $this->tokenProcessor->render($name, $this);
 239   }
 240
 241 }
 242
 243 /**
 244  * Class TokenRowContext
 245  * @package Civi\Token
 246  *
 247  * Combine the row-context and general-context into a single array-like facade.
 248  */
 249 class TokenRowContext implements \ArrayAccess, \IteratorAggregate, \Countable {
 250
 251   /**
 252    * @var TokenProcessor
 253    */
 254   protected $tokenProcessor;
 255
 256   protected $tokenRow;
 257
 258   /**
 259    * Class constructor.
 260    *
 261    * @param array $tokenProcessor
 262    * @param array $tokenRow
 263    */
 264   public function __construct($tokenProcessor, $tokenRow) {
 265     $this->tokenProcessor = $tokenProcessor;
 266     $this->tokenRow = $tokenRow;
 267   }
 268
 269   /**
 270    * Does offset exist.
 271    *
 272    * @param mixed $offset
 273    *
 274    * @return bool
 275    */
 276   public function offsetExists($offset) {
 277     return
 278       isset($this->tokenProcessor->rowContexts[$this->tokenRow][$offset])
 279       || isset($this->tokenProcessor->context[$offset]);
 280   }
 281
 282   /**
 283    * Get offset.
 284    *
 285    * @param string $offset
 286    *
 287    * @return string
 288    */
 289   public function &offsetGet($offset) {
 290     if (isset($this->tokenProcessor->rowContexts[$this->tokenRow][$offset])) {
 291       return $this->tokenProcessor->rowContexts[$this->tokenRow][$offset];
 292     }
 293     if (isset($this->tokenProcessor->context[$offset])) {
 294       return $this->tokenProcessor->context[$offset];
 295     }
 296     $val = NULL;
 297     return $val;
 298   }
 299
 300   /**
 301    * Set offset.
 302    *
 303    * @param string $offset
 304    * @param mixed $value
 305    */
 306   public function offsetSet($offset, $value) {
 307     $this->tokenProcessor->rowContexts[$this->tokenRow][$offset] = $value;
 308   }
 309
 310   /**
 311    * Unset offset.
 312    *
 313    * @param mixed $offset
 314    */
 315   public function offsetUnset($offset) {
 316     unset($this->tokenProcessor->rowContexts[$this->tokenRow][$offset]);
 317   }
 318
 319   /**
 320    * Get iterator.
 321    *
 322    * @return \ArrayIterator
 323    */
 324   public function getIterator() {
 325     return new \ArrayIterator($this->createMergedArray());
 326   }
 327
 328   /**
 329    * Count.
 330    *
 331    * @return int
 332    */
 333   public function count() {
 334     return count($this->createMergedArray());
 335   }
 336
 337   /**
 338    * Create merged array.
 339    *
 340    * @return array
 341    */
 342   protected function createMergedArray() {
 343     return array_merge(
 344       $this->tokenProcessor->rowContexts[$this->tokenRow],
 345       $this->tokenProcessor->context
 346     );
 347   }
 348
 349 }