Documentation

CRM_Contact_Tokens extends CRM_Core_EntityTokens
in package

Class CRM_Contact_Tokens

Generate "contact.*" tokens.

Table of Contents

Properties

$activeTokens  : array<string|int, mixed>
$entity  : string
$tokenNames  : array<string|int, mixed>
$checkPermissions  : bool
Should permissions be checked when loading tokens.
$fieldMetadata  : array<string|int, mixed>
Metadata about the entity fields.
$prefetch  : array<string|int, mixed>
$tokensMetadata  : array<string|int, mixed>
Metadata about all tokens.

Methods

__construct()  : mixed
Class constructor.
alterActionScheduleQuery()  : void
Alter action schedule query.
checkActive()  : bool
Determine whether this token-handler should be used with the given processor.
evaluateLegacyHookTokens()  : void
Load token data from legacy hooks.
evaluateToken()  : mixed
Evaluate the content of a single token.
evaluateTokens()  : mixed
Populate the token data.
getActiveTokens()  : mixed
To handle variable tokens, override this function and return the active tokens.
getExtendableTableName()  : string
Get the name of the table this token class can extend.
getPrefetchFields()  : array<string|int, mixed>
Get the fields required to prefetch the entity.
getSubscribedEvents()  : array<string|int, mixed>
isHTMLTextField()  : bool
Is the text stored in html format.
onEvaluate()  : mixed
Load token data.
prefetch()  : mixed
To perform a bulk lookup before rendering tokens, override this function and return the prefetched data.
registerTokens()  : void
Register the declared tokens.
addFieldToTokenMetadata()  : void
Add the token to the metadata based on the field spec.
getApiEntityName()  : string
Get the entity name for api v4 calls.
getBasicTokens()  : array<string|int, string>
getBespokeTokens()  : array<string|int, array<string|int, mixed>>
Get calculated or otherwise 'special', tokens.
getCacheKey()  : string
Get a cache key appropriate to the current usage.
getContact()  : array<string|int, mixed>
Get the contact for the row.
getCurrency()  : string
Get the currency to use for formatting money.
getCurrencyFieldName()  : mixed
getCustomFieldName()  : string
Get the apiv4 style custom field name.
getCustomFieldValue()  : array<string|int, mixed>|string|void|null
getDependencies()  : array<string|int, mixed>
Get fields which need to be returned to render another token.
getDeprecatedTokens()  : array<string|int, string>
These tokens still work but we don't advertise them.
getEntityAlias()  : string
Get the entity alias to use within queries.
getEntityIDField()  : string
getEntityName()  : string
getExposedFields()  : array<string|int, string>
Get all tokens advertised as contact tokens.
getFieldMetadata()  : array<string|int, mixed>
Get the metadata for the available fields.
getFieldValue()  : string|int
Get the field value.
getHiddenTokens()  : array<string|int, mixed>
Get tokens to be suppressed from the widget.
getHookTokens()  : array<string|int, mixed>
Get the tokens defined by the legacy hook.
getLegacyHookTokens()  : array<string|int, mixed>
Get functions declared using the legacy hook.
getMetadataForField()  : array<string|int, mixed>
Get the metadata for the field.
getRelatedEntityTokenMetadata()  : array<string|int, array<string|int, string>>
Get the fields exposed from related entities.
getRelatedTokens()  : array<string|int, mixed>
Get related entity tokens.
getRelatedTokensForEntity()  : array<string|int, mixed>
Get metadata for tokens for a related entity joined by a field on the main entity.
getReturnFields()  : array<string|int, string>
Get an array of fields to be requested.
getSkippedFields()  : array<string|int, string>
Get entity fields that should not be exposed as tokens.
getTokenMappingsForRelatedEntities()  : array<string|int, string>
Get the tokens that are accessed by joining onto a related entity.
getTokenMetadata()  : array<string|int, mixed>
Get the metadata for the available fields.
getTokenMetadataOverrides()  : array<string|int, array<string|int, string>>
Get any overrides for token metadata.
isBooleanField()  : bool
Is the given field a boolean field.
isCustomField()  : bool
Is the given field a custom field.
isDateField()  : bool
Is the given field a date field.
isMoneyField()  : bool
Is the given field a date field.
isPseudoField()  : bool
Is the given field a pseudo field.
getEmptyBillingEntities()  : array<string|int, mixed>
Get the array of related billing entities that are empty.

Properties

$activeTokens

public array<string|int, mixed> $activeTokens

List of active tokens - tokens provided by this class and used in the message Array(string $tokenName);

$tokenNames

public array<string|int, mixed> $tokenNames

List of tokens provided by this class Array(string $fieldName => string $label).

$checkPermissions

Should permissions be checked when loading tokens.

protected bool $checkPermissions = \FALSE

$fieldMetadata

Metadata about the entity fields.

protected array<string|int, mixed> $fieldMetadata = []

$prefetch

protected array<string|int, mixed> $prefetch = []

$tokensMetadata

Metadata about all tokens.

protected array<string|int, mixed> $tokensMetadata = []

Methods

__construct()

Class constructor.

public __construct() : mixed

checkActive()

Determine whether this token-handler should be used with the given processor.

public checkActive(TokenProcessor $processor) : bool

To short-circuit token-processing in irrelevant contexts, override this.

Parameters
$processor : TokenProcessor
Return values
bool

evaluateLegacyHookTokens()

Load token data from legacy hooks.

public evaluateLegacyHookTokens(TokenValueEvent $e) : void

While our goal is for people to move towards implementing toke processors the old-style hooks can extend contact token data.

When that is happening we need to load the full contact record to send to the hooks (not great for performance but the fix is to move away from implementing legacy style hooks).

Consistent with prior behaviour we only load the contact it it is already loaded. In that scenario we also load any extra fields that might be wanted for the contact tokens.

Parameters
$e : TokenValueEvent
Tags
throws
CRM_Core_Exception

evaluateToken()

Evaluate the content of a single token.

public evaluateToken(TokenRow $row, mixed $entity, mixed $field[, mixed $prefetch = NULL ]) : mixed
Parameters
$row : TokenRow

The record for which we want token values.

$entity : mixed

The name of the token entity.

$field : mixed

The name of the token field.

$prefetch : mixed = NULL

Any data that was returned by the prefetch().

Tags
inheritDoc
throws
CRM_Core_Exception

getExtendableTableName()

Get the name of the table this token class can extend.

public getExtendableTableName() : string

The default is based on the entity but some token classes, specifically the event class, latch on to other tables - ie the participant table.

Return values
string

getSubscribedEvents()

public static getSubscribedEvents() : array<string|int, mixed>
Tags
inheritDoc
Return values
array<string|int, mixed>

isHTMLTextField()

Is the text stored in html format.

public isHTMLTextField(string $fieldName) : bool
Parameters
$fieldName : string
Return values
bool

addFieldToTokenMetadata()

Add the token to the metadata based on the field spec.

protected addFieldToTokenMetadata(array<string|int, mixed> &$tokensMetadata, array<string|int, mixed> $field, array<string|int, mixed> $exposedFields[, string $prefix = '' ]) : void
Parameters
$tokensMetadata : array<string|int, mixed>
$field : array<string|int, mixed>
$exposedFields : array<string|int, mixed>
$prefix : string = ''

getApiEntityName()

Get the entity name for api v4 calls.

protected getApiEntityName() : string
Return values
string

getBasicTokens()

protected getBasicTokens() : array<string|int, string>
Tags
todo

remove this function & use the metadata that is loaded.

throws
CRM_Core_Exception
Return values
array<string|int, string>

getBespokeTokens()

Get calculated or otherwise 'special', tokens.

protected getBespokeTokens() : array<string|int, array<string|int, mixed>>
Return values
array<string|int, array<string|int, mixed>>

getCacheKey()

Get a cache key appropriate to the current usage.

protected getCacheKey() : string
Return values
string

getContact()

Get the contact for the row.

protected getContact(int $contactId, array<string|int, mixed> $requiredFields[, bool $getAll = FALSE ]) : array<string|int, mixed>
Parameters
$contactId : int
$requiredFields : array<string|int, mixed>
$getAll : bool = FALSE
Tags
throws
CRM_Core_Exception
Return values
array<string|int, mixed>

getCurrency()

Get the currency to use for formatting money.

protected getCurrency(mixed $row) : string
Parameters
$row : mixed
Return values
string

getCurrencyFieldName()

protected getCurrencyFieldName() : mixed

getCustomFieldName()

Get the apiv4 style custom field name.

protected getCustomFieldName(int $id) : string
Parameters
$id : int
Tags
throws
CRM_Core_Exception
Return values
string

getCustomFieldValue()

protected getCustomFieldValue(mixed $entityID, string $field) : array<string|int, mixed>|string|void|null
Parameters
$entityID : mixed
$field : string

eg. 'custom_1'

Tags
throws
CRM_Core_Exception
Return values
array<string|int, mixed>|string|void|null —

$mixed

getDependencies()

Get fields which need to be returned to render another token.

protected getDependencies() : array<string|int, mixed>
Return values
array<string|int, mixed>

getDeprecatedTokens()

These tokens still work but we don't advertise them.

protected getDeprecatedTokens() : array<string|int, string>

We can remove from the following places

  • scheduled reminders
  • add to 'blocked' on pdf letter & email

& then at some point start issuing warnings for them but contact tokens are pretty central so it might be a bit drawn out.

Return values
array<string|int, string> —

Keys are deprecated tokens and values are their replacements.

getEntityAlias()

Get the entity alias to use within queries.

protected getEntityAlias() : string

The default has a double underscore which should prevent any ambiguity with an existing table name.

Return values
string

getEntityIDField()

protected getEntityIDField() : string
Return values
string

getEntityName()

protected getEntityName() : string
Return values
string

getExposedFields()

Get all tokens advertised as contact tokens.

protected getExposedFields() : array<string|int, string>
Return values
array<string|int, string>

getFieldMetadata()

Get the metadata for the available fields.

protected getFieldMetadata() : array<string|int, mixed>
Return values
array<string|int, mixed>

getFieldValue()

Get the field value.

protected getFieldValue(TokenRow $row, string $field) : string|int
Parameters
$row : TokenRow
$field : string
Tags
throws
CRM_Core_Exception
Return values
string|int

getHiddenTokens()

Get tokens to be suppressed from the widget.

protected getHiddenTokens() : array<string|int, mixed>

Note this is expected to be an interim function. Now we are no longer working around the parent function we can just define them once... with metadata, in a future refactor.

Return values
array<string|int, mixed>

getHookTokens()

Get the tokens defined by the legacy hook.

protected getHookTokens() : array<string|int, mixed>
Return values
array<string|int, mixed>

getLegacyHookTokens()

Get functions declared using the legacy hook.

protected getLegacyHookTokens() : array<string|int, mixed>

Note that these only extend the contact entity ( ie they are based on having a contact ID which they. may or may not use, but they don't have other entity IDs.)

Return values
array<string|int, mixed>

getMetadataForField()

Get the metadata for the field.

protected getMetadataForField(string $fieldName) : array<string|int, mixed>
Parameters
$fieldName : string
Return values
array<string|int, mixed>

getRelatedEntityTokenMetadata()

Get the fields exposed from related entities.

protected getRelatedEntityTokenMetadata() : array<string|int, array<string|int, string>>
Return values
array<string|int, array<string|int, string>>

getRelatedTokens()

Get related entity tokens.

protected getRelatedTokens() : array<string|int, mixed>
Return values
array<string|int, mixed>

getRelatedTokensForEntity()

Get metadata for tokens for a related entity joined by a field on the main entity.

protected getRelatedTokensForEntity(string $entity, string $joinField, array<string|int, mixed> $tokenList[, array<string|int, mixed> $hiddenTokens = [] ]) : array<string|int, mixed>
Parameters
$entity : string
$joinField : string
$tokenList : array<string|int, mixed>
$hiddenTokens : array<string|int, mixed> = []
Tags
throws
CRM_Core_Exception
Return values
array<string|int, mixed>

getReturnFields()

Get an array of fields to be requested.

protected getReturnFields() : array<string|int, string>
Tags
todo

this function should look up tokenMetadata that is already loaded.

Return values
array<string|int, string>

getSkippedFields()

Get entity fields that should not be exposed as tokens.

protected getSkippedFields() : array<string|int, string>
Return values
array<string|int, string>

getTokenMappingsForRelatedEntities()

Get the tokens that are accessed by joining onto a related entity.

protected getTokenMappingsForRelatedEntities() : array<string|int, string>

This is an array of legacy style tokens mapped to the new style - so that discontinued tokens still work (although they are no longer advertised).

There are three types of legacy tokens

  • apiv3 style - e.g {contact.email}
  • ad hoc - hey cos it's CiviCRM
  • 'wrong' apiv4 style - ie I thought we would do 'primary_address' but we did 'address_primary' - these were added as the 'real token names' but not advertised & likely never adopted so handling them for a while is a conservative approach.

The new type maps to the v4 api.

Return values
array<string|int, string>

getTokenMetadata()

Get the metadata for the available fields.

protected getTokenMetadata() : array<string|int, mixed>
Tags
noinspection

PhpDocMissingThrowsInspection

noinspection

PhpUnhandledExceptionInspection

Return values
array<string|int, mixed>

getTokenMetadataOverrides()

Get any overrides for token metadata.

protected getTokenMetadataOverrides() : array<string|int, array<string|int, string>>

This is most obviously used for setting the audience, which will affect widget-presence.

Return values
array<string|int, array<string|int, string>>

isBooleanField()

Is the given field a boolean field.

protected isBooleanField(string $fieldName) : bool
Parameters
$fieldName : string
Return values
bool

isCustomField()

Is the given field a custom field.

protected isCustomField(string $fieldName) : bool
Parameters
$fieldName : string
Return values
bool

isDateField()

Is the given field a date field.

protected isDateField(string $fieldName) : bool
Parameters
$fieldName : string
Return values
bool

isMoneyField()

Is the given field a date field.

protected isMoneyField(string $fieldName) : bool
Parameters
$fieldName : string
Return values
bool

isPseudoField()

Is the given field a pseudo field.

protected isPseudoField(string $fieldName) : bool
Parameters
$fieldName : string
Return values
bool

getEmptyBillingEntities()

Get the array of related billing entities that are empty.

private getEmptyBillingEntities(array<string|int, mixed> $billingFields, array<string|int, mixed> $contact) : array<string|int, mixed>

The billing tokens fall back to the primary address tokens as we cannot rely on all contacts having an address with is_billing set and the code historically has treated billing addresses as 'get the best billing address', despite the failure to set the fields.

Here we figure out the entities where swapping in the primary fields makes sense. This is the case when there is no billing address at all, but we don't want to 'supplement' a partial billing address with data from a possibly-completely-different primary address.

Parameters
$billingFields : array<string|int, mixed>
$contact : array<string|int, mixed>
Return values
array<string|int, mixed> 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results