CRM/Utils/Token.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 4.6                                                |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2014                                |
   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 /**
  29  *
  30  * @package CRM
  31  * @copyright CiviCRM LLC (c) 2004-2014
  32  * $Id: $
  33  *
  34  */
  35
  36 /**
  37  * Class to abstract token replacement
  38  */
  39 class CRM_Utils_Token {
  40   static $_requiredTokens = NULL;
  41
  42   static $_tokens = array(
  43     'action' => array(
  44       'forward',
  45       'optOut',
  46       'optOutUrl',
  47       'reply',
  48       'unsubscribe',
  49       'unsubscribeUrl',
  50       'resubscribe',
  51       'resubscribeUrl',
  52       'subscribeUrl',
  53     ),
  54     'mailing' => array(
  55       'id',
  56       'name',
  57       'group',
  58       'subject',
  59       'viewUrl',
  60       'editUrl',
  61       'scheduleUrl',
  62       'approvalStatus',
  63       'approvalNote',
  64       'approveUrl',
  65       'creator',
  66       'creatorEmail',
  67     ),
  68     'user' => array(
  69       // we extract the stuff after the role / permission and return the
  70       // civicrm email addresses of all users with that role / permission
  71       // useful with rules integration
  72       'permission:',
  73       'role:',
  74     ),
  75     // populate this dynamically
  76     'contact' => NULL,
  77     // populate this dynamically
  78     'contribution' => NULL,
  79     'domain' => array(
  80       'name',
  81       'phone',
  82       'address',
  83       'email',
  84       'id',
  85       'description',
  86     ),
  87     'subscribe' => array('group'),
  88     'unsubscribe' => array('group'),
  89     'resubscribe' => array('group'),
  90     'welcome' => array('group'),
  91   );
  92
  93   /**
  94    * Check a string (mailing body) for required tokens.
  95    *
  96    * @param string $str
  97    *   The message.
  98    *
  99    * @return bool|array
 100    *    true if all required tokens are found,
 101    *    else an array of the missing tokens
 102    * @static
 103    */
 104   public static function requiredTokens(&$str) {
 105     if (self::$_requiredTokens == NULL) {
 106       self::$_requiredTokens = array(
 107         'domain.address' => ts("Domain address - displays your organization's postal address."),
 108         'action.optOutUrl or action.unsubscribeUrl' => array(
 109           'action.optOut' => ts("'Opt out via email' - displays an email address for recipients to opt out of receiving emails from your organization."),
 110           'action.optOutUrl' => ts("'Opt out via web page' - creates a link for recipients to click if they want to opt out of receiving emails from your organization. Alternatively, you can include the 'Opt out via email' token."),
 111           'action.unsubscribe' => ts("'Unsubscribe via email' - displays an email address for recipients to unsubscribe from the specific mailing list used to send this message."),
 112           'action.unsubscribeUrl' => ts("'Unsubscribe via web page' - creates a link for recipients to unsubscribe from the specific mailing list used to send this message. Alternatively, you can include the 'Unsubscribe via email' token or one of the Opt-out tokens."),
 113         ),
 114       );
 115     }
 116
 117     $missing = array();
 118     foreach (self::$_requiredTokens as $token => $value) {
 119       if (!is_array($value)) {
 120         if (!preg_match('/(^|[^\{])' . preg_quote('{' . $token . '}') . '/', $str)) {
 121           $missing[$token] = $value;
 122         }
 123       }
 124       else {
 125         $present = FALSE;
 126         $desc = NULL;
 127         foreach ($value as $t => $d) {
 128           $desc = $d;
 129           if (preg_match('/(^|[^\{])' . preg_quote('{' . $t . '}') . '/', $str)) {
 130             $present = TRUE;
 131           }
 132         }
 133         if (!$present) {
 134           $missing[$token] = $desc;
 135         }
 136       }
 137     }
 138
 139     if (empty($missing)) {
 140       return TRUE;
 141     }
 142     return $missing;
 143   }
 144
 145   /**
 146    * Wrapper for token matching
 147    *
 148    * @param string $type
 149    *   The token type (domain,mailing,contact,action).
 150    * @param string $var
 151    *   The token variable.
 152    * @param string $str
 153    *   The string to search.
 154    *
 155    * @return boolean
 156    *   Was there a match
 157    * @static
 158    */
 159   public static function token_match($type, $var, &$str) {
 160     $token = preg_quote('{' . "$type.$var") . '(\|.+?)?' . preg_quote('}');
 161     return preg_match("/(^|[^\{])$token/", $str);
 162   }
 163
 164   /**
 165    * Wrapper for token replacing
 166    *
 167    * @param string $type
 168    *   The token type.
 169    * @param string $var
 170    *   The token variable.
 171    * @param string $value
 172    *   The value to substitute for the token.
 173    * @param string (reference) $str The string to replace in
 174    *
 175    * @param bool $escapeSmarty
 176    *
 177    * @return string
 178    *   The processed string
 179    * @static
 180    */
 181   public static function &token_replace($type, $var, $value, &$str, $escapeSmarty = FALSE) {
 182     $token = preg_quote('{' . "$type.$var") . '(\|([^\}]+?))?' . preg_quote('}');
 183     if (!$value) {
 184       $value = '$3';
 185     }
 186     if ($escapeSmarty) {
 187       $value = self::tokenEscapeSmarty($value);
 188     }
 189     $str = preg_replace("/([^\{])?$token/", "\${1}$value", $str);
 190     return $str;
 191   }
 192
 193   /**
 194    * Get< the regex for token replacement
 195    *
 196    * @param string $token_type
 197    *   A string indicating the the type of token to be used in the expression.
 198    *
 199    * @return string
 200    *   regular expression sutiable for using in preg_replace
 201    * @static
 202    */
 203   private static function tokenRegex($token_type) {
 204     return '/(?<!\{|\\\\)\{' . $token_type . '\.([\w]+(\-[\w\s]+)?)\}(?!\})/';
 205   }
 206
 207   /**
 208    * Escape the string so a malicious user cannot inject smarty code into the template
 209    *
 210    * @param string $string
 211    *   A string that needs to be escaped from smarty parsing.
 212    *
 213    * @return string
 214    *   the escaped string
 215    * @static
 216    */
 217   private static function tokenEscapeSmarty($string) {
 218     // need to use negative look-behind, as both str_replace() and preg_replace() are sequential
 219     return preg_replace(array('/{/', '/(?<!{ldelim)}/'), array('{ldelim}', '{rdelim}'), $string);
 220   }
 221
 222   /**
 223    * Replace all the domain-level tokens in $str
 224    *
 225    * @param string $str
 226    *   The string with tokens to be replaced.
 227    * @param object $domain
 228    *   The domain BAO.
 229    * @param bool $html
 230    *   Replace tokens with HTML or plain text.
 231    *
 232    * @param null $knownTokens
 233    * @param bool $escapeSmarty
 234    *
 235    * @return string
 236    *   The processed string
 237    * @static
 238    */
 239   public static function &replaceDomainTokens(
 240     $str,
 241     &$domain,
 242     $html = FALSE,
 243     $knownTokens = NULL,
 244     $escapeSmarty = FALSE
 245   ) {
 246     $key = 'domain';
 247     if (
 248       !$knownTokens || empty($knownTokens[$key])
 249     ) {
 250       return $str;
 251     }
 252
 253     $str = preg_replace_callback(
 254       self::tokenRegex($key),
 255       function ($matches) use (&$domain, $html, $escapeSmarty) {
 256         return CRM_Utils_Token::getDomainTokenReplacement($matches[1], $domain, $html, $escapeSmarty);
 257       },
 258       $str
 259     );
 260     return $str;
 261   }
 262
 263   /**
 264    * @param $token
 265    * @param $domain
 266    * @param bool $html
 267    * @param bool $escapeSmarty
 268    *
 269    * @return mixed|null|string
 270    */
 271   public static function getDomainTokenReplacement($token, &$domain, $html = FALSE, $escapeSmarty = FALSE) {
 272     // check if the token we were passed is valid
 273     // we have to do this because this function is
 274     // called only when we find a token in the string
 275
 276     $loc = &$domain->getLocationValues();
 277
 278     if (!in_array($token, self::$_tokens['domain'])) {
 279       $value = "{domain.$token}";
 280     }
 281     elseif ($token == 'address') {
 282       static $addressCache = array();
 283
 284       $cache_key = $html ? 'address-html' : 'address-text';
 285       if (array_key_exists($cache_key, $addressCache)) {
 286         return $addressCache[$cache_key];
 287       }
 288
 289       $value = NULL;
 290       /* Construct the address token */
 291
 292       if (!empty($loc[$token])) {
 293         if ($html) {
 294           $value = $loc[$token][1]['display'];
 295           $value = str_replace("\n", '<br />', $value);
 296         }
 297         else {
 298           $value = $loc[$token][1]['display_text'];
 299         }
 300         $addressCache[$cache_key] = $value;
 301       }
 302     }
 303     elseif ($token == 'name' || $token == 'id' || $token == 'description') {
 304       $value = $domain->$token;
 305     }
 306     elseif ($token == 'phone' || $token == 'email') {
 307       /* Construct the phone and email tokens */
 308
 309       $value = NULL;
 310       if (!empty($loc[$token])) {
 311         foreach ($loc[$token] as $index => $entity) {
 312           $value = $entity[$token];
 313           break;
 314         }
 315       }
 316     }
 317
 318     if ($escapeSmarty) {
 319       $value = self::tokenEscapeSmarty($value);
 320     }
 321
 322     return $value;
 323   }
 324
 325   /**
 326    * Replace all the org-level tokens in $str
 327    *
 328    * @param string $str
 329    *   The string with tokens to be replaced.
 330    * @param object $org
 331    *   Associative array of org properties.
 332    * @param bool $html
 333    *   Replace tokens with HTML or plain text.
 334    *
 335    * @param bool $escapeSmarty
 336    *
 337    * @return string
 338    *   The processed string
 339    * @static
 340    */
 341   public static function &replaceOrgTokens($str, &$org, $html = FALSE, $escapeSmarty = FALSE) {
 342     self::$_tokens['org'] =
 343       array_merge(
 344         array_keys(CRM_Contact_BAO_Contact::importableFields('Organization')),
 345         array('address', 'display_name', 'checksum', 'contact_id')
 346       );
 347
 348     $cv = NULL;
 349     foreach (self::$_tokens['org'] as $token) {
 350       // print "Getting token value for $token<br/><br/>";
 351       if ($token == '') {
 352         continue;
 353       }
 354
 355       /* If the string doesn't contain this token, skip it. */
 356
 357       if (!self::token_match('org', $token, $str)) {
 358         continue;
 359       }
 360
 361       /* Construct value from $token and $contact */
 362
 363       $value = NULL;
 364
 365       if ($cfID = CRM_Core_BAO_CustomField::getKeyID($token)) {
 366         // only generate cv if we need it
 367         if ($cv === NULL) {
 368           $cv = CRM_Core_BAO_CustomValue::getContactValues($org['contact_id']);
 369         }
 370         foreach ($cv as $cvFieldID => $value) {
 371           if ($cvFieldID == $cfID) {
 372             $value = CRM_Core_BAO_CustomOption::getOptionLabel($cfID, $value);
 373             break;
 374           }
 375         }
 376       }
 377       elseif ($token == 'checksum') {
 378         $cs = CRM_Contact_BAO_Contact_Utils::generateChecksum($org['contact_id']);
 379         $value = "cs={$cs}";
 380       }
 381       elseif ($token == 'address') {
 382         /* Build the location values array */
 383
 384         $loc = array();
 385         $loc['display_name'] = CRM_Utils_Array::retrieveValueRecursive($org, 'display_name');
 386         $loc['street_address'] = CRM_Utils_Array::retrieveValueRecursive($org, 'street_address');
 387         $loc['city'] = CRM_Utils_Array::retrieveValueRecursive($org, 'city');
 388         $loc['state_province'] = CRM_Utils_Array::retrieveValueRecursive($org, 'state_province');
 389         $loc['postal_code'] = CRM_Utils_Array::retrieveValueRecursive($org, 'postal_code');
 390
 391         /* Construct the address token */
 392
 393         $value = CRM_Utils_Address::format($loc);
 394         if ($html) {
 395           $value = str_replace("\n", '<br />', $value);
 396         }
 397       }
 398       else {
 399         $value = CRM_Utils_Array::retrieveValueRecursive($org, $token);
 400       }
 401
 402       self::token_replace('org', $token, $value, $str, $escapeSmarty);
 403     }
 404
 405     return $str;
 406   }
 407
 408   /**
 409    * Replace all mailing tokens in $str
 410    *
 411    * @param string $str
 412    *   The string with tokens to be replaced.
 413    * @param object $mailing
 414    *   The mailing BAO, or null for validation.
 415    * @param bool $html
 416    *   Replace tokens with HTML or plain text.
 417    *
 418    * @param null $knownTokens
 419    * @param bool $escapeSmarty
 420    *
 421    * @return string
 422    *   The processed sstring
 423    * @static
 424    */
 425   public static function &replaceMailingTokens(
 426     $str,
 427     &$mailing,
 428     $html = FALSE,
 429     $knownTokens = NULL,
 430     $escapeSmarty = FALSE
 431   ) {
 432     $key = 'mailing';
 433     if (!$knownTokens || !isset($knownTokens[$key])) {
 434       return $str;
 435     }
 436
 437     $str = preg_replace_callback(
 438       self::tokenRegex($key),
 439       function ($matches) use (&$mailing, $escapeSmarty) {
 440         return CRM_Utils_Token::getMailingTokenReplacement($matches[1], $mailing, $escapeSmarty);
 441       },
 442       $str
 443     );
 444     return $str;
 445   }
 446
 447   /**
 448    * @param $token
 449    * @param $mailing
 450    * @param bool $escapeSmarty
 451    *
 452    * @return string
 453    */
 454   public static function getMailingTokenReplacement($token, &$mailing, $escapeSmarty = FALSE) {
 455     $value = '';
 456     switch ($token) {
 457       // CRM-7663
 458
 459       case 'id':
 460         $value = $mailing ? $mailing->id : 'undefined';
 461         break;
 462
 463       case 'name':
 464         $value = $mailing ? $mailing->name : 'Mailing Name';
 465         break;
 466
 467       case 'group':
 468         $groups = $mailing ? $mailing->getGroupNames() : array('Mailing Groups');
 469         $value = implode(', ', $groups);
 470         break;
 471
 472       case 'subject':
 473         $value = $mailing->subject;
 474         break;
 475
 476       case 'viewUrl':
 477         $mailingKey = $mailing->id;
 478         if ($hash = CRM_Mailing_BAO_Mailing::getMailingHash($mailingKey)) {
 479           $mailingKey = $hash;
 480         }
 481         $value = CRM_Utils_System::url('civicrm/mailing/view',
 482           "reset=1&id={$mailingKey}",
 483           TRUE, NULL, FALSE, TRUE
 484         );
 485         break;
 486
 487       case 'editUrl':
 488         $value = CRM_Utils_System::url('civicrm/mailing/send',
 489           "reset=1&mid={$mailing->id}&continue=true",
 490           TRUE, NULL, FALSE, TRUE
 491         );
 492         break;
 493
 494       case 'scheduleUrl':
 495         $value = CRM_Utils_System::url('civicrm/mailing/schedule',
 496           "reset=1&mid={$mailing->id}",
 497           TRUE, NULL, FALSE, TRUE
 498         );
 499         break;
 500
 501       case 'html':
 502         $page = new CRM_Mailing_Page_View();
 503         $value = $page->run($mailing->id, NULL, FALSE, TRUE);
 504         break;
 505
 506       case 'approvalStatus':
 507         $value = CRM_Core_PseudoConstant::getLabel('CRM_Mailing_DAO_Mailing', 'approval_status_id', $mailing->approval_status_id);
 508         break;
 509
 510       case 'approvalNote':
 511         $value = $mailing->approval_note;
 512         break;
 513
 514       case 'approveUrl':
 515         $value = CRM_Utils_System::url('civicrm/mailing/approve',
 516           "reset=1&mid={$mailing->id}",
 517           TRUE, NULL, FALSE, TRUE
 518         );
 519         break;
 520
 521       case 'creator':
 522         $value = CRM_Contact_BAO_Contact::displayName($mailing->created_id);
 523         break;
 524
 525       case 'creatorEmail':
 526         $value = CRM_Contact_BAO_Contact::getPrimaryEmail($mailing->created_id);
 527         break;
 528
 529       default:
 530         $value = "{mailing.$token}";
 531         break;
 532     }
 533
 534     if ($escapeSmarty) {
 535       $value = self::tokenEscapeSmarty($value);
 536     }
 537     return $value;
 538   }
 539
 540   /**
 541    * Replace all action tokens in $str
 542    *
 543    * @param string $str
 544    *   The string with tokens to be replaced.
 545    * @param array $addresses
 546    *   Assoc. array of VERP event addresses.
 547    * @param array $urls
 548    *   Assoc. array of action URLs.
 549    * @param bool $html
 550    *   Replace tokens with HTML or plain text.
 551    * @param array $knownTokens
 552    *   A list of tokens that are known to exist in the email body.
 553    *
 554    * @param bool $escapeSmarty
 555    *
 556    * @return string
 557    *   The processed string
 558    * @static
 559    */
 560   public static function &replaceActionTokens(
 561     $str,
 562     &$addresses,
 563     &$urls,
 564     $html = FALSE,
 565     $knownTokens = NULL,
 566     $escapeSmarty = FALSE
 567   ) {
 568     $key = 'action';
 569     // here we intersect with the list of pre-configured valid tokens
 570     // so that we remove anything we do not recognize
 571     // I hope to move this step out of here soon and
 572     // then we will just iterate on a list of tokens that are passed to us
 573     if (!$knownTokens || empty($knownTokens[$key])) {
 574       return $str;
 575     }
 576
 577     $str = preg_replace_callback(
 578       self::tokenRegex($key),
 579       function ($matches) use (&$addresses, &$urls, $html, $escapeSmarty) {
 580         return CRM_Utils_Token::getActionTokenReplacement($matches[1], $addresses, $urls, $html, $escapeSmarty);
 581       },
 582       $str
 583     );
 584     return $str;
 585   }
 586
 587   /**
 588    * @param $token
 589    * @param $addresses
 590    * @param $urls
 591    * @param bool $html
 592    * @param bool $escapeSmarty
 593    *
 594    * @return mixed|string
 595    */
 596   public static function getActionTokenReplacement(
 597     $token,
 598     &$addresses,
 599     &$urls,
 600     $html = FALSE,
 601     $escapeSmarty = FALSE
 602   ) {
 603     /* If the token is an email action, use it.  Otherwise, find the
 604          * appropriate URL */
 605
 606     if (!in_array($token, self::$_tokens['action'])) {
 607       $value = "{action.$token}";
 608     }
 609     else {
 610       $value = CRM_Utils_Array::value($token, $addresses);
 611
 612       if ($value == NULL) {
 613         $value = CRM_Utils_Array::value($token, $urls);
 614       }
 615
 616       if ($value && $html) {
 617         //fix for CRM-2318
 618         if ((substr($token, -3) != 'Url') && ($token != 'forward')) {
 619           $value = "mailto:$value";
 620         }
 621       }
 622       elseif ($value && !$html) {
 623         $value = str_replace('&amp;', '&', $value);
 624       }
 625     }
 626
 627     if ($escapeSmarty) {
 628       $value = self::tokenEscapeSmarty($value);
 629     }
 630     return $value;
 631   }
 632
 633   /**
 634    * Replace all the contact-level tokens in $str with information from
 635    * $contact.
 636    *
 637    * @param string $str
 638    *   The string with tokens to be replaced.
 639    * @param array $contact
 640    *   Associative array of contact properties.
 641    * @param bool $html
 642    *   Replace tokens with HTML or plain text.
 643    * @param array $knownTokens
 644    *   A list of tokens that are known to exist in the email body.
 645    * @param bool $returnBlankToken
 646    *   Return unevaluated token if value is null.
 647    *
 648    * @param bool $escapeSmarty
 649    *
 650    * @return string
 651    *   The processed string
 652    * @static
 653    */
 654   public static function &replaceContactTokens(
 655     $str,
 656     &$contact,
 657     $html = FALSE,
 658     $knownTokens = NULL,
 659     $returnBlankToken = FALSE,
 660     $escapeSmarty = FALSE
 661   ) {
 662     $key = 'contact';
 663     if (self::$_tokens[$key] == NULL) {
 664       /* This should come from UF */
 665
 666       self::$_tokens[$key] =
 667         array_merge(
 668           array_keys(CRM_Contact_BAO_Contact::exportableFields('All')),
 669           array('checksum', 'contact_id')
 670         );
 671     }
 672
 673     // here we intersect with the list of pre-configured valid tokens
 674     // so that we remove anything we do not recognize
 675     // I hope to move this step out of here soon and
 676     // then we will just iterate on a list of tokens that are passed to us
 677     if (!$knownTokens || empty($knownTokens[$key])) {
 678       return $str;
 679     }
 680
 681     $str = preg_replace_callback(
 682       self::tokenRegex($key),
 683       function ($matches) use (&$contact, $html, $returnBlankToken, $escapeSmarty) {
 684         return CRM_Utils_Token::getContactTokenReplacement($matches[1], $contact, $html, $returnBlankToken, $escapeSmarty);
 685       },
 686       $str
 687     );
 688
 689     $str = preg_replace('/\\\\|\{(\s*)?\}/', ' ', $str);
 690     return $str;
 691   }
 692
 693   /**
 694    * @param $token
 695    * @param $contact
 696    * @param bool $html
 697    * @param bool $returnBlankToken
 698    * @param bool $escapeSmarty
 699    *
 700    * @return bool|mixed|null|string
 701    */
 702   public static function getContactTokenReplacement(
 703     $token,
 704     &$contact,
 705     $html = FALSE,
 706     $returnBlankToken = FALSE,
 707     $escapeSmarty = FALSE
 708   ) {
 709     if (self::$_tokens['contact'] == NULL) {
 710       /* This should come from UF */
 711
 712       self::$_tokens['contact'] =
 713         array_merge(
 714           array_keys(CRM_Contact_BAO_Contact::exportableFields('All')),
 715           array('checksum', 'contact_id')
 716         );
 717     }
 718
 719     /* Construct value from $token and $contact */
 720
 721     $value = NULL;
 722     $noReplace = FALSE;
 723
 724     // Support legacy tokens
 725     $token = CRM_Utils_Array::value($token, self::legacyContactTokens(), $token);
 726
 727     // check if the token we were passed is valid
 728     // we have to do this because this function is
 729     // called only when we find a token in the string
 730
 731     if (!in_array($token, self::$_tokens['contact'])) {
 732       $noReplace = TRUE;
 733     }
 734     elseif ($token == 'checksum') {
 735       $hash = CRM_Utils_Array::value('hash', $contact);
 736       $contactID = CRM_Utils_Array::retrieveValueRecursive($contact, 'contact_id');
 737       $cs = CRM_Contact_BAO_Contact_Utils::generateChecksum($contactID,
 738         NULL,
 739         NULL,
 740         $hash
 741       );
 742       $value = "cs={$cs}";
 743     }
 744     else {
 745       $value = CRM_Utils_Array::retrieveValueRecursive($contact, $token);
 746
 747       // FIXME: for some pseudoconstants we get array ( 0 => id, 1 => label )
 748       if (is_array($value)) {
 749         $value = $value[1];
 750       }
 751       // Convert pseudoconstants using metadata
 752       elseif ($value && is_numeric($value)) {
 753         $allFields = CRM_Contact_BAO_Contact::exportableFields('All');
 754         if (!empty($allFields[$token]['pseudoconstant'])) {
 755           $value = CRM_Core_PseudoConstant::getLabel('CRM_Contact_BAO_Contact', $token, $value);
 756         }
 757       }
 758     }
 759
 760     if (!$html) {
 761       $value = str_replace('&amp;', '&', $value);
 762     }
 763
 764     // if null then return actual token
 765     if ($returnBlankToken && !$value) {
 766       $noReplace = TRUE;
 767     }
 768
 769     if ($noReplace) {
 770       $value = "{contact.$token}";
 771     }
 772
 773     if ($escapeSmarty
 774       && !($returnBlankToken && $noReplace)
 775     ) { // $returnBlankToken means the caller wants to do further attempts at processing unreplaced tokens -- so don't escape them yet in this case.
 776       $value = self::tokenEscapeSmarty($value);
 777     }
 778
 779     return $value;
 780   }
 781
 782   /**
 783    * Replace all the hook tokens in $str with information from
 784    * $contact.
 785    *
 786    * @param string $str
 787    *   The string with tokens to be replaced.
 788    * @param array $contact
 789    *   Associative array of contact properties (including hook token values).
 790    * @param $categories
 791    * @param bool $html
 792    *   Replace tokens with HTML or plain text.
 793    *
 794    * @param bool $escapeSmarty
 795    *
 796    * @return string
 797    *   The processed string
 798    * @static
 799    */
 800   public static function &replaceHookTokens(
 801     $str,
 802     &$contact,
 803     &$categories,
 804     $html = FALSE,
 805     $escapeSmarty = FALSE
 806   ) {
 807     foreach ($categories as $key) {
 808       $str = preg_replace_callback(
 809         self::tokenRegex($key),
 810         function ($matches) use (&$contact, $key, $html, $escapeSmarty) {
 811           return CRM_Utils_Token::getHookTokenReplacement($matches[1], $contact, $key, $html, $escapeSmarty);
 812         },
 813         $str
 814       );
 815     }
 816     return $str;
 817   }
 818
 819   /**
 820    * Parse html through Smarty resolving any smarty functions
 821    * @param string $tokenHtml
 822    * @param array $entity
 823    * @param string $entityType
 824    * @return string
 825    *   html parsed through smarty
 826    */
 827   public static function parseThroughSmarty($tokenHtml, $entity, $entityType = 'contact') {
 828     if (defined('CIVICRM_MAIL_SMARTY') && CIVICRM_MAIL_SMARTY) {
 829       $smarty = CRM_Core_Smarty::singleton();
 830       // also add the tokens to the template
 831       $smarty->assign_by_ref($entityType, $entity);
 832       $tokenHtml = $smarty->fetch("string:$tokenHtml");
 833     }
 834     return $tokenHtml;
 835   }
 836
 837   /**
 838    * @param $token
 839    * @param $contact
 840    * @param $category
 841    * @param bool $html
 842    * @param bool $escapeSmarty
 843    *
 844    * @return mixed|string
 845    */
 846   public static function getHookTokenReplacement(
 847     $token,
 848     &$contact,
 849     $category,
 850     $html = FALSE,
 851     $escapeSmarty = FALSE
 852   ) {
 853     $value = CRM_Utils_Array::value("{$category}.{$token}", $contact);
 854
 855     if ($value && !$html) {
 856       $value = str_replace('&amp;', '&', $value);
 857     }
 858
 859     if ($escapeSmarty) {
 860       $value = self::tokenEscapeSmarty($value);
 861     }
 862
 863     return $value;
 864   }
 865
 866   /**
 867    *  unescapeTokens removes any characters that caused the replacement routines to skip token replacement
 868    *  for example {{token}}  or \{token}  will result in {token} in the final email
 869    *
 870    *  this routine will remove the extra backslashes and braces
 871    *
 872    * @param $str ref to the string that will be scanned and modified
 873    * @return void
 874    *   this function works directly on the string that is passed
 875    * @access public
 876    * @static
 877    */
 878   public static function unescapeTokens(&$str) {
 879     $str = preg_replace('/\\\\|\{(\{\w+\.\w+\})\}/', '\\1', $str);
 880   }
 881
 882   /**
 883    * Replace unsubscribe tokens
 884    *
 885    * @param string $str
 886    *   The string with tokens to be replaced.
 887    * @param object $domain
 888    *   The domain BAO.
 889    * @param array $groups
 890    *   The groups (if any) being unsubscribed.
 891    * @param bool $html
 892    *   Replace tokens with html or plain text.
 893    * @param int $contact_id
 894    *   The contact ID.
 895    * @param string hash The security hash of the unsub event
 896    *
 897    * @return string
 898    *   The processed string
 899    * @static
 900    */
 901   public static function &replaceUnsubscribeTokens(
 902     $str,
 903     &$domain,
 904     &$groups,
 905     $html,
 906     $contact_id,
 907     $hash
 908   ) {
 909     if (self::token_match('unsubscribe', 'group', $str)) {
 910       if (!empty($groups)) {
 911         $config = CRM_Core_Config::singleton();
 912         $base = CRM_Utils_System::baseURL();
 913
 914         // FIXME: an ugly hack for CRM-2035, to be dropped once CRM-1799 is implemented
 915         $dao = new CRM_Contact_DAO_Group();
 916         $dao->find();
 917         while ($dao->fetch()) {
 918           if (substr($dao->visibility, 0, 6) == 'Public') {
 919             $visibleGroups[] = $dao->id;
 920           }
 921         }
 922         $value = implode(', ', $groups);
 923         self::token_replace('unsubscribe', 'group', $value, $str);
 924       }
 925     }
 926     return $str;
 927   }
 928
 929   /**
 930    * Replace resubscribe tokens
 931    *
 932    * @param string $str
 933    *   The string with tokens to be replaced.
 934    * @param object $domain
 935    *   The domain BAO.
 936    * @param array $groups
 937    *   The groups (if any) being resubscribed.
 938    * @param bool $html
 939    *   Replace tokens with html or plain text.
 940    * @param int $contact_id
 941    *   The contact ID.
 942    * @param string hash The security hash of the resub event
 943    *
 944    * @return string
 945    *   The processed string
 946    * @static
 947    */
 948   public static function &replaceResubscribeTokens(
 949     $str, &$domain, &$groups, $html,
 950     $contact_id, $hash
 951   ) {
 952     if (self::token_match('resubscribe', 'group', $str)) {
 953       if (!empty($groups)) {
 954         $value = implode(', ', $groups);
 955         self::token_replace('resubscribe', 'group', $value, $str);
 956       }
 957     }
 958     return $str;
 959   }
 960
 961   /**
 962    * Replace subscription-confirmation-request tokens
 963    *
 964    * @param string $str
 965    *   The string with tokens to be replaced.
 966    * @param string $group
 967    *   The name of the group being subscribed.
 968    * @param $url
 969    * @param bool $html
 970    *   Replace tokens with html or plain text.
 971    *
 972    * @return string
 973    *   The processed string
 974    * @static
 975    */
 976   public static function &replaceSubscribeTokens($str, $group, $url, $html) {
 977     if (self::token_match('subscribe', 'group', $str)) {
 978       self::token_replace('subscribe', 'group', $group, $str);
 979     }
 980     if (self::token_match('subscribe', 'url', $str)) {
 981       self::token_replace('subscribe', 'url', $url, $str);
 982     }
 983     return $str;
 984   }
 985
 986   /**
 987    * Replace subscription-invitation tokens
 988    *
 989    * @param string $str
 990    *   The string with tokens to be replaced.
 991    *
 992    * @return string
 993    *   The processed string
 994    * @static
 995    */
 996   public static function &replaceSubscribeInviteTokens($str) {
 997     if (preg_match('/\{action\.subscribeUrl\}/', $str)) {
 998       $url = CRM_Utils_System::url('civicrm/mailing/subscribe',
 999         'reset=1',
1000         TRUE, NULL, TRUE, TRUE
1001       );
1002       $str = preg_replace('/\{action\.subscribeUrl\}/', $url, $str);
1003     }
1004
1005     if (preg_match('/\{action\.subscribeUrl.\d+\}/', $str, $matches)) {
1006       foreach ($matches as $key => $value) {
1007         $gid = substr($value, 21, -1);
1008         $url = CRM_Utils_System::url('civicrm/mailing/subscribe',
1009           "reset=1&gid={$gid}",
1010           TRUE, NULL, TRUE, TRUE
1011         );
1012         $url = str_replace('&amp;', '&', $url);
1013         $str = preg_replace('/' . preg_quote($value) . '/', $url, $str);
1014       }
1015     }
1016
1017     if (preg_match('/\{action\.subscribe.\d+\}/', $str, $matches)) {
1018       foreach ($matches as $key => $value) {
1019         $gid = substr($value, 18, -1);
1020         $config = CRM_Core_Config::singleton();
1021         $domain = CRM_Core_BAO_MailSettings::defaultDomain();
1022         $localpart = CRM_Core_BAO_MailSettings::defaultLocalpart();
1023         // we add the 0.0000000000000000 part to make this match the other email patterns (with action, two ids and a hash)
1024         $str = preg_replace('/' . preg_quote($value) . '/', "mailto:{$localpart}s.{$gid}.0.0000000000000000@$domain", $str);
1025       }
1026     }
1027     return $str;
1028   }
1029
1030   /**
1031    * Replace welcome/confirmation tokens
1032    *
1033    * @param string $str
1034    *   The string with tokens to be replaced.
1035    * @param string $group
1036    *   The name of the group being subscribed.
1037    * @param bool $html
1038    *   Replace tokens with html or plain text.
1039    *
1040    * @return string
1041    *   The processed string
1042    * @static
1043    */
1044   public static function &replaceWelcomeTokens($str, $group, $html) {
1045     if (self::token_match('welcome', 'group', $str)) {
1046       self::token_replace('welcome', 'group', $group, $str);
1047     }
1048     return $str;
1049   }
1050
1051   /**
1052    * Find unprocessed tokens (call this last)
1053    *
1054    * @param string $str
1055    *   The string to search.
1056    *
1057    * @return array
1058    *   Array of tokens that weren't replaced
1059    * @static
1060    */
1061   public static function &unmatchedTokens(&$str) {
1062     //preg_match_all('/[^\{\\\\]\{(\w+\.\w+)\}[^\}]/', $str, $match);
1063     preg_match_all('/\{(\w+\.\w+)\}/', $str, $match);
1064     return $match[1];
1065   }
1066
1067   /**
1068    * Find and replace tokens for each component
1069    *
1070    * @param string $str
1071    *   The string to search.
1072    * @param array $contact
1073    *   Associative array of contact properties.
1074    * @param array $components
1075    *   A list of tokens that are known to exist in the email body.
1076    *
1077    * @param bool $escapeSmarty
1078    * @param bool $returnEmptyToken
1079    *
1080    * @return string
1081    *   The processed string
1082    * @static
1083    */
1084   public static function &replaceComponentTokens(&$str, $contact, $components, $escapeSmarty = FALSE, $returnEmptyToken = TRUE) {
1085     if (!is_array($components) || empty($contact)) {
1086       return $str;
1087     }
1088
1089     foreach ($components as $name => $tokens) {
1090       if (!is_array($tokens) || empty($tokens)) {
1091         continue;
1092       }
1093
1094       foreach ($tokens as $token) {
1095         if (self::token_match($name, $token, $str) && isset($contact[$name . '.' . $token])) {
1096           self::token_replace($name, $token, $contact[$name . '.' . $token], $str, $escapeSmarty);
1097         }
1098         elseif (!$returnEmptyToken) {
1099           //replacing empty token
1100           self::token_replace($name, $token, "", $str, $escapeSmarty);
1101         }
1102       }
1103     }
1104     return $str;
1105   }
1106
1107   /**
1108    * Get array of string tokens
1109    *
1110    * @param string $string
1111    *   The input string to parse for tokens.
1112    *
1113    * @return array
1114    *   array of tokens mentioned in field
1115    * @access public
1116    * @static
1117    */
1118   public static function getTokens($string) {
1119     $matches = array();
1120     $tokens = array();
1121     preg_match_all('/(?<!\{|\\\\)\{(\w+\.\w+)\}(?!\})/',
1122       $string,
1123       $matches,
1124       PREG_PATTERN_ORDER
1125     );
1126
1127     if ($matches[1]) {
1128       foreach ($matches[1] as $token) {
1129         list($type, $name) = preg_split('/\./', $token, 2);
1130         if ($name && $type) {
1131           if (!isset($tokens[$type])) {
1132             $tokens[$type] = array();
1133           }
1134           $tokens[$type][] = $name;
1135         }
1136       }
1137     }
1138     return $tokens;
1139   }
1140
1141   /**
1142    * Function to determine which values to retrieve to insert into tokens. The heavy resemblance between this function
1143    * and getTokens appears to be historical rather than intentional and should be reviewed
1144    * @param $string
1145    * @return array
1146    *   fields to pass in as return properties when populating token
1147    */
1148   public static function getReturnProperties(&$string) {
1149     $returnProperties = array();
1150     $matches = array();
1151     preg_match_all('/(?<!\{|\\\\)\{(\w+\.\w+)\}(?!\})/',
1152       $string,
1153       $matches,
1154       PREG_PATTERN_ORDER
1155     );
1156     if ($matches[1]) {
1157       foreach ($matches[1] as $token) {
1158         list($type, $name) = preg_split('/\./', $token, 2);
1159         if ($name) {
1160           $returnProperties["{$name}"] = 1;
1161         }
1162       }
1163     }
1164
1165     return $returnProperties;
1166   }
1167
1168   /**
1169    * Gives required details of contacts in an indexed array format so we
1170    * can iterate in a nice loop and do token evaluation
1171    *
1172    * @param $contactIDs
1173    * @param array $returnProperties
1174    *   Of required properties.
1175    * @param bool $skipOnHoldDon 't return on_hold contact info also.
1176    *   Don't return on_hold contact info also.
1177    * @param bool $skipDeceasedDon 't return deceased contact info.
1178    *   Don't return deceased contact info.
1179    * @param array $extraParams
1180    *   Extra params.
1181    * @param array $tokens
1182    *   The list of tokens we've extracted from the content.
1183    * @param null $className
1184    * @param int $jobID
1185    *   The mailing list jobID - this is a legacy param.
1186    *
1187    * @return array
1188    * @static
1189    */
1190   static function getTokenDetails(
1191     $contactIDs,
1192     $returnProperties = NULL,
1193     $skipOnHold = TRUE,
1194     $skipDeceased = TRUE,
1195     $extraParams = NULL,
1196     $tokens = array(),
1197     $className = NULL,
1198     $jobID = NULL
1199   ) {
1200     if (empty($contactIDs)) {
1201       // putting a fatal here so we can track if/when this happens
1202       CRM_Core_Error::fatal();
1203     }
1204
1205     $params = array();
1206     foreach ($contactIDs as $key => $contactID) {
1207       $params[] = array(
1208         CRM_Core_Form::CB_PREFIX . $contactID,
1209         '=',
1210         1,
1211         0,
1212         0,
1213       );
1214     }
1215
1216     // fix for CRM-2613
1217     if ($skipDeceased) {
1218       $params[] = array('is_deceased', '=', 0, 0, 0);
1219     }
1220
1221     //fix for CRM-3798
1222     if ($skipOnHold) {
1223       $params[] = array('on_hold', '=', 0, 0, 0);
1224     }
1225
1226     if ($extraParams) {
1227       $params = array_merge($params, $extraParams);
1228     }
1229
1230     // if return properties are not passed then get all return properties
1231     if (empty($returnProperties)) {
1232       $fields = array_merge(array_keys(CRM_Contact_BAO_Contact::exportableFields()),
1233         array('display_name', 'checksum', 'contact_id')
1234       );
1235       foreach ($fields as $key => $val) {
1236         $returnProperties[$val] = 1;
1237       }
1238     }
1239
1240     $custom = array();
1241     foreach ($returnProperties as $name => $dontCare) {
1242       $cfID = CRM_Core_BAO_CustomField::getKeyID($name);
1243       if ($cfID) {
1244         $custom[] = $cfID;
1245       }
1246     }
1247
1248     //get the total number of contacts to fetch from database.
1249     $numberofContacts = count($contactIDs);
1250     $query = new CRM_Contact_BAO_Query($params, $returnProperties);
1251
1252     $details = $query->apiQuery($params, $returnProperties, NULL, NULL, 0, $numberofContacts);
1253
1254     $contactDetails = &$details[0];
1255
1256     foreach ($contactIDs as $key => $contactID) {
1257       if (array_key_exists($contactID, $contactDetails)) {
1258         if (CRM_Utils_Array::value('preferred_communication_method', $returnProperties) == 1
1259           && array_key_exists('preferred_communication_method', $contactDetails[$contactID])
1260         ) {
1261           $pcm = CRM_Core_PseudoConstant::get('CRM_Contact_DAO_Contact', 'preferred_communication_method');
1262
1263           // communication Prefferance
1264           $contactPcm = explode(CRM_Core_DAO::VALUE_SEPARATOR,
1265             $contactDetails[$contactID]['preferred_communication_method']
1266           );
1267           $result = array();
1268           foreach ($contactPcm as $key => $val) {
1269             if ($val) {
1270               $result[$val] = $pcm[$val];
1271             }
1272           }
1273           $contactDetails[$contactID]['preferred_communication_method'] = implode(', ', $result);
1274         }
1275
1276         foreach ($custom as $cfID) {
1277           if (isset($contactDetails[$contactID]["custom_{$cfID}"])) {
1278             $contactDetails[$contactID]["custom_{$cfID}"] = CRM_Core_BAO_CustomField::getDisplayValue($contactDetails[$contactID]["custom_{$cfID}"],
1279               $cfID, $details[1]
1280             );
1281           }
1282         }
1283
1284         //special case for greeting replacement
1285         foreach (array(
1286                    'email_greeting',
1287                    'postal_greeting',
1288                    'addressee'
1289                  ) as $val) {
1290           if (!empty($contactDetails[$contactID][$val])) {
1291             $contactDetails[$contactID][$val] = $contactDetails[$contactID]["{$val}_display"];
1292           }
1293         }
1294       }
1295     }
1296
1297     // also call a hook and get token details
1298     CRM_Utils_Hook::tokenValues($details[0],
1299       $contactIDs,
1300       $jobID,
1301       $tokens,
1302       $className
1303     );
1304     return $details;
1305   }
1306
1307   /**
1308    * Call hooks on tokens for anonymous users - contact id is set to 0 - this allows non-contact
1309    * specific tokens to be rendered
1310    *
1311    * @param array $contactIDs
1312    *   This should always be array(0) or its not anonymous - left to keep signature same.
1313    * as main fn
1314    * @param string $returnProperties
1315    * @param bool $skipOnHold
1316    * @param bool $skipDeceased
1317    * @param string $extraParams
1318    * @param array $tokens
1319    * @param string $className
1320    *   Sent as context to the hook.
1321    * @param string $jobID
1322    * @return array
1323    *   contactDetails with hooks swapped out
1324    */
1325   public function getAnonymousTokenDetails($contactIDs = array(
1326       0
1327     ),
1328                                            $returnProperties = NULL,
1329                                            $skipOnHold = TRUE,
1330                                            $skipDeceased = TRUE,
1331                                            $extraParams = NULL,
1332                                            $tokens = array(),
1333                                            $className = NULL,
1334                                            $jobID = NULL) {
1335     $details = array(0 => array());
1336     // also call a hook and get token details
1337     CRM_Utils_Hook::tokenValues($details[0],
1338       $contactIDs,
1339       $jobID,
1340       $tokens,
1341       $className
1342     );
1343     return $details;
1344   }
1345
1346   /**
1347    * Gives required details of contribuion in an indexed array format so we
1348    * can iterate in a nice loop and do token evaluation
1349    *
1350    * @param array $contributionIDs
1351    * @param array $returnProperties
1352    *   Of required properties.
1353    * @param array $extraParams
1354    *   Extra params.
1355    * @param array $tokens
1356    *   The list of tokens we've extracted from the content.
1357    * @param string $className
1358    *
1359    * @return array
1360    * @static
1361    */
1362   static function getContributionTokenDetails(
1363     $contributionIDs,
1364     $returnProperties = NULL,
1365     $extraParams = NULL,
1366     $tokens = array(),
1367     $className = NULL
1368   ) {
1369     //@todo - this function basically replications calling civicrm_api3('contribution', 'get', array('id' => array('IN' => array())
1370     if (empty($contributionIDs)) {
1371       // putting a fatal here so we can track if/when this happens
1372       CRM_Core_Error::fatal();
1373     }
1374
1375     $details = array();
1376
1377     // no apiQuery helper yet, so do a loop and find contribution by id
1378     foreach ($contributionIDs as $contributionID) {
1379
1380       $dao = new CRM_Contribute_DAO_Contribution();
1381       $dao->id = $contributionID;
1382
1383       if ($dao->find(TRUE)) {
1384
1385         $details[$dao->id] = array();
1386         CRM_Core_DAO::storeValues($dao, $details[$dao->id]);
1387
1388         // do the necessary transformation
1389         if (!empty($details[$dao->id]['payment_instrument_id'])) {
1390           $piId = $details[$dao->id]['payment_instrument_id'];
1391           $pis = CRM_Contribute_PseudoConstant::paymentInstrument();
1392           $details[$dao->id]['payment_instrument'] = $pis[$piId];
1393         }
1394         if (!empty($details[$dao->id]['campaign_id'])) {
1395           $campaignId = $details[$dao->id]['campaign_id'];
1396           $campaigns = CRM_Campaign_BAO_Campaign::getCampaigns($campaignId);
1397           $details[$dao->id]['campaign'] = $campaigns[$campaignId];
1398         }
1399
1400         if (!empty($details[$dao->id]['financial_type_id'])) {
1401           $financialtypeId = $details[$dao->id]['financial_type_id'];
1402           $ftis = CRM_Contribute_PseudoConstant::financialType();
1403           $details[$dao->id]['financial_type'] = $ftis[$financialtypeId];
1404         }
1405
1406         // TODO: call a hook to get token contribution details
1407       }
1408     }
1409
1410     return $details;
1411   }
1412
1413   /**
1414    * Get Membership Token Details
1415    * @param array $membershipIDs
1416    *   Array of membership IDS.
1417    */
1418   public static function getMembershipTokenDetails($membershipIDs) {
1419     $memberships = civicrm_api3('membership', 'get', array(
1420         'options' => array('limit' => 200000),
1421         'membership_id' => array('IN' => (array) $membershipIDs)
1422       ));
1423     return $memberships['values'];
1424   }
1425
1426   /**
1427    * Replace greeting tokens exists in message/subject
1428    */
1429   public static function replaceGreetingTokens(&$tokenString, $contactDetails = NULL, $contactId = NULL, $className = NULL, $escapeSmarty = FALSE) {
1430
1431     if (!$contactDetails && !$contactId) {
1432       return;
1433     }
1434
1435     // check if there are any tokens
1436     $greetingTokens = self::getTokens($tokenString);
1437
1438     if (!empty($greetingTokens)) {
1439       // first use the existing contact object for token replacement
1440       if (!empty($contactDetails)) {
1441         $tokenString = CRM_Utils_Token::replaceContactTokens($tokenString, $contactDetails, TRUE, $greetingTokens, TRUE, $escapeSmarty);
1442       }
1443
1444       // check if there are any unevaluated tokens
1445       $greetingTokens = self::getTokens($tokenString);
1446
1447       // $greetingTokens not empty, means there are few tokens which are not evaluated, like custom data etc
1448       // so retrieve it from database
1449       if (!empty($greetingTokens) && array_key_exists('contact', $greetingTokens)) {
1450         $greetingsReturnProperties = array_flip(CRM_Utils_Array::value('contact', $greetingTokens));
1451         $greetingsReturnProperties = array_fill_keys(array_keys($greetingsReturnProperties), 1);
1452         $contactParams = array('contact_id' => $contactId);
1453
1454         $greetingDetails = self::getTokenDetails($contactParams,
1455           $greetingsReturnProperties,
1456           FALSE, FALSE, NULL,
1457           $greetingTokens,
1458           $className
1459         );
1460
1461         // again replace tokens
1462         $tokenString = CRM_Utils_Token::replaceContactTokens($tokenString,
1463           $greetingDetails,
1464           TRUE,
1465           $greetingTokens,
1466           FALSE,
1467           $escapeSmarty
1468         );
1469       }
1470
1471       // check if there are still any unevaluated tokens
1472       $remainingTokens = self::getTokens($tokenString);
1473
1474       // contact related $greetingTokens not empty, there are customized or hook tokens to replace
1475       if (!empty($remainingTokens['contact'])) {
1476         // Fill the return properties array
1477         $greetingTokens = $remainingTokens['contact'];
1478         reset($greetingTokens);
1479         $greetingsReturnProperties = array();
1480         while (list($key) = each($greetingTokens)) {
1481           $props = array_flip(CRM_Utils_Array::value($key, $greetingTokens));
1482           $props = array_fill_keys(array_keys($props), 1);
1483           $greetingsReturnProperties = $greetingsReturnProperties + $props;
1484         }
1485         $contactParams = array('contact_id' => $contactId);
1486         $greetingDetails = self::getTokenDetails($contactParams,
1487           $greetingsReturnProperties,
1488           FALSE, FALSE, NULL,
1489           $greetingTokens,
1490           $className
1491         );
1492         // Prepare variables for calling replaceHookTokens
1493         $categories = array_keys($greetingTokens);
1494         list($contact) = $greetingDetails;
1495         // Replace tokens defined in Hooks.
1496         $tokenString = CRM_Utils_Token::replaceHookTokens($tokenString, $contact[$contactId], $categories);
1497       }
1498     }
1499   }
1500
1501   /**
1502    * @param $tokens
1503    *
1504    * @return array
1505    */
1506   public static function flattenTokens(&$tokens) {
1507     $flattenTokens = array();
1508
1509     foreach (array(
1510                'html',
1511                'text',
1512                'subject'
1513              ) as $prop) {
1514       if (!isset($tokens[$prop])) {
1515         continue;
1516       }
1517       foreach ($tokens[$prop] as $type => $names) {
1518         if (!isset($flattenTokens[$type])) {
1519           $flattenTokens[$type] = array();
1520         }
1521         foreach ($names as $name) {
1522           $flattenTokens[$type][$name] = 1;
1523         }
1524       }
1525     }
1526
1527     return $flattenTokens;
1528   }
1529
1530   /**
1531    * Replace all user tokens in $str
1532    *
1533    * @param string $str
1534    *   The string with tokens to be replaced.
1535    *
1536    * @param null $knownTokens
1537    * @param bool $escapeSmarty
1538    *
1539    * @return string
1540    *   The processed string
1541    * @static
1542    */
1543   public static function &replaceUserTokens($str, $knownTokens = NULL, $escapeSmarty = FALSE) {
1544     $key = 'user';
1545     if (!$knownTokens ||
1546       !isset($knownTokens[$key])
1547     ) {
1548       return $str;
1549     }
1550
1551     $str = preg_replace_callback(
1552       self::tokenRegex($key),
1553       function ($matches) use ($escapeSmarty) {
1554         return CRM_Utils_Token::getUserTokenReplacement($matches[1], $escapeSmarty);
1555       },
1556       $str
1557     );
1558     return $str;
1559   }
1560
1561   /**
1562    * @param $token
1563    * @param bool $escapeSmarty
1564    *
1565    * @return string
1566    */
1567   public static function getUserTokenReplacement($token, $escapeSmarty = FALSE) {
1568     $value = '';
1569
1570     list($objectName, $objectValue) = explode('-', $token, 2);
1571
1572     switch ($objectName) {
1573       case 'permission':
1574         $value = CRM_Core_Permission::permissionEmails($objectValue);
1575         break;
1576
1577       case 'role':
1578         $value = CRM_Core_Permission::roleEmails($objectValue);
1579         break;
1580     }
1581
1582     if ($escapeSmarty) {
1583       $value = self::tokenEscapeSmarty($value);
1584     }
1585
1586     return $value;
1587   }
1588
1589   /**
1590    */
1591   protected static function _buildContributionTokens() {
1592     $key = 'contribution';
1593     if (self::$_tokens[$key] == NULL) {
1594       self::$_tokens[$key] = array_keys(array_merge(CRM_Contribute_BAO_Contribution::exportableFields('All'),
1595         array('campaign', 'financial_type')
1596       ));
1597     }
1598   }
1599
1600   /**
1601    * Store membership tokens on the static _tokens array
1602    */
1603   protected static function _buildMembershipTokens() {
1604     $key = 'membership';
1605     if (!isset(self::$_tokens[$key]) || self::$_tokens[$key] == NULL) {
1606       $membershipTokens = array();
1607       $tokens = CRM_Core_SelectValues::membershipTokens();
1608       foreach ($tokens as $token => $dontCare) {
1609         $membershipTokens[] = substr($token, (strpos($token, '.') + 1), -1);
1610       }
1611       self::$_tokens[$key] = $membershipTokens;
1612     }
1613   }
1614
1615   /**
1616    * Replace tokens for an entity
1617    * @param string $entity
1618    * @param array $entityArray
1619    *   (e.g. in format from api).
1620    * @param string $str
1621    *   String to replace in.
1622    * @param array $knownTokens
1623    *   Array of tokens present.
1624    * @param bool $escapeSmarty
1625    * @return string
1626    *   string with replacements made
1627    */
1628   public static function replaceEntityTokens($entity, $entityArray, $str, $knownTokens = array(), $escapeSmarty = FALSE) {
1629     if (!$knownTokens || empty($knownTokens[$entity])) {
1630       return $str;
1631     }
1632
1633     $fn = 'get' . ucfirst($entity) . 'tokenReplacement';
1634     //since we already know the tokens lets just use them & do str_replace which is faster & simpler than preg_replace
1635     foreach ($knownTokens[$entity] as $token) {
1636       $replaceMent = CRM_Utils_Token::$fn($token, $entityArray, $escapeSmarty);
1637       $str = str_replace('{' . $entity . '.' . $token . '}', $replaceMent, $str);
1638     }
1639     $str = preg_replace('/\\\\|\{(\s*)?\}/', ' ', $str);
1640     return $str;
1641   }
1642
1643   /**
1644    * Replace Contribution tokens in html
1645    *
1646    * @param string $str
1647    * @param array $contribution
1648    * @param bool|string $html
1649    * @param string $knownTokens
1650    * @param bool|string $escapeSmarty
1651    *
1652    * @return mixed
1653    */
1654   public static function replaceContributionTokens($str, &$contribution, $html = FALSE, $knownTokens = NULL, $escapeSmarty = FALSE) {
1655     $key = 'contribution';
1656     if (!$knownTokens || !CRM_Utils_Array::value($key, $knownTokens)) {
1657       return $str; //early return
1658     }
1659     self::_buildContributionTokens();
1660
1661     // here we intersect with the list of pre-configured valid tokens
1662     // so that we remove anything we do not recognize
1663     // I hope to move this step out of here soon and
1664     // then we will just iterate on a list of tokens that are passed to us
1665
1666     $str = preg_replace_callback(
1667       self::tokenRegex($key),
1668       function ($matches) use (&$contribution, $html, $escapeSmarty) {
1669         return CRM_Utils_Token::getContributionTokenReplacement($matches[1], $contribution, $html, $escapeSmarty);
1670       },
1671       $str
1672     );
1673
1674     $str = preg_replace('/\\\\|\{(\s*)?\}/', ' ', $str);
1675     return $str;
1676   }
1677
1678   /**
1679    * We have a situation where we are rendering more than one token in each field because we are combining
1680    * tokens from more than one contribution when pdf thank you letters are grouped (CRM-14367)
1681    *
1682    * The replaceContributionToken doesn't handle receive_date correctly in this scenario because of the formatting
1683    * it applies (other tokens are OK including date fields)
1684    *
1685    * So we sort this out & then call the main function. Note that we are not escaping smarty on this fields like the main function
1686    * does - but the fields is already being formatted through a date function
1687    *
1688    * @param string $separator
1689    * @param string $str
1690    * @param array $contribution
1691    * @param bool|string $html
1692    * @param string $knownTokens
1693    * @param bool|string $escapeSmarty
1694    *
1695    * @return \Ambigous|mixed|string|\unknown
1696    */
1697   public static function replaceMultipleContributionTokens($separator, $str, &$contribution, $html = FALSE, $knownTokens = NULL, $escapeSmarty = FALSE) {
1698     if (empty($knownTokens['contribution'])) {
1699       return $str;
1700     }
1701
1702     if (in_array('receive_date', $knownTokens['contribution'])) {
1703       $formattedDates = array();
1704       $dates = explode($separator, $contribution['receive_date']);
1705       foreach ($dates as $date) {
1706         $formattedDates[] = CRM_Utils_Date::customFormat($date, NULL, array('j', 'm', 'Y'));
1707       }
1708       $str = str_replace("{contribution.receive_date}", implode($separator, $formattedDates), $str);
1709       unset($knownTokens['contribution']['receive_date']);
1710     }
1711     return self::replaceContributionTokens($str, $contribution, $html, $knownTokens, $escapeSmarty);
1712   }
1713
1714   /**
1715    * Get replacement strings for any membership tokens (only a small number of tokens are implemnted in the first instance
1716    * - this is used by the pdfLetter task from membership search
1717    * @param string $token
1718    * @param array $membership
1719    *   An api result array for a single membership.
1720    * @param bool $escapeSmarty
1721    * @return string
1722    *   token replacement
1723    */
1724   public static function getMembershipTokenReplacement($token, $membership, $escapeSmarty = FALSE) {
1725     $entity = 'membership';
1726     self::_buildMembershipTokens();
1727     switch ($token) {
1728       case 'type':
1729         $value = $membership['membership_name'];
1730         break;
1731
1732       case 'status':
1733         $statuses = CRM_Member_BAO_Membership::buildOptions('status_id');
1734         $value = $statuses[$membership['status_id']];
1735         break;
1736
1737       case 'fee':
1738         try {
1739           $value = civicrm_api3('membership_type', 'getvalue', array(
1740               'id' => $membership['membership_type_id'],
1741               'return' => 'minimum_fee'
1742             ));
1743         }
1744         catch (CiviCRM_API3_Exception $e) {
1745           // we can anticipate we will get an error if the minimum fee is set to 'NULL' because of the way the
1746           // api handles NULL (4.4)
1747           $value = 0;
1748         }
1749         break;
1750
1751       default:
1752         if (in_array($token, self::$_tokens[$entity])) {
1753           $value = $membership[$token];
1754         }
1755         else {
1756           //ie unchanged
1757           $value = "{$entity}.{$token}";
1758         }
1759         break;
1760     }
1761
1762     if ($escapeSmarty) {
1763       $value = self::tokenEscapeSmarty($value);
1764     }
1765     return $value;
1766   }
1767
1768   /**
1769    * @param $token
1770    * @param $contribution
1771    * @param bool $html
1772    * @param bool $escapeSmarty
1773    *
1774    * @return mixed|string
1775    */
1776   public static function getContributionTokenReplacement($token, &$contribution, $html = FALSE, $escapeSmarty = FALSE) {
1777     self::_buildContributionTokens();
1778
1779     switch ($token) {
1780       case 'total_amount':
1781       case 'net_amount':
1782       case 'fee_amount':
1783       case 'non_deductible_amount':
1784         $value = CRM_Utils_Money::format(CRM_Utils_Array::retrieveValueRecursive($contribution, $token));
1785         break;
1786
1787       case 'receive_date':
1788         $value = CRM_Utils_Array::retrieveValueRecursive($contribution, $token);
1789         $value = CRM_Utils_Date::customFormat($value, NULL, array('j', 'm', 'Y'));
1790         break;
1791
1792       default:
1793         if (!in_array($token, self::$_tokens['contribution'])) {
1794           $value = "{contribution.$token}";
1795         }
1796         else {
1797           $value = CRM_Utils_Array::retrieveValueRecursive($contribution, $token);
1798         }
1799         break;
1800     }
1801
1802     if ($escapeSmarty) {
1803       $value = self::tokenEscapeSmarty($value);
1804     }
1805     return $value;
1806   }
1807
1808   /**
1809    * @return array
1810    *   legacy_token => new_token
1811    */
1812   public static function legacyContactTokens() {
1813     return array(
1814       'individual_prefix' => 'prefix_id',
1815       'individual_suffix' => 'suffix_id',
1816       'gender' => 'gender_id',
1817       'communication_style' => 'communication_style_id',
1818     );
1819   }
1820
1821   /**
1822    * Formats a token list for the select2 widget
1823    * @param $tokens
1824    * @return array
1825    */
1826   public static function formatTokensForDisplay($tokens) {
1827     $sorted = $output = array();
1828
1829     // Sort in ascending order by ignoring word case
1830     natcasesort($tokens);
1831
1832     // Attempt to place tokens into optgroups
1833     // TODO: These groupings could be better and less hackish. Getting them pre-grouped from upstream would be nice.
1834     foreach ($tokens as $k => $v) {
1835       // Check to see if this token is already in a group e.g. for custom fields
1836       $split = explode(' :: ', $v);
1837       if (!empty($split[1])) {
1838         $sorted[$split[1]][] = array('id' => $k, 'text' => $split[0]);
1839       }
1840       // Group by entity
1841       else {
1842         $split = explode('.', trim($k, '{}'));
1843         if (isset($split[1])) {
1844           $entity = array_key_exists($split[1], CRM_Core_DAO_Address::export()) ? 'Address' : ucfirst($split[0]);
1845         }
1846         else {
1847           $entity = 'Contact';
1848         }
1849         $sorted[ts($entity)][] = array('id' => $k, 'text' => $v);
1850       }
1851     }
1852
1853     ksort($sorted);
1854     foreach ($sorted as $k => $v) {
1855       $output[] = array('text' => $k, 'children' => $v);
1856     }
1857
1858     return $output;
1859   }
1860 }