CRM_Utils_Token

class CRM_Utils_Token

Class to abstract token replacement.

Properties

static $_requiredTokens
static $_tokens

Methods

static array
getRequiredTokens() deprecated

No description

static bool|array
requiredTokens(string $str)

Check a string (mailing body) for required tokens.

static bool
token_match(string $type, string $var, string $str)

Wrapper for token matching.

static string
token_replace(string $type, string $var, string $value, string $str, bool $escapeSmarty = FALSE)

Wrapper for token replacing.

static string
tokenEscapeSmarty(string $string)

Escape the string so a malicious user cannot inject smarty code into the template.

static string
replaceDomainTokens(string $str, object $domain, bool $html = FALSE, null $knownTokens = NULL, bool $escapeSmarty = FALSE)

Replace all the domain-level tokens in $str

static mixed|null|string
getDomainTokenReplacement($token, $domain, bool $html = FALSE, bool $escapeSmarty = FALSE)

No description

static string
replaceOrgTokens(string $str, object $org, bool $html = FALSE, bool $escapeSmarty = FALSE) deprecated

Replace all the org-level tokens in $str

static string
replaceMailingTokens(string $str, object $mailing, bool $html = FALSE, null $knownTokens = NULL, bool $escapeSmarty = FALSE)

Replace all mailing tokens in $str

static string
getMailingTokenReplacement($token, $mailing, bool $escapeSmarty = FALSE)

No description

static string
replaceActionTokens(string $str, array $addresses, array $urls, bool $html = FALSE, array $knownTokens = NULL, bool $escapeSmarty = FALSE)

Replace all action tokens in $str

static mixed|string
getActionTokenReplacement($token, $addresses, $urls, bool $html = FALSE, bool $escapeSmarty = FALSE)

No description

static string
replaceContactTokens(string $str, array $contact, bool $html = FALSE, array $knownTokens = NULL, bool $returnBlankToken = FALSE, bool $escapeSmarty = FALSE)

Replace all the contact-level tokens in $str with information from $contact.

static bool|mixed|null|string
getContactTokenReplacement($token, $contact, bool $html = FALSE, bool $returnBlankToken = FALSE, bool $escapeSmarty = FALSE)

No description

static string
replaceHookTokens(string $str, array $contact, $categories, bool $html = FALSE, bool $escapeSmarty = FALSE)

Replace all the hook tokens in $str with information from $contact.

static string
parseThroughSmarty(string $tokenHtml, array $entity, string $entityType = 'contact')

Parse html through Smarty resolving any smarty functions.

static mixed|string
getHookTokenReplacement($token, $contact, $category, bool $html = FALSE, bool $escapeSmarty = FALSE)

No description

static 
unescapeTokens($str)

unescapeTokens removes any characters that caused the replacement routines to skip token replacement for example {{token}} or {token} will result in {token} in the final email

static string
replaceUnsubscribeTokens(string $str, object $domain, array $groups, bool $html, int $contact_id, string $hash)

Replace unsubscribe tokens.

static string
replaceResubscribeTokens(string $str, object $domain, array $groups, bool $html, int $contact_id, string $hash)

Replace resubscribe tokens.

static string
replaceSubscribeTokens(string $str, string $group, $url, bool $html)

Replace subscription-confirmation-request tokens

static string
replaceSubscribeInviteTokens(string $str)

Replace subscription-invitation tokens

static string
replaceWelcomeTokens(string $str, string $group, bool $html)

Replace welcome/confirmation tokens

static array
unmatchedTokens(string $str)

Find unprocessed tokens (call this last)

static string
replaceComponentTokens(string $str, array $contact, array $components, bool $escapeSmarty = FALSE, bool $returnEmptyToken = TRUE)

Find and replace tokens for each component.

static array
getTokens(string $string)

Get array of string tokens.

static array
getReturnProperties($string)

Function to determine which values to retrieve to insert into tokens. The heavy resemblance between this function and getTokens appears to be historical rather than intentional and should be reviewed

static array
getTokenDetails(array $contactIDs, array $returnProperties = NULL, bool $skipOnHold = TRUE, bool $skipDeceased = TRUE, array $extraParams = NULL, array $tokens = [], null $className = NULL, int $jobID = NULL)

Gives required details of contacts in an indexed array format so we can iterate in a nice loop and do token evaluation

static array
getAnonymousTokenDetails(array $contactIDs = [0], string $returnProperties = NULL, bool $skipOnHold = TRUE, bool $skipDeceased = TRUE, string $extraParams = NULL, array $tokens = [], string $className = NULL, string $jobID = NULL)

Call hooks on tokens for anonymous users - contact id is set to 0 - this allows non-contact specific tokens to be rendered

static 
getMembershipTokenDetails(array $membershipIDs)

Get Membership Token Details.

static 
replaceGreetingTokens(string $tokenString, array $contactDetails = NULL, int $contactId = NULL, string $className = NULL, bool $escapeSmarty = FALSE)

Replace existing greeting tokens in message/subject.

static array
flattenTokens($tokens)

No description

static string
replaceUserTokens(string $str, null $knownTokens = NULL, bool $escapeSmarty = FALSE)

Replace all user tokens in $str

static string
getUserTokenReplacement($token, bool $escapeSmarty = FALSE)

No description

static 
_buildContributionTokens()

No description

static 
_buildMembershipTokens()

Store membership tokens on the static _tokens array.

static string
replaceEntityTokens(string $entity, array $entityArray, string $str, array $knownTokens = [], bool $escapeSmarty = FALSE)

Replace tokens for an entity.

static string
replaceCaseTokens(int $caseId, int $str, array $knownTokens = [], bool $escapeSmarty = FALSE)

No description

static string
getApiTokenReplacement(string $entity, string $token, array $entityArray)

Generic function for formatting token replacement for an api field

static mixed
replaceContributionTokens(string $str, array $contribution, bool|string $html = FALSE, string $knownTokens = NULL, bool|string $escapeSmarty = FALSE)

Replace Contribution tokens in html.

static string
replaceMultipleContributionTokens(string $separator, string $str, array $contribution, bool|string $html = FALSE, string $knownTokens = NULL, bool|string $escapeSmarty = FALSE)

We have a situation where we are rendering more than one token in each field because we are combining tokens from more than one contribution when pdf thank you letters are grouped (CRM-14367)

static string
getMembershipTokenReplacement(string $entity, string $token, array $membership)

Get replacement strings for any membership tokens (only a small number of tokens are implemnted in the first instance - this is used by the pdfLetter task from membership search

static mixed|string
getContributionTokenReplacement($token, $contribution, bool $html = FALSE, bool $escapeSmarty = FALSE)

No description

static array
legacyContactTokens()

No description

static array
getCustomFieldTokens(string $entity, bool $usedForTokenWidget = FALSE)

Get all custom field tokens of $entity

static array
formatTokensForDisplay($tokens)

Formats a token list for the select2 widget

Details

at line 96
static array getRequiredTokens() deprecated

deprecated This is used by CiviMail but will be made redundant by FlexMailer.

Return Value

array

at line 121
static bool|array requiredTokens(string $str)

Check a string (mailing body) for required tokens.

Parameters

string $str The message.

Return Value

bool|array true if all required tokens are found, else an array of the missing tokens

at line 166
static bool token_match(string $type, string $var, string $str)

Wrapper for token matching.

Parameters

string $type The token type (domain,mailing,contact,action).
string $var The token variable.
string $str The string to search.

Return Value

bool Was there a match

at line 187
static string token_replace(string $type, string $var, string $value, string $str, bool $escapeSmarty = FALSE)

Wrapper for token replacing.

Parameters

string $type The token type.
string $var The token variable.
string $value The value to substitute for the token.
string $str (reference) The string to replace in
bool $escapeSmarty

Return Value

string The processed string

at line 221
static string tokenEscapeSmarty(string $string)

Escape the string so a malicious user cannot inject smarty code into the template.

Parameters

string $string A string that needs to be escaped from smarty parsing.

Return Value

string the escaped string

at line 242
static string replaceDomainTokens(string $str, object $domain, bool $html = FALSE, null $knownTokens = NULL, bool $escapeSmarty = FALSE)

Replace all the domain-level tokens in $str

Parameters

string $str The string with tokens to be replaced.
object $domain The domain BAO.
bool $html Replace tokens with HTML or plain text.
null $knownTokens
bool $escapeSmarty

Return Value

string The processed string

at line 274
static mixed|null|string getDomainTokenReplacement($token, $domain, bool $html = FALSE, bool $escapeSmarty = FALSE)

Parameters

$token
$domain
bool $html
bool $escapeSmarty

Return Value

mixed|null|string

at line 348
static string replaceOrgTokens(string $str, object $org, bool $html = FALSE, bool $escapeSmarty = FALSE) deprecated

deprecated

Replace all the org-level tokens in $str

Parameters

string $str The string with tokens to be replaced.
object $org Associative array of org properties.
bool $html Replace tokens with HTML or plain text.
bool $escapeSmarty

Return Value

string The processed string

at line 431
static string replaceMailingTokens(string $str, object $mailing, bool $html = FALSE, null $knownTokens = NULL, bool $escapeSmarty = FALSE)

Replace all mailing tokens in $str

Parameters

string $str The string with tokens to be replaced.
object $mailing The mailing BAO, or null for validation.
bool $html Replace tokens with HTML or plain text.
null $knownTokens
bool $escapeSmarty

Return Value

string The processed string

at line 460
static string getMailingTokenReplacement($token, $mailing, bool $escapeSmarty = FALSE)

Parameters

$token
$mailing
bool $escapeSmarty

Return Value

string

at line 561
static string replaceActionTokens(string $str, array $addresses, array $urls, bool $html = FALSE, array $knownTokens = NULL, bool $escapeSmarty = FALSE)

Replace all action tokens in $str

Parameters

string $str The string with tokens to be replaced.
array $addresses Assoc. array of VERP event addresses.
array $urls Assoc. array of action URLs.
bool $html Replace tokens with HTML or plain text.
array $knownTokens A list of tokens that are known to exist in the email body.
bool $escapeSmarty

Return Value

string The processed string

at line 597
static mixed|string getActionTokenReplacement($token, $addresses, $urls, bool $html = FALSE, bool $escapeSmarty = FALSE)

Parameters

$token
$addresses
$urls
bool $html
bool $escapeSmarty

Return Value

mixed|string

at line 654
static string replaceContactTokens(string $str, array $contact, bool $html = FALSE, array $knownTokens = NULL, bool $returnBlankToken = FALSE, bool $escapeSmarty = FALSE)

Replace all the contact-level tokens in $str with information from $contact.

Parameters

string $str The string with tokens to be replaced.
array $contact Associative array of contact properties.
bool $html Replace tokens with HTML or plain text.
array $knownTokens A list of tokens that are known to exist in the email body.
bool $returnBlankToken Return unevaluated token if value is null.
bool $escapeSmarty

Return Value

string The processed string

at line 699
static bool|mixed|null|string getContactTokenReplacement($token, $contact, bool $html = FALSE, bool $returnBlankToken = FALSE, bool $escapeSmarty = FALSE)

Parameters

$token
$contact
bool $html
bool $returnBlankToken
bool $escapeSmarty

Return Value

bool|mixed|null|string

at line 801
static string replaceHookTokens(string $str, array $contact, $categories, bool $html = FALSE, bool $escapeSmarty = FALSE)

Replace all the hook tokens in $str with information from $contact.

Parameters

string $str The string with tokens to be replaced.
array $contact Associative array of contact properties (including hook token values).
$categories
bool $html Replace tokens with HTML or plain text.
bool $escapeSmarty

Return Value

string The processed string

at line 828
static string parseThroughSmarty(string $tokenHtml, array $entity, string $entityType = 'contact')

Parse html through Smarty resolving any smarty functions.

Parameters

string $tokenHtml
array $entity
string $entityType

Return Value

string html parsed through smarty

at line 847
static mixed|string getHookTokenReplacement($token, $contact, $category, bool $html = FALSE, bool $escapeSmarty = FALSE)

Parameters

$token
$contact
$category
bool $html
bool $escapeSmarty

Return Value

mixed|string

at line 875
static unescapeTokens($str)

unescapeTokens removes any characters that caused the replacement routines to skip token replacement for example {{token}} or {token} will result in {token} in the final email

this routine will remove the extra backslashes and braces

Parameters

$str ref to the string that will be scanned and modified

at line 897
static string replaceUnsubscribeTokens(string $str, object $domain, array $groups, bool $html, int $contact_id, string $hash)

Replace unsubscribe tokens.

Parameters

string $str The string with tokens to be replaced.
object $domain The domain BAO.
array $groups The groups (if any) being unsubscribed.
bool $html Replace tokens with html or plain text.
int $contact_id The contact ID.
string $hash The security hash of the unsub event

Return Value

string The processed string

at line 943
static string replaceResubscribeTokens(string $str, object $domain, array $groups, bool $html, int $contact_id, string $hash)

Replace resubscribe tokens.

Parameters

string $str The string with tokens to be replaced.
object $domain The domain BAO.
array $groups The groups (if any) being resubscribed.
bool $html Replace tokens with html or plain text.
int $contact_id The contact ID.
string $hash The security hash of the resub event

Return Value

string The processed string

at line 970
static string replaceSubscribeTokens(string $str, string $group, $url, bool $html)

Replace subscription-confirmation-request tokens

Parameters

string $str The string with tokens to be replaced.
string $group The name of the group being subscribed.
$url
bool $html Replace tokens with html or plain text.

Return Value

string The processed string

at line 989
static string replaceSubscribeInviteTokens(string $str)

Replace subscription-invitation tokens

Parameters

string $str The string with tokens to be replaced.

Return Value

string The processed string

at line 1035
static string replaceWelcomeTokens(string $str, string $group, bool $html)

Replace welcome/confirmation tokens

Parameters

string $str The string with tokens to be replaced.
string $group The name of the group being subscribed.
bool $html Replace tokens with html or plain text.

Return Value

string The processed string

at line 1051
static array unmatchedTokens(string $str)

Find unprocessed tokens (call this last)

Parameters

string $str The string to search.

Return Value

array Array of tokens that weren't replaced

at line 1073
static string replaceComponentTokens(string $str, array $contact, array $components, bool $escapeSmarty = FALSE, bool $returnEmptyToken = TRUE)

Find and replace tokens for each component.

Parameters

string $str The string to search.
array $contact Associative array of contact properties.
array $components A list of tokens that are known to exist in the email body.
bool $escapeSmarty
bool $returnEmptyToken

Return Value

string The processed string

at line 1105
static array getTokens(string $string)

Get array of string tokens.

Parameters

string $string The input string to parse for tokens.

Return Value

array array of tokens mentioned in field

at line 1135
static array getReturnProperties($string)

Function to determine which values to retrieve to insert into tokens. The heavy resemblance between this function and getTokens appears to be historical rather than intentional and should be reviewed

Parameters

$string

Return Value

array fields to pass in as return properties when populating token

at line 1176
static array getTokenDetails(array $contactIDs, array $returnProperties = NULL, bool $skipOnHold = TRUE, bool $skipDeceased = TRUE, array $extraParams = NULL, array $tokens = [], null $className = NULL, int $jobID = NULL)

Gives required details of contacts in an indexed array format so we can iterate in a nice loop and do token evaluation

Parameters

array $contactIDs
array $returnProperties Of required properties.
bool $skipOnHold Don't return on_hold contact info also. Don't return on_hold contact info also.
bool $skipDeceased Don't return deceased contact info. Don't return deceased contact info.
array $extraParams Extra params.
array $tokens The list of tokens we've extracted from the content.
null $className
int $jobID The mailing list jobID - this is a legacy param.

Return Value

array

at line 1301
static array getAnonymousTokenDetails(array $contactIDs = [0], string $returnProperties = NULL, bool $skipOnHold = TRUE, bool $skipDeceased = TRUE, string $extraParams = NULL, array $tokens = [], string $className = NULL, string $jobID = NULL)

Call hooks on tokens for anonymous users - contact id is set to 0 - this allows non-contact specific tokens to be rendered

Parameters

array $contactIDs This should always be array(0) or its not anonymous - left to keep signature same. as main fn
string $returnProperties
bool $skipOnHold
bool $skipDeceased
string $extraParams
array $tokens
string $className Sent as context to the hook.
string $jobID

Return Value

array contactDetails with hooks swapped out

at line 1327
static getMembershipTokenDetails(array $membershipIDs)

Get Membership Token Details.

Parameters

array $membershipIDs Array of membership IDS.

at line 1353
static replaceGreetingTokens(string $tokenString, array $contactDetails = NULL, int $contactId = NULL, string $className = NULL, bool $escapeSmarty = FALSE)

Replace existing greeting tokens in message/subject.

This function operates by reference, modifying the first parameter. Other methods for token replacement in this class return the modified string. This leads to inconsistency in how these methods must be applied.

Parameters

string $tokenString
array $contactDetails
int $contactId
string $className
bool $escapeSmarty

at line 1482
static array flattenTokens($tokens)

Parameters

$tokens

Return Value

array

at line 1518
static string replaceUserTokens(string $str, null $knownTokens = NULL, bool $escapeSmarty = FALSE)

Replace all user tokens in $str

Parameters

string $str The string with tokens to be replaced.
null $knownTokens
bool $escapeSmarty

Return Value

string The processed string

at line 1542
static string getUserTokenReplacement($token, bool $escapeSmarty = FALSE)

Parameters

$token
bool $escapeSmarty

Return Value

string

at line 1564
static protected _buildContributionTokens()

at line 1577
static protected _buildMembershipTokens()

Store membership tokens on the static _tokens array.

at line 1602
static string replaceEntityTokens(string $entity, array $entityArray, string $str, array $knownTokens = [], bool $escapeSmarty = FALSE)

Replace tokens for an entity.

Parameters

string $entity
array $entityArray (e.g. in format from api).
string $str String to replace in.
array $knownTokens Array of tokens present.
bool $escapeSmarty

Return Value

string string with replacements made

at line 1628
static string replaceCaseTokens(int $caseId, int $str, array $knownTokens = [], bool $escapeSmarty = FALSE)

Parameters

int $caseId
int $str
array $knownTokens
bool $escapeSmarty

Return Value

string

Exceptions

CiviCRM_API3_Exception

at line 1645
static string getApiTokenReplacement(string $entity, string $token, array $entityArray)

Generic function for formatting token replacement for an api field

Parameters

string $entity
string $token
array $entityArray

Return Value

string

Exceptions

CiviCRM_API3_Exception

at line 1682
static mixed replaceContributionTokens(string $str, array $contribution, bool|string $html = FALSE, string $knownTokens = NULL, bool|string $escapeSmarty = FALSE)

Replace Contribution tokens in html.

Parameters

string $str
array $contribution
bool|string $html
string $knownTokens
bool|string $escapeSmarty

Return Value

mixed

at line 1726
static string replaceMultipleContributionTokens(string $separator, string $str, array $contribution, bool|string $html = FALSE, string $knownTokens = NULL, bool|string $escapeSmarty = FALSE)

We have a situation where we are rendering more than one token in each field because we are combining tokens from more than one contribution when pdf thank you letters are grouped (CRM-14367)

The replaceContributionToken doesn't handle receive_date correctly in this scenario because of the formatting it applies (other tokens are OK including date fields)

So we sort this out & then call the main function. Note that we are not escaping smarty on this fields like the main function does - but the fields is already being formatted through a date function

Parameters

string $separator
string $str
array $contribution
bool|string $html
string $knownTokens
bool|string $escapeSmarty

Return Value

string

at line 1754
static string getMembershipTokenReplacement(string $entity, string $token, array $membership)

Get replacement strings for any membership tokens (only a small number of tokens are implemnted in the first instance - this is used by the pdfLetter task from membership search

Parameters

string $entity should always be "membership"
string $token field name
array $membership An api result array for a single membership.

Return Value

string token replacement

at line 1806
static mixed|string getContributionTokenReplacement($token, $contribution, bool $html = FALSE, bool $escapeSmarty = FALSE)

Parameters

$token
$contribution
bool $html
bool $escapeSmarty

Return Value

mixed|string

at line 1842
static array legacyContactTokens()

Return Value

array [legacy_token => new_token]

at line 1860
static array getCustomFieldTokens(string $entity, bool $usedForTokenWidget = FALSE)

Get all custom field tokens of $entity

Parameters

string $entity
bool $usedForTokenWidget

Return Value

array return custom field tokens in array('custom_N' => 'label') format

at line 1876
static array formatTokensForDisplay($tokens)

Formats a token list for the select2 widget

Parameters

$tokens

Return Value

array