CRM/Utils/Token.php

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