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