CRM/Utils/Token.php

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