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