Documentation

CRM_Utils_Token
in package

Application

Class to abstract token replacement.

Properties

$_requiredTokens : mixed
$_tokens : mixed

Methods

flattenTokens() : array<string|int, mixed>
formatTokensForDisplay() : array<string|int, mixed>: Formats a token list for the select2 widget
getActionTokenReplacement() : mixed|string
getAnonymousTokenDetails() : array<string|int, mixed>: Call hooks on tokens for anonymous users - contact id is set to 0 - this allows non-contact specific tokens to be rendered
getApiTokenReplacement() : string: Generic function for formatting token replacement for an api field
getContactTokenReplacement() : bool|mixed|null|string: Do Not use.
getContributionTokenReplacement() : mixed|string: Do not use - unused in core.
getCustomFieldTokens() : array<string|int, mixed>: Get all custom field tokens of $entity
getDomainTokenReplacement() : null|string: Do not use.
getHookTokenReplacement() : mixed|string: Do not use, unused in core.
getMailingTokenReplacement() : string
getMembershipTokenDetails() : mixed: Get Membership Token Details.
getMembershipTokenReplacement() : string: 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
getRequiredTokens() : array<string|int, mixed>
getReturnProperties() : array<string|int, mixed>: 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
getTokenCategories() : array<string|int, mixed>: Get the categories required for rendering tokens.
getTokenDeprecations() : array<string|int, mixed>: Get token deprecation information.
getTokenDetails() : array<string|int, mixed>: Do not use this function.
getTokens() : array<string|int, mixed>: Get array of string tokens.
getUserTokenReplacement() : string
legacyContactTokens() : array<string|int, mixed>
replaceActionTokens() : string: Replace all action tokens in $str
replaceContactTokens() : string: Replace all the contact-level tokens in $str with information from $contact.
replaceDomainTokens() : string: Replace all the domain-level tokens in $str
replaceEntityTokens() : string: Do not use.
replaceGreetingTokens() : mixed: Replace existing greeting tokens in message/subject.
replaceHookTokens() : string: Do not use - unused in core.
replaceMailingTokens() : string: Replace all mailing tokens in $str
replaceResubscribeTokens() : string: Replace resubscribe tokens.
replaceSubscribeInviteTokens() : string: Replace subscription-invitation tokens
replaceSubscribeTokens() : string: Replace subscription-confirmation-request tokens
replaceUnsubscribeTokens() : string: Replace unsubscribe tokens.
replaceUserTokens() : string: Replace all user tokens in $str
replaceWelcomeTokens() : string: Replace welcome/confirmation tokens
requiredTokens() : bool|array<string|int, mixed>: Check a string (mailing body) for required tokens.
token_match() : bool: Wrapper for token matching.
token_replace() : string: Wrapper for token replacing.
tokenEscapeSmarty() : string: Escape the string so a malicious user cannot inject smarty code into the template.
unescapeTokens() : mixed: 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
unmatchedTokens() : array<string|int, mixed>: Find unprocessed tokens (call this last)
_buildContributionTokens() : mixed
convertPseudoConstantsUsingMetadata() : bool|int|mixed|string|null
tokenRegex() : string: Get the regex for token replacement

$_requiredTokens


    public
    static    mixed
    $_requiredTokens
     = \NULL

$_tokens


    public
    static    mixed
    $_tokens
     = [
    'action' => ['forward', 'optOut', 'optOutUrl', 'reply', 'unsubscribe', 'unsubscribeUrl', 'resubscribe', 'resubscribeUrl', 'subscribeUrl'],
    'mailing' => ['id', 'key', 'name', 'group', 'subject', 'viewUrl', 'editUrl', 'scheduleUrl', 'approvalStatus', 'approvalNote', 'approveUrl', 'creator', 'creatorEmail'],
    'user' => [
        // we extract the stuff after the role / permission and return the
        // civicrm email addresses of all users with that role / permission
        // useful with rules integration
        'permission:',
        'role:',
    ],
    // populate this dynamically
    'contact' => \NULL,
    // populate this dynamically
    'contribution' => \NULL,
    'domain' => ['name', 'phone', 'address', 'email', 'id', 'description'],
    'subscribe' => ['group'],
    'unsubscribe' => ['group'],
    'resubscribe' => ['group'],
    'welcome' => ['group'],
]

flattenTokens()


    public
            static        flattenTokens(mixed &$tokens) : array<string|int, mixed>

Parameters

$tokens : mixed

Return values

array<string|int, mixed>

formatTokensForDisplay()

Formats a token list for the select2 widget


    public
            static        formatTokensForDisplay(mixed $tokens) : array<string|int, mixed>

Parameters

$tokens : mixed

Return values

array<string|int, mixed>

getActionTokenReplacement()


    public
            static        getActionTokenReplacement(mixed $token, mixed &$addresses, mixed &$urls[, bool $html = FALSE ][, bool $escapeSmarty = FALSE ]) : mixed|string

Parameters

$token : mixed
$addresses : mixed
$urls : mixed
$html : bool = FALSE
$escapeSmarty : bool = FALSE

Return values

mixed|string

getAnonymousTokenDetails()

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


    public
            static        getAnonymousTokenDetails([array<string|int, mixed> $contactIDs = [0] ][, string $returnProperties = NULL ][, bool $skipOnHold = TRUE ][, bool $skipDeceased = TRUE ][, string $extraParams = NULL ][, array<string|int, mixed> $tokens = [] ][, string $className = NULL ][, string $jobID = NULL ]) : array<string|int, mixed>

Parameters

$contactIDs : array<string|int, mixed> = [0]: This should always be array(0) or its not anonymous - left to keep signature same. as main fn
$returnProperties : string = NULL
$skipOnHold : bool = TRUE
$skipDeceased : bool = TRUE
$extraParams : string = NULL
$tokens : array<string|int, mixed> = []
$className : string = NULL: Sent as context to the hook.
$jobID : string = NULL

Return values

array<string|int, mixed> —

contactDetails with hooks swapped out

getApiTokenReplacement()

Generic function for formatting token replacement for an api field


    public
            static        getApiTokenReplacement(string $entity, string $token, array<string|int, mixed> $entityArray) : string

Parameters

$entity : string
$token : string
$entityArray : array<string|int, mixed>

Return values

string

getContactTokenReplacement()

Do Not use.


    public
            static        getContactTokenReplacement(mixed $token, mixed &$contact[, bool $html = FALSE ][, bool $returnBlankToken = FALSE ][, bool $escapeSmarty = FALSE ]) : bool|mixed|null|string

Only core usage is from a deprecated unused function and from deprecated BAO_Mailing code (to be replaced by flexmailer).

Parameters

$token : mixed
$contact : mixed
$html : bool = FALSE
$returnBlankToken : bool = FALSE
$escapeSmarty : bool = FALSE

Return values

bool|mixed|null|string

getContributionTokenReplacement()

Do not use - unused in core.


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

Parameters

$token : mixed
$contribution : mixed
$html : bool = FALSE
$escapeSmarty : bool = FALSE

Return values

mixed|string

getCustomFieldTokens()

Get all custom field tokens of $entity


    public
            static        getCustomFieldTokens(string $entity) : array<string|int, mixed>

Parameters

$entity : string

Return values

array<string|int, mixed> —

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

getDomainTokenReplacement()

Do not use.


    public
            static        getDomainTokenReplacement(string $token, CRM_Core_BAO_Domain $domain[, bool $html = FALSE ][, bool $escapeSmarty = FALSE ]) : null|string

Parameters

$token : string
$domain : CRM_Core_BAO_Domain
$html : bool = FALSE
$escapeSmarty : bool = FALSE

Return values

null|string

getHookTokenReplacement()

Do not use, unused in core.


    public
            static        getHookTokenReplacement(mixed $token, mixed &$contact, mixed $category[, bool $html = FALSE ][, bool $escapeSmarty = FALSE ]) : mixed|string

Parameters

$token : mixed
$contact : mixed
$category : mixed
$html : bool = FALSE
$escapeSmarty : bool = FALSE

Return values

mixed|string

getMailingTokenReplacement()


    public
            static        getMailingTokenReplacement(mixed $token, mixed &$mailing[, bool $escapeSmarty = FALSE ]) : string

Parameters

$token : mixed
$mailing : mixed
$escapeSmarty : bool = FALSE

Return values

string

getMembershipTokenDetails()

Get Membership Token Details.


    public
            static        getMembershipTokenDetails(array<string|int, mixed> $membershipIDs) : mixed

Parameters

$membershipIDs : array<string|int, mixed>: Array of membership IDS.

getMembershipTokenReplacement()

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


    public
            static        getMembershipTokenReplacement(string $entity, string $token, array<string|int, mixed> $membership) : string

This is called via replaceEntityTokens.

In the near term it will not be called at all from core as the pdf letter task is updated to use the processor.

Parameters

$entity : string: should always be "membership"
$token : string: field name
$membership : array<string|int, mixed>: An api result array for a single membership.

Return values

string —

token replacement

getRequiredTokens()


    public
            static        getRequiredTokens() : array<string|int, mixed>

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

Return values

array<string|int, mixed>

getReturnProperties()

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


    public
            static        getReturnProperties(mixed &$string) : array<string|int, mixed>

Parameters

$string : mixed

Return values

array<string|int, mixed> —

fields to pass in as return properties when populating token

getTokenCategories()

Get the categories required for rendering tokens.


    public
            static        getTokenCategories() : array<string|int, mixed>

since 5.78 will be removed around 5.90.

Return values

array<string|int, mixed>

getTokenDeprecations()

Get token deprecation information.


    public
            static        getTokenDeprecations() : array<string|int, mixed>

Return values

array<string|int, mixed>

getTokenDetails()

Do not use this function.


    public
            static        getTokenDetails(array<string|int, mixed> $contactIDs[, array<string|int, mixed> $returnProperties = NULL ][, bool $skipOnHold = TRUE ][, bool $skipDeceased = TRUE ][, array<string|int, mixed> $extraParams = NULL ][, array<string|int, mixed> $tokens = [] ][, string|null $className = NULL ][, int|null $jobID = NULL ]) : array<string|int, mixed>

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

Parameters

$contactIDs : array<string|int, mixed>
$returnProperties : array<string|int, mixed> = NULL: Of required properties.
$skipOnHold : bool = TRUE: Don't return on_hold contact info also. Don't return on_hold contact info also.
$skipDeceased : bool = TRUE: Don't return deceased contact info. Don't return deceased contact info.
$extraParams : array<string|int, mixed> = NULL: Extra params - DEPRECATED
$tokens : array<string|int, mixed> = []: The list of tokens we've extracted from the content.
$className : string|null = NULL
$jobID : int|null = NULL: The mailing list jobID - this is a legacy param.

Return values

array<string|int, mixed> —

e.g [[1 => ['first_name' => 'bob'...], 34 => ['first_name' => 'fred'...]]]

getTokens()

Get array of string tokens.


    public
            static        getTokens(string $string) : array<string|int, mixed>

Parameters

$string : string: The input string to parse for tokens.

Return values

array<string|int, mixed> —

array of tokens mentioned in field

getUserTokenReplacement()


    public
            static        getUserTokenReplacement(mixed $token[, bool $escapeSmarty = FALSE ]) : string

Parameters

$token : mixed
$escapeSmarty : bool = FALSE

Return values

string

legacyContactTokens()


    public
            static        legacyContactTokens() : array<string|int, mixed>

Only used from deprecated functions not called by core.

Return values

array<string|int, mixed> —

[legacy_token => new_token]

replaceActionTokens()

Replace all action tokens in $str


    public
            static    &    replaceActionTokens(string $str, array<string|int, mixed> &$addresses, array<string|int, mixed> &$urls[, bool $html = FALSE ][, array<string|int, mixed> $knownTokens = NULL ][, bool $escapeSmarty = FALSE ]) : string

Parameters

$str : string: The string with tokens to be replaced.
$addresses : array<string|int, mixed>: Assoc. array of VERP event addresses.
$urls : array<string|int, mixed>: Assoc. array of action URLs.
$html : bool = FALSE: Replace tokens with HTML or plain text.
$knownTokens : array<string|int, mixed> = NULL: A list of tokens that are known to exist in the email body.
$escapeSmarty : bool = FALSE

Return values

string —

The processed string

replaceContactTokens()

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


    public
            static        replaceContactTokens(string $str, array<string|int, mixed> &$contact[, bool $html = FALSE ][, array<string|int, mixed> $knownTokens = NULL ][, bool $returnBlankToken = FALSE ][, bool $escapeSmarty = FALSE ]) : string

Parameters

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

Return values

string —

The processed string

replaceDomainTokens()

Replace all the domain-level tokens in $str


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

since ages ago will be removed around 5.90

Parameters

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

Return values

string —

The processed string

replaceEntityTokens()

Do not use.


    public
            static        replaceEntityTokens(string $entity, array<string|int, mixed> $entityArray, string $str[, array<string|int, mixed> $knownTokens = [] ][, bool $escapeSmarty = FALSE ]) : string

Replace tokens for an entity.

Parameters

$entity : string
$entityArray : array<string|int, mixed>: (e.g. in format from api).
$str : string: String to replace in.
$knownTokens : array<string|int, mixed> = []: Array of tokens present.
$escapeSmarty : bool = FALSE

Return values

string —

string with replacements made

replaceGreetingTokens()

Replace existing greeting tokens in message/subject.


    public
            static        replaceGreetingTokens(string &$tokenString[, array<string|int, mixed> $contactDetails = NULL ][, int $contactId = NULL ][, string $className = NULL ][, bool $escapeSmarty = FALSE ]) : mixed

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

$tokenString : string
$contactDetails : array<string|int, mixed> = NULL
$contactId : int = NULL
$className : string = NULL
$escapeSmarty : bool = FALSE

replaceHookTokens()

Do not use - unused in core.


    public
            static    &    replaceHookTokens(string $str, array<string|int, mixed> &$contact[, mixed $categories = NULL ][, bool $html = FALSE ][, bool $escapeSmarty = FALSE ]) : string

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

Parameters

$str : string: The string with tokens to be replaced.
$contact : array<string|int, mixed>: Associative array of contact properties (including hook token values).
$categories : mixed = NULL
$html : bool = FALSE: Replace tokens with HTML or plain text.
$escapeSmarty : bool = FALSE

Return values

string —

The processed string

replaceMailingTokens()

Replace all mailing tokens in $str


    public
            static    &    replaceMailingTokens(string $str, object &$mailing[, bool $html = FALSE ][, null $knownTokens = NULL ][, bool $escapeSmarty = FALSE ]) : string

Parameters

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

Return values

string —

The processed string

replaceResubscribeTokens()

Replace resubscribe tokens.


    public
            static        replaceResubscribeTokens(string $str, null $youHaveBeenRickRolled, array<string|int, mixed> $groups) : string

Parameters

$str : string: The string with tokens to be replaced.
$youHaveBeenRickRolled : null: The domain BAO.
$groups : array<string|int, mixed>: The groups (if any) being resubscribed.

Return values

string —

The processed string

replaceSubscribeInviteTokens()

Replace subscription-invitation tokens


    public
            static    &    replaceSubscribeInviteTokens(string $str) : string

Parameters

$str : string: The string with tokens to be replaced.

Return values

string —

The processed string

replaceSubscribeTokens()

Replace subscription-confirmation-request tokens


    public
            static    &    replaceSubscribeTokens(string $str, string $group, mixed $url, bool $html) : string

Parameters

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

Return values

string —

The processed string

replaceUnsubscribeTokens()

Replace unsubscribe tokens.


    public
            static    &    replaceUnsubscribeTokens(string $str, object &$domain, array<string|int, mixed> &$groups, bool $html, int $contact_id, string $hash) : string

Parameters

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

Return values

string —

The processed string

replaceUserTokens()

Replace all user tokens in $str


    public
            static    &    replaceUserTokens(string $str[, null $knownTokens = NULL ][, bool $escapeSmarty = FALSE ]) : string

Parameters

$str : string: The string with tokens to be replaced.
$knownTokens : null = NULL
$escapeSmarty : bool = FALSE

Return values

string —

The processed string

replaceWelcomeTokens()

Replace welcome/confirmation tokens


    public
            static    &    replaceWelcomeTokens(string $str, string $group, bool $html) : string

since 5.65 will be removed around 5.71

Parameters

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

Return values

string —

The processed string

requiredTokens()

Check a string (mailing body) for required tokens.


    public
            static        requiredTokens(string &$str) : bool|array<string|int, mixed>

since 5.78 will be removed around 5.90

Parameters

$str : string: The message.

Return values

bool|array<string|int, mixed> —

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

token_match()

Wrapper for token matching.


    public
            static        token_match(string $type, string $var, string &$str) : bool

Parameters

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

Return values

bool —

Was there a match

token_replace()

Wrapper for token replacing.


    public
            static        token_replace(string $type, string $var, string $value, string &$str[, bool $escapeSmarty = FALSE ]) : string

Parameters

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

Return values

string —

The processed string

tokenEscapeSmarty()

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


    public
            static        tokenEscapeSmarty(string $string) : string

Parameters

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

Return values

string —

the escaped string

unescapeTokens()

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


    public
            static        unescapeTokens(string &$str) : mixed

this routine will remove the extra backslashes and braces

Parameters

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

unmatchedTokens()

Find unprocessed tokens (call this last)


    public
            static    &    unmatchedTokens(string &$str) : array<string|int, mixed>

Parameters

$str : string: The string to search.

Return values

array<string|int, mixed> —

Array of tokens that weren't replaced

_buildContributionTokens()


    protected
            static        _buildContributionTokens() : mixed

Do not use this function - it still needs full removal from active code in CRM_Contribute_Form_Task_PDFLetter.

convertPseudoConstantsUsingMetadata()


    protected
            static        convertPseudoConstantsUsingMetadata(mixed $value, mixed $token) : bool|int|mixed|string|null

Parameters

$value : mixed
$token : mixed

Return values

bool|int|mixed|string|null

tokenRegex()

Get the regex for token replacement


    private
            static        tokenRegex(string $token_type) : string

Parameters

$token_type : string: A string indicating the the type of token to be used in the expression.

Return values

string —

regular expression suitable for using in preg_replace

CRM_Utils_Token in package Application

Table of Contents

Properties

Methods

Properties

$_requiredTokens

$_tokens

Methods

flattenTokens()

Parameters

Return values

formatTokensForDisplay()

Parameters

Return values

getActionTokenReplacement()

Parameters

Return values

getAnonymousTokenDetails()

Parameters

Return values

getApiTokenReplacement()

Parameters

Tags

Return values

getContactTokenReplacement()

Parameters

Return values

getContributionTokenReplacement()

Parameters

Tags

Return values

getCustomFieldTokens()

Parameters

Return values

getDomainTokenReplacement()

Parameters

Return values

getHookTokenReplacement()

Parameters

Return values

getMailingTokenReplacement()

Parameters

Return values

getMembershipTokenDetails()

Parameters

getMembershipTokenReplacement()

Parameters

Return values

getRequiredTokens()

Return values

getReturnProperties()

Parameters

Return values

getTokenCategories()

Return values

getTokenDeprecations()

Return values

getTokenDetails()

Parameters

Return values

getTokens()

Parameters

Return values

getUserTokenReplacement()

Parameters

Return values

legacyContactTokens()

Return values

replaceActionTokens()

Parameters

Return values

replaceContactTokens()

Parameters

Return values

replaceDomainTokens()

Parameters

Return values

replaceEntityTokens()

Parameters

Return values

CRM_Utils_Token
in package

Application