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 custom field token.
 131    *
 132    * @param string $entity
 133    * @param int $customFieldID
 134    * @param int $entityID
 135    * @return TokenRow
 136    */
 137   public function customToken($entity, $customFieldID, $entityID) {
 138     $customFieldName = "custom_" . $customFieldID;
 139     $record = civicrm_api3($entity, "getSingle", [
 140       'return' => $customFieldName,
 141        'id' => $entityID,
 142     ]);
 143     $fieldValue = \CRM_Utils_Array::value($customFieldName, $record, '');
 144
 145     // format the raw custom field value into proper display value
 146     if (isset($fieldValue)) {
 147       $fieldValue = \CRM_Core_BAO_CustomField::displayValue($fieldValue, $customFieldID);
 148     }
 149
 150     return $this->tokens($entity, $customFieldName, $fieldValue);
 151   }
 152
 153   /**
 154    * Update the value of a token. Apply formatting based on DB schema.
 155    *
 156    * @param string $tokenEntity
 157    * @param string $tokenField
 158    * @param string $baoName
 159    * @param array $baoField
 160    * @param mixed $fieldValue
 161    * @return TokenRow
 162    * @throws \CRM_Core_Exception
 163    */
 164   public function dbToken($tokenEntity, $tokenField, $baoName, $baoField, $fieldValue) {
 165     if ($fieldValue === NULL || $fieldValue === '') {
 166       return $this->tokens($tokenEntity, $tokenField, '');
 167     }
 168
 169     $fields = $baoName::fields();
 170     if (!empty($fields[$baoField]['pseudoconstant'])) {
 171       $options = $baoName::buildOptions($baoField, 'get');
 172       return $this->format('text/plain')->tokens($tokenEntity, $tokenField, $options[$fieldValue]);
 173     }
 174
 175     switch ($fields[$baoField]['type']) {
 176       case \CRM_Utils_Type::T_DATE + \CRM_Utils_Type::T_TIME:
 177         return $this->format('text/plain')->tokens($tokenEntity, $tokenField, \CRM_Utils_Date::customFormat($fieldValue));
 178
 179       case \CRM_Utils_Type::T_MONEY:
 180         // Is this something you should ever use? Seems like you need more context
 181         // to know which currency to use.
 182         return $this->format('text/plain')->tokens($tokenEntity, $tokenField, \CRM_Utils_Money::format($fieldValue));
 183
 184       case \CRM_Utils_Type::T_STRING:
 185       case \CRM_Utils_Type::T_BOOLEAN:
 186       case \CRM_Utils_Type::T_INT:
 187       case \CRM_Utils_Type::T_TEXT:
 188         return $this->format('text/plain')->tokens($tokenEntity, $tokenField, $fieldValue);
 189
 190     }
 191
 192     throw new \CRM_Core_Exception("Cannot format token for field '$baoField' in '$baoName'");
 193   }
 194
 195   /**
 196    * Auto-convert between different formats
 197    *
 198    * @param string $format
 199    *
 200    * @return TokenRow
 201    */
 202   public function fill($format = NULL) {
 203     if ($format === NULL) {
 204       $format = $this->format;
 205     }
 206
 207     if (!isset($this->tokenProcessor->rowValues[$this->tokenRow]['text/html'])) {
 208       $this->tokenProcessor->rowValues[$this->tokenRow]['text/html'] = [];
 209     }
 210     if (!isset($this->tokenProcessor->rowValues[$this->tokenRow]['text/plain'])) {
 211       $this->tokenProcessor->rowValues[$this->tokenRow]['text/plain'] = [];
 212     }
 213
 214     $htmlTokens = &$this->tokenProcessor->rowValues[$this->tokenRow]['text/html'];
 215     $textTokens = &$this->tokenProcessor->rowValues[$this->tokenRow]['text/plain'];
 216
 217     switch ($format) {
 218       case 'text/html':
 219         // Plain => HTML.
 220         foreach ($textTokens as $entity => $values) {
 221           $entityFields = civicrm_api3($entity, "getFields", ['api_action' => 'get']);
 222           foreach ($values as $field => $value) {
 223             if (!isset($htmlTokens[$entity][$field])) {
 224               // CRM-18420 - Activity Details Field are enclosed within <p>,
 225               // hence if $body_text is empty, htmlentities will lead to
 226               // conversion of these tags resulting in raw HTML.
 227               if ($entity == 'activity' && $field == 'details') {
 228                 $htmlTokens[$entity][$field] = $value;
 229               }
 230               elseif (\CRM_Utils_Array::value('data_type', \CRM_Utils_Array::value($field, $entityFields['values'])) == 'Memo') {
 231                 // Memo fields aka custom fields of type Note are html.
 232                 $htmlTokens[$entity][$field] = CRM_Utils_String::purifyHTML($value);
 233               }
 234               else {
 235                 $htmlTokens[$entity][$field] = htmlentities($value);
 236               }
 237             }
 238           }
 239         }
 240         break;
 241
 242       case 'text/plain':
 243         // HTML => Plain.
 244         foreach ($htmlTokens as $entity => $values) {
 245           foreach ($values as $field => $value) {
 246             if (!isset($textTokens[$entity][$field])) {
 247               $textTokens[$entity][$field] = html_entity_decode(strip_tags($value));
 248             }
 249           }
 250         }
 251         break;
 252
 253       default:
 254         throw new \RuntimeException("Invalid format");
 255     }
 256
 257     return $this;
 258   }
 259
 260   /**
 261    * Render a message.
 262    *
 263    * @param string $name
 264    *   The name previously registered with TokenProcessor::addMessage.
 265    * @return string
 266    *   Fully rendered message, with tokens merged.
 267    */
 268   public function render($name) {
 269     return $this->tokenProcessor->render($name, $this);
 270   }
 271
 272 }
 273
 274 /**
 275  * Class TokenRowContext
 276  * @package Civi\Token
 277  *
 278  * Combine the row-context and general-context into a single array-like facade.
 279  */
 280 class TokenRowContext implements \ArrayAccess, \IteratorAggregate, \Countable {
 281
 282   /**
 283    * @var TokenProcessor
 284    */
 285   protected $tokenProcessor;
 286
 287   protected $tokenRow;
 288
 289   /**
 290    * Class constructor.
 291    *
 292    * @param array $tokenProcessor
 293    * @param array $tokenRow
 294    */
 295   public function __construct($tokenProcessor, $tokenRow) {
 296     $this->tokenProcessor = $tokenProcessor;
 297     $this->tokenRow = $tokenRow;
 298   }
 299
 300   /**
 301    * Does offset exist.
 302    *
 303    * @param mixed $offset
 304    *
 305    * @return bool
 306    */
 307   public function offsetExists($offset) {
 308     return
 309       isset($this->tokenProcessor->rowContexts[$this->tokenRow][$offset])
 310       || isset($this->tokenProcessor->context[$offset]);
 311   }
 312
 313   /**
 314    * Get offset.
 315    *
 316    * @param string $offset
 317    *
 318    * @return string
 319    */
 320   public function &offsetGet($offset) {
 321     if (isset($this->tokenProcessor->rowContexts[$this->tokenRow][$offset])) {
 322       return $this->tokenProcessor->rowContexts[$this->tokenRow][$offset];
 323     }
 324     if (isset($this->tokenProcessor->context[$offset])) {
 325       return $this->tokenProcessor->context[$offset];
 326     }
 327     $val = NULL;
 328     return $val;
 329   }
 330
 331   /**
 332    * Set offset.
 333    *
 334    * @param string $offset
 335    * @param mixed $value
 336    */
 337   public function offsetSet($offset, $value) {
 338     $this->tokenProcessor->rowContexts[$this->tokenRow][$offset] = $value;
 339   }
 340
 341   /**
 342    * Unset offset.
 343    *
 344    * @param mixed $offset
 345    */
 346   public function offsetUnset($offset) {
 347     unset($this->tokenProcessor->rowContexts[$this->tokenRow][$offset]);
 348   }
 349
 350   /**
 351    * Get iterator.
 352    *
 353    * @return \ArrayIterator
 354    */
 355   public function getIterator() {
 356     return new \ArrayIterator($this->createMergedArray());
 357   }
 358
 359   /**
 360    * Count.
 361    *
 362    * @return int
 363    */
 364   public function count() {
 365     return count($this->createMergedArray());
 366   }
 367
 368   /**
 369    * Create merged array.
 370    *
 371    * @return array
 372    */
 373   protected function createMergedArray() {
 374     return array_merge(
 375       $this->tokenProcessor->rowContexts[$this->tokenRow],
 376       $this->tokenProcessor->context
 377     );
 378   }
 379
 380 }