CRM/Contact/Tokens.php

   1 <?php
   2
   3 /*
   4  +--------------------------------------------------------------------+
   5  | Copyright CiviCRM LLC. All rights reserved.                        |
   6  |                                                                    |
   7  | This work is published under the GNU AGPLv3 license with some      |
   8  | permitted exceptions and without any warranty. For full license    |
   9  | and copyright information, see https://civicrm.org/licensing       |
  10  +--------------------------------------------------------------------+
  11  */
  12
  13 use Civi\Api4\Contact;
  14 use Civi\Token\Event\TokenRegisterEvent;
  15 use Civi\Token\Event\TokenValueEvent;
  16 use Civi\Token\TokenProcessor;
  17 use Civi\Token\TokenRow;
  18
  19 /**
  20  * Class CRM_Contact_Tokens
  21  *
  22  * Generate "contact.*" tokens.
  23  */
  24 class CRM_Contact_Tokens extends CRM_Core_EntityTokens {
  25
  26   /**
  27    * Get the entity name for api v4 calls.
  28    *
  29    * @return string
  30    */
  31   protected function getApiEntityName(): string {
  32     return 'Contact';
  33   }
  34
  35   /**
  36    * @inheritDoc
  37    */
  38   public static function getSubscribedEvents(): array {
  39     return [
  40       'civi.token.eval' => [
  41         ['evaluateLegacyHookTokens', 500],
  42         ['onEvaluate'],
  43       ],
  44       'civi.token.list' => 'registerTokens',
  45     ];
  46   }
  47
  48   /**
  49    * Register the declared tokens.
  50    *
  51    * @param \Civi\Token\Event\TokenRegisterEvent $e
  52    *   The registration event. Add new tokens using register().
  53    *
  54    * @throws \CRM_Core_Exception
  55    */
  56   public function registerTokens(TokenRegisterEvent $e): void {
  57     if (!$this->checkActive($e->getTokenProcessor())) {
  58       return;
  59     }
  60     $relatedTokens = array_flip($this->getTokenMappingsForRelatedEntities());
  61     foreach ($this->getTokenMetadata() as $tokenName => $field) {
  62       if ($field['audience'] === 'user') {
  63         $e->register([
  64           'entity' => $this->entity,
  65           // Preserve legacy token names. It generally feels like
  66           // it would be good to switch to the more specific token names
  67           // but other code paths are still in use which can't handle them.
  68           'field' => $relatedTokens[$tokenName] ?? $tokenName,
  69           'label' => $field['title'],
  70         ]);
  71       }
  72     }
  73     foreach ($this->getLegacyHookTokens() as $legacyHookToken) {
  74       $e->register([
  75         'entity' => $legacyHookToken['category'],
  76         'field' => $legacyHookToken['name'],
  77         'label' => $legacyHookToken['label'],
  78       ]);
  79     }
  80   }
  81
  82   /**
  83    * Determine whether this token-handler should be used with
  84    * the given processor.
  85    *
  86    * To short-circuit token-processing in irrelevant contexts,
  87    * override this.
  88    *
  89    * @param \Civi\Token\TokenProcessor $processor
  90    * @return bool
  91    */
  92   public function checkActive(TokenProcessor $processor): bool {
  93     return in_array($this->getEntityIDField(), $processor->context['schema'], TRUE);
  94   }
  95
  96   /**
  97    * @return string
  98    */
  99   protected function getEntityIDField(): string {
 100     return 'contactId';
 101   }
 102
 103   /**
 104    * Get functions declared using the legacy hook.
 105    *
 106    * Note that these only extend the contact entity (
 107    * ie they are based on having a contact ID which they.
 108    * may or may not use, but they don't have other
 109    * entity IDs.)
 110    *
 111    * @return array
 112    */
 113   protected function getLegacyHookTokens(): array {
 114     $tokens = [];
 115
 116     foreach ($this->getHookTokens() as $tokenValues) {
 117       foreach ($tokenValues as $key => $value) {
 118         if (is_numeric($key)) {
 119           // This appears to be an attempt to compensate for
 120           // inconsistencies described in https://docs.civicrm.org/dev/en/latest/hooks/hook_civicrm_tokenValues/#example
 121           // in effect there is a suggestion that
 122           // Send an Email" and "CiviMail" send different parameters to the tokenValues hook
 123           // As of now 'send an email' renders hooks through this class.
 124           // CiviMail it depends on the use or otherwise of flexmailer.
 125           $key = $value;
 126         }
 127         if (preg_match('/^\{([^\}]+)\}$/', $value, $matches)) {
 128           $value = $matches[1];
 129         }
 130         $keyParts = explode('.', $key);
 131         $tokens[$key] = [
 132           'category' => $keyParts[0],
 133           'name' => $keyParts[1],
 134           'label' => $value,
 135         ];
 136       }
 137     }
 138     return $tokens;
 139   }
 140
 141   /**
 142    * Get all tokens advertised as contact tokens.
 143    *
 144    * @return string[]
 145    */
 146   protected function getExposedFields(): array {
 147     return [
 148       'contact_type',
 149       'do_not_email',
 150       'do_not_phone',
 151       'do_not_mail',
 152       'do_not_sms',
 153       'do_not_trade',
 154       'is_opt_out',
 155       'external_identifier',
 156       'sort_name',
 157       'display_name',
 158       'nick_name',
 159       'image_URL',
 160       'preferred_communication_method',
 161       'preferred_language',
 162       'preferred_mail_format',
 163       'hash',
 164       'source',
 165       'first_name',
 166       'middle_name',
 167       'last_name',
 168       'prefix_id',
 169       'suffix_id',
 170       'formal_title',
 171       'communication_style_id',
 172       'job_title',
 173       'gender_id',
 174       'birth_date',
 175       'employer_id',
 176       'is_deleted',
 177       'created_date',
 178       'modified_date',
 179       'addressee_display',
 180       'email_greeting_display',
 181       'postal_greeting_display',
 182       'id',
 183     ];
 184   }
 185
 186   /**
 187    * Get the fields exposed from related entities.
 188    *
 189    * @return \string[][]
 190    */
 191   protected function getRelatedEntityTokenMetadata(): array {
 192     return [
 193       'address' => [
 194         'location_type_id',
 195         'id',
 196         'street_address',
 197         'street_number',
 198         'street_number_suffix',
 199         'street_name',
 200         'street_unit',
 201         'supplemental_address_1',
 202         'supplemental_address_2',
 203         'supplemental_address_3',
 204         'city',
 205         'postal_code_suffix',
 206         'postal_code',
 207         'manual_geo_code',
 208         'geo_code_1',
 209         'geo_code_2',
 210         'name',
 211         'master_id',
 212         'county_id',
 213         'state_province_id',
 214         'country_id',
 215       ],
 216       'phone' => ['phone', 'phone_ext', 'phone_type_id'],
 217       'email' => ['email', 'signature_html', 'signature_text', 'on_hold'],
 218       'website' => ['url'],
 219       'openid' => ['openid'],
 220       'im' => ['name', 'provider_id'],
 221     ];
 222   }
 223
 224   /**
 225    * Load token data from legacy hooks.
 226    *
 227    * While our goal is for people to move towards implementing
 228    * toke processors the old-style hooks can extend contact
 229    * token data.
 230    *
 231    * When that is happening we need to load the full contact record
 232    * to send to the hooks (not great for performance but the
 233    * fix is to move away from implementing legacy style hooks).
 234    *
 235    * Consistent with prior behaviour we only load the contact it it
 236    * is already loaded. In that scenario we also load any extra fields
 237    * that might be wanted for the contact tokens.
 238    *
 239    * @param \Civi\Token\Event\TokenValueEvent $e
 240    *
 241    * @throws \CRM_Core_Exception
 242    */
 243   public function evaluateLegacyHookTokens(TokenValueEvent $e): void {
 244     $messageTokens = $e->getTokenProcessor()->getMessageTokens();
 245     if (empty($messageTokens) || !array_intersect(array_keys($this->getHookTokens()), array_keys($messageTokens))) {
 246       return;
 247     }
 248
 249     foreach ($e->getRows() as $row) {
 250       if (empty($row->context['contactId'])) {
 251         continue;
 252       }
 253       unset($swapLocale);
 254       $swapLocale = empty($row->context['locale']) ? NULL : \CRM_Utils_AutoClean::swapLocale($row->context['locale']);
 255       if (empty($row->context['contact'])) {
 256         // If we don't have the contact already load it now, getting full
 257         // details for hooks and anything the contact token resolution might
 258         // want later.
 259         $row->context['contact'] = $this->getContact($row->context['contactId'], $messageTokens['contact'] ?? [], TRUE);
 260       }
 261       $contactArray = [$row->context['contactId'] => $row->context['contact']];
 262       \CRM_Utils_Hook::tokenValues($contactArray,
 263         [$row->context['contactId']],
 264         empty($row->context['mailingJobId']) ? NULL : $row->context['mailingJobId'],
 265         $messageTokens,
 266         $row->context['controller']
 267       );
 268       foreach ($this->getHookTokens() as $category => $hookToken) {
 269         if (!empty($messageTokens[$category])) {
 270           foreach (array_keys($hookToken) as $tokenName) {
 271             $tokenPartOnly = str_replace($category . '.', '', $tokenName);
 272             if (in_array($tokenPartOnly, $messageTokens[$category], TRUE)) {
 273               $row->format('text/html')
 274                 ->tokens($category, str_replace($category . '.', '', $tokenName), $contactArray[$row->context['contactId']][$tokenName] ?? ($contactArray[$row->context['contactId']][$category . '.' . $tokenName] ?? ''));
 275             }
 276           }
 277         }
 278       }
 279     }
 280   }
 281
 282   /**
 283    * Load token data.
 284    *
 285    * @param \Civi\Token\Event\TokenValueEvent $e
 286    *
 287    * @throws TokenException
 288    * @throws \CRM_Core_Exception
 289    */
 290   public function onEvaluate(TokenValueEvent $e) {
 291     $messageTokens = $e->getTokenProcessor()->getMessageTokens()['contact'] ?? [];
 292     if (empty($messageTokens)) {
 293       return;
 294     }
 295
 296     foreach ($e->getRows() as $row) {
 297       if (empty($row->context['contactId']) && empty($row->context['contact'])) {
 298         continue;
 299       }
 300
 301       unset($swapLocale);
 302       $swapLocale = empty($row->context['locale']) ? NULL : \CRM_Utils_AutoClean::swapLocale($row->context['locale']);
 303
 304       if (empty($row->context['contact'])) {
 305         $row->context['contact'] = $this->getContact($row->context['contactId'], $messageTokens);
 306       }
 307
 308       foreach ($messageTokens as $token) {
 309         if ($token === 'checksum') {
 310           $cs = \CRM_Contact_BAO_Contact_Utils::generateChecksum($row->context['contactId'],
 311             NULL,
 312             NULL,
 313             $row->context['hash'] ?? NULL
 314           );
 315           $row->format('text/html')
 316             ->tokens('contact', $token, "cs={$cs}");
 317         }
 318         elseif ($token === 'signature_html') {
 319           $row->format('text/html')->tokens('contact', $token, html_entity_decode($row->context['contact'][$token]));
 320         }
 321         else {
 322           parent::evaluateToken($row, $this->entity, $token, $row->context['contact']);
 323         }
 324       }
 325     }
 326   }
 327
 328   /**
 329    * Get the field value.
 330    *
 331    * @param \Civi\Token\TokenRow $row
 332    * @param string $field
 333    * @return string|int
 334    */
 335   protected function getFieldValue(TokenRow $row, string $field) {
 336     $entityName = 'contact';
 337     if (isset($this->getDeprecatedTokens()[$field])) {
 338       // Check the non-deprecated location first, fall back to deprecated
 339       // this is important for the greetings because - they are weird in the query object.
 340       $possibilities = [$this->getDeprecatedTokens()[$field], $field];
 341     }
 342     else {
 343       $possibilities = [$field];
 344       if (in_array($field, $this->getDeprecatedTokens(), TRUE)) {
 345         $possibilities[] = array_search($field, $this->getDeprecatedTokens(), TRUE);
 346       }
 347     }
 348
 349     foreach ($possibilities as $possibility) {
 350       if (isset($row->context[$entityName][$possibility])) {
 351         return $row->context[$entityName][$possibility];
 352       }
 353     }
 354     return '';
 355   }
 356
 357   /**
 358    * Get the metadata for the available fields.
 359    *
 360    * @return array
 361    * @noinspection PhpDocMissingThrowsInspection
 362    * @noinspection PhpUnhandledExceptionInspection
 363    */
 364   protected function getTokenMetadata(): array {
 365     if ($this->tokensMetadata) {
 366       return $this->tokensMetadata;
 367     }
 368     if (Civi::cache('metadata')->has($this->getCacheKey())) {
 369       return Civi::cache('metadata')->get($this->getCacheKey());
 370     }
 371     $this->fieldMetadata = (array) civicrm_api4('Contact', 'getfields', ['checkPermissions' => FALSE], 'name');
 372     $this->tokensMetadata = $this->getBespokeTokens();
 373     foreach ($this->fieldMetadata as $field) {
 374       $this->addFieldToTokenMetadata($field, $this->getExposedFields());
 375     }
 376
 377     foreach ($this->getRelatedEntityTokenMetadata() as $entity => $exposedFields) {
 378       $apiEntity = ($entity === 'openid') ? 'OpenID' : ucfirst($entity);
 379       $metadata = (array) civicrm_api4($apiEntity, 'getfields', ['checkPermissions' => FALSE], 'name');
 380       foreach ($metadata as $field) {
 381         $this->addFieldToTokenMetadata($field, $exposedFields, 'primary_' . $entity);
 382       }
 383     }
 384     // Manually add in the abbreviated state province as that maps to
 385     // what has traditionally been delivered.
 386     $this->tokensMetadata['primary_address.state_province_id:abbr'] = $this->tokensMetadata['primary_address.state_province_id:label'];
 387     $this->tokensMetadata['primary_address.state_province_id:abbr']['name'] = 'state_province_id:abbr';
 388     $this->tokensMetadata['primary_address.state_province_id:abbr']['audience'] = 'user';
 389     // Hide the label for now because we are not sure if there are paths
 390     // where legacy token resolution is in play where this could not be resolved.
 391     $this->tokensMetadata['primary_address.state_province_id:label']['audience'] = 'sysadmin';
 392     // Hide this really obscure one. Just cos it annoys me.
 393     $this->tokensMetadata['primary_address.manual_geo_code:label']['audience'] = 'sysadmin';
 394     Civi::cache('metadata')->set($this->getCacheKey(), $this->tokensMetadata);
 395     return $this->tokensMetadata;
 396   }
 397
 398   /**
 399    * Get the contact for the row.
 400    *
 401    * @param int $contactId
 402    * @param array $requiredFields
 403    * @param bool $getAll
 404    *
 405    * @return array
 406    * @throws \CRM_Core_Exception
 407    */
 408   protected function getContact(int $contactId, array $requiredFields, bool $getAll = FALSE): array {
 409     $returnProperties = [];
 410     if (in_array('checksum', $requiredFields, TRUE)) {
 411       $returnProperties[] = 'hash';
 412     }
 413     foreach ($this->getTokenMappingsForRelatedEntities() as $oldName => $newName) {
 414       if (in_array($oldName, $requiredFields, TRUE)) {
 415         $returnProperties[] = $newName;
 416       }
 417     }
 418     $joins = [];
 419     $customFields = [];
 420     foreach ($requiredFields as $field) {
 421       $fieldSpec = $this->getMetadataForField($field);
 422       $prefix = '';
 423       if (isset($fieldSpec['table_name']) && $fieldSpec['table_name'] !== 'civicrm_contact') {
 424         $tableAlias = str_replace('civicrm_', 'primary_', $fieldSpec['table_name']);
 425         $joins[$tableAlias] = $fieldSpec['entity'];
 426
 427         $prefix = $tableAlias . '.';
 428       }
 429       if ($fieldSpec['type'] === 'Custom') {
 430         $customFields['custom_' . $fieldSpec['custom_field_id']] = $fieldSpec['name'];
 431       }
 432       $returnProperties[] = $prefix . $this->getMetadataForField($field)['name'];
 433     }
 434
 435     if ($getAll) {
 436       $returnProperties = array_merge(['*', 'custom.*'], $this->getDeprecatedTokens(), $this->getTokenMappingsForRelatedEntities());
 437     }
 438
 439     $contactApi = Contact::get($this->checkPermissions)
 440       ->setSelect($returnProperties)->addWhere('id', '=', $contactId);
 441     foreach ($joins as $alias => $joinEntity) {
 442       $contactApi->addJoin($joinEntity . ' AS ' . $alias,
 443         'LEFT',
 444         ['id', '=', $alias . '.contact_id'],
 445         // For website the fact we use 'first' is the deduplication.
 446         ($joinEntity !== 'Website' ? [$alias . '.is_primary', '=', 1] : []));
 447     }
 448     $contact = $contactApi->execute()->first();
 449
 450     foreach ($this->getDeprecatedTokens() as $apiv3Name => $fieldName) {
 451       // it would be set already with the right value for a greeting token
 452       // the query object returns the db value for email_greeting_display
 453       // and a numeric value for email_greeting if you put email_greeting
 454       // in the return properties.
 455       if (!isset($contact[$apiv3Name]) && array_key_exists($fieldName, $contact)) {
 456         $contact[$apiv3Name] = $contact[$fieldName];
 457       }
 458     }
 459     foreach ($this->getTokenMappingsForRelatedEntities() as $oldName => $newName) {
 460       if (isset($contact[$newName])) {
 461         $contact[$oldName] = $contact[$newName];
 462       }
 463     }
 464
 465     //update value of custom field token
 466     foreach ($customFields as $apiv3Name => $fieldName) {
 467       $value = $contact[$fieldName];
 468       if ($this->getMetadataForField($apiv3Name)['data_type'] === 'Boolean') {
 469         $value = (int) $value;
 470       }
 471       $contact[$apiv3Name] = \CRM_Core_BAO_CustomField::displayValue($value, \CRM_Core_BAO_CustomField::getKeyID($apiv3Name));
 472     }
 473
 474     return $contact;
 475   }
 476
 477   /**
 478    * Get the array of the return fields from 'get all'.
 479    *
 480    * This is the list from the BAO_Query object but copied
 481    * here to be 'frozen in time'. The goal is to map to apiv4
 482    * and stop using the legacy call to load the contact.
 483    *
 484    * @return array
 485    */
 486   protected function getAllContactReturnFields(): array {
 487     return [
 488       'image_URL' => 1,
 489       'legal_identifier' => 1,
 490       'external_identifier' => 1,
 491       'contact_type' => 1,
 492       'contact_sub_type' => 1,
 493       'sort_name' => 1,
 494       'display_name' => 1,
 495       'preferred_mail_format' => 1,
 496       'nick_name' => 1,
 497       'first_name' => 1,
 498       'middle_name' => 1,
 499       'last_name' => 1,
 500       'prefix_id' => 1,
 501       'suffix_id' => 1,
 502       'formal_title' => 1,
 503       'communication_style_id' => 1,
 504       'birth_date' => 1,
 505       'gender_id' => 1,
 506       'street_address' => 1,
 507       'supplemental_address_1' => 1,
 508       'supplemental_address_2' => 1,
 509       'supplemental_address_3' => 1,
 510       'city' => 1,
 511       'postal_code' => 1,
 512       'postal_code_suffix' => 1,
 513       'state_province' => 1,
 514       'country' => 1,
 515       'world_region' => 1,
 516       'geo_code_1' => 1,
 517       'geo_code_2' => 1,
 518       'email' => 1,
 519       'on_hold' => 1,
 520       'phone' => 1,
 521       'im' => 1,
 522       'household_name' => 1,
 523       'organization_name' => 1,
 524       'deceased_date' => 1,
 525       'is_deceased' => 1,
 526       'job_title' => 1,
 527       'legal_name' => 1,
 528       'sic_code' => 1,
 529       'current_employer' => 1,
 530       'do_not_email' => 1,
 531       'do_not_mail' => 1,
 532       'do_not_sms' => 1,
 533       'do_not_phone' => 1,
 534       'do_not_trade' => 1,
 535       'is_opt_out' => 1,
 536       'contact_is_deleted' => 1,
 537       'preferred_communication_method' => 1,
 538       'preferred_language' => 1,
 539     ];
 540   }
 541
 542   /**
 543    * These tokens still work but we don't advertise them.
 544    *
 545    * We can remove from the following places
 546    * - scheduled reminders
 547    * - add to 'blocked' on pdf letter & email
 548    *
 549    * & then at some point start issuing warnings for them
 550    * but contact tokens are pretty central so it might be
 551    * a bit drawn out.
 552    *
 553    * @return string[]
 554    *   Keys are deprecated tokens and values are their replacements.
 555    */
 556   protected function getDeprecatedTokens(): array {
 557     return [
 558       'individual_prefix' => 'prefix_id:label',
 559       'individual_suffix' => 'suffix_id:label',
 560       'contact_type' => 'contact_type:label',
 561       'gender' => 'gender_id:label',
 562       'communication_style' => 'communication_style_id:label',
 563       'preferred_communication_method' => 'preferred_communication_method:label',
 564       'email_greeting' => 'email_greeting_display',
 565       'postal_greeting' => 'postal_greeting_display',
 566       'addressee' => 'addressee_display',
 567       'contact_id' => 'id',
 568       'contact_source' => 'source',
 569       'contact_is_deleted' => 'is_deleted',
 570       'current_employer_id' => 'employer_id',
 571     ];
 572   }
 573
 574   /**
 575    * Get the tokens that are accessed by joining onto a related entity.
 576    *
 577    * Note the original thinking was to migrate to advertising the tokens
 578    * that more accurately reflect the schema & also add support for e.g
 579    * billing_address.street_address - which would be hugely useful for workflow
 580    * message templates.
 581    *
 582    * However that feels like a bridge too far for this round
 583    * since we haven't quite hit the goal of all token processing going through
 584    * the token processor & we risk advertising tokens that don't work if we get
 585    * ahead of that process.
 586    *
 587    * @return string[]
 588    */
 589   protected function getTokenMappingsForRelatedEntities(): array {
 590     return [
 591       'on_hold' => 'primary_email.on_hold',
 592       'on_hold:label' => 'primary_email.on_hold:label',
 593       'phone_type_id' => 'primary_phone.phone_type_id',
 594       'phone_type_id:label' => 'primary_phone.phone_type_id:label',
 595       'current_employer' => 'employer_id.display_name',
 596       'location_type_id' => 'primary_address.location_type_id',
 597       'location_type' => 'primary_address.location_type_id:label',
 598       'location_type_id:label' => 'primary_address.location_type_id:label',
 599       'street_address' => 'primary_address.street_address',
 600       'address_id' => 'primary_address.id',
 601       'address_name' => 'primary_address.name',
 602       'street_number' => 'primary_address.street_number',
 603       'street_number_suffix' => 'primary_address.street_number_suffix',
 604       'street_name' => 'primary_address.street_name',
 605       'street_unit' => 'primary_address.street_unit',
 606       'supplemental_address_1' => 'primary_address.supplemental_address_1',
 607       'supplemental_address_2' => 'primary_address.supplemental_address_2',
 608       'supplemental_address_3' => 'primary_address.supplemental_address_3',
 609       'city' => 'primary_address.city',
 610       'postal_code' => 'primary_address.postal_code',
 611       'postal_code_suffix' => 'primary_address.postal_code_suffix',
 612       'geo_code_1' => 'primary_address.geo_code_1',
 613       'geo_code_2' => 'primary_address.geo_code_2',
 614       'manual_geo_code' => 'primary_address.manual_geo_code',
 615       'master_id' => 'primary_address.master_id',
 616       'county' => 'primary_address.county_id:label',
 617       'county_id' => 'primary_address.county_id',
 618       'state_province' => 'primary_address.state_province_id:abbr',
 619       'state_province_id' => 'primary_address.state_province_id',
 620       'country' => 'primary_address.country_id:label',
 621       'country_id' => 'primary_address.country_id',
 622       'world_region' => 'primary_address.country_id.region_id:name',
 623       'phone_type' => 'primary_phone.phone_type_id:label',
 624       'phone' => 'primary_phone.phone',
 625       'phone_ext' => 'primary_phone.phone_ext',
 626       'email' => 'primary_email.email',
 627       'signature_text' => 'primary_email.signature_text',
 628       'signature_html' => 'primary_email.signature_html',
 629       'im' => 'primary_im.name',
 630       'im_provider' => 'primary_im.provider_id',
 631       'provider_id:label' => 'primary_im.provider_id:label',
 632       'provider_id' => 'primary_im.provider_id',
 633       'openid' => 'primary_openid.openid',
 634       'url' => 'primary_website.url',
 635     ];
 636   }
 637
 638   /**
 639    * Get calculated or otherwise 'special', tokens.
 640    *
 641    * @return array[]
 642    */
 643   protected function getBespokeTokens(): array {
 644     return [
 645       'checksum' => [
 646         'title' => ts('Checksum'),
 647         'name' => 'checksum',
 648         'type' => 'calculated',
 649         'options' => NULL,
 650         'data_type' => 'String',
 651         'audience' => 'user',
 652       ],
 653       'employer_id.display_name' => [
 654         'title' => ts('Current Employer'),
 655         'name' => 'employer_id.display_name',
 656         'type' => 'mapped',
 657         'api_v3' => 'current_employer',
 658         'options' => NULL,
 659         'data_type' => 'String',
 660         'audience' => 'user',
 661       ],
 662       'primary_address.country_id.region_id:name' => [
 663         'title' => ts('World Region'),
 664         'name' => 'country_id.region_id.name',
 665         'type' => 'mapped',
 666         'api_v3' => 'world_region',
 667         'options' => NULL,
 668         'data_type' => 'String',
 669         'advertised_name' => 'world_region',
 670         'audience' => 'user',
 671       ],
 672       // this gets forced out if we specify individual fields
 673       'organization_name' => [
 674         'title' => ts('Organization name'),
 675         'name' => 'organization_name',
 676         'type' => 'Field',
 677         'options' => NULL,
 678         'data_type' => 'String',
 679         'audience' => 'sysadmin',
 680       ],
 681     ];
 682   }
 683
 684   /**
 685    * Get the tokens defined by the legacy hook.
 686    *
 687    * @return array
 688    */
 689   protected function getHookTokens(): array {
 690     if (isset(Civi::$statics[__CLASS__]['hook_tokens'])) {
 691       return Civi::$statics[__CLASS__]['hook_tokens'];
 692     }
 693     $tokens = [];
 694     \CRM_Utils_Hook::tokens($tokens);
 695     Civi::$statics[__CLASS__]['hook_tokens'] = $tokens;
 696     return $tokens;
 697   }
 698
 699 }