CRM/Contribute/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\ActionSchedule\Event\MailingQueryEvent;
  14 use Civi\Token\AbstractTokenSubscriber;
  15 use Civi\Token\TokenProcessor;
  16 use Civi\Token\TokenRow;
  17
  18 /**
  19  * Class CRM_Contribute_Tokens
  20  *
  21  * Generate "contribution.*" tokens.
  22  *
  23  * At time of writing, we don't have any particularly special tokens -- we just
  24  * do some basic formatting based on the corresponding DB field.
  25  */
  26 class CRM_Contribute_Tokens extends AbstractTokenSubscriber {
  27
  28   /**
  29    * Get a list of tokens whose name and title match the DB fields.
  30    * @return array
  31    */
  32   protected function getPassthruTokens(): array {
  33     return [
  34       'contribution_page_id',
  35       'receive_date',
  36       'total_amount',
  37       'fee_amount',
  38       'net_amount',
  39       'trxn_id',
  40       'invoice_id',
  41       'currency',
  42       'contribution_cancel_date',
  43       'receipt_date',
  44       'thankyou_date',
  45       'tax_amount',
  46       'contribution_status_id',
  47     ];
  48   }
  49
  50   /**
  51    * Get alias tokens.
  52    *
  53    * @return array
  54    */
  55   protected function getAliasTokens(): array {
  56     return [
  57       'id' => 'contribution_id',
  58       'payment_instrument' => 'payment_instrument_id',
  59       'source' => 'contribution_source',
  60       'status' => 'contribution_status_id',
  61       'type' => 'financial_type_id',
  62       'cancel_date' => 'contribution_cancel_date',
  63     ];
  64   }
  65
  66   /**
  67    * Get tokens supporting the syntax we are migrating to.
  68    *
  69    * In general these are tokens that were not previously supported
  70    * so we can add them in the preferred way or that we have
  71    * undertaken some, as yet to be written, db update.
  72    *
  73    * See https://lab.civicrm.org/dev/core/-/issues/2650
  74    *
  75    * @return string[]
  76    */
  77   protected function getBasicTokens(): array {
  78     return ['contribution_status_id' => ts('Contribution Status ID')];
  79   }
  80
  81   /**
  82    * Class constructor.
  83    */
  84   public function __construct() {
  85     $tokens = CRM_Utils_Array::subset(
  86       CRM_Utils_Array::collect('title', CRM_Contribute_DAO_Contribution::fields()),
  87       $this->getPassthruTokens()
  88     );
  89     $tokens['id'] = ts('Contribution ID');
  90     $tokens['payment_instrument'] = ts('Payment Instrument');
  91     $tokens['source'] = ts('Contribution Source');
  92     // Per https://lab.civicrm.org/dev/core/-/issues/2650
  93     // the intent is to deprecate this field in favour of
  94     // {contribution.contribution_status_id:label}
  95     $tokens['status'] = ts('Contribution Status');
  96     $tokens['type'] = ts('Financial Type');
  97     $tokens = array_merge($tokens, CRM_Utils_Token::getCustomFieldTokens('Contribution'));
  98     parent::__construct('contribution', $tokens);
  99   }
 100
 101   /**
 102    * Check if the token processor is active.
 103    *
 104    * @param \Civi\Token\TokenProcessor $processor
 105    *
 106    * @return bool
 107    */
 108   public function checkActive(TokenProcessor $processor) {
 109     return !empty($processor->context['actionMapping'])
 110       && $processor->context['actionMapping']->getEntity() === 'civicrm_contribution';
 111   }
 112
 113   /**
 114    * Alter action schedule query.
 115    *
 116    * @param \Civi\ActionSchedule\Event\MailingQueryEvent $e
 117    */
 118   public function alterActionScheduleQuery(MailingQueryEvent $e): void {
 119     if ($e->mapping->getEntity() !== 'civicrm_contribution') {
 120       return;
 121     }
 122
 123     $fields = CRM_Contribute_DAO_Contribution::fields();
 124     foreach ($this->getPassthruTokens() as $token) {
 125       $e->query->select("e." . $fields[$token]['name'] . " AS contrib_{$token}");
 126     }
 127     foreach ($this->getAliasTokens() as $alias => $orig) {
 128       $e->query->select("e." . $fields[$orig]['name'] . " AS contrib_{$alias}");
 129     }
 130   }
 131
 132   /**
 133    * @inheritDoc
 134    */
 135   public function evaluateToken(TokenRow $row, $entity, $field, $prefetch = NULL) {
 136     $actionSearchResult = $row->context['actionSearchResult'];
 137     $fieldValue = $actionSearchResult->{"contrib_$field"} ?? NULL;
 138
 139     $aliasTokens = $this->getAliasTokens();
 140     if (in_array($field, ['total_amount', 'fee_amount', 'net_amount'])) {
 141       return $row->format('text/plain')->tokens($entity, $field,
 142         \CRM_Utils_Money::format($fieldValue, $actionSearchResult->contrib_currency));
 143     }
 144     if (isset($aliasTokens[$field])) {
 145       $row->dbToken($entity, $field, 'CRM_Contribute_BAO_Contribution', $aliasTokens[$field], $fieldValue);
 146     }
 147     elseif ($cfID = \CRM_Core_BAO_CustomField::getKeyID($field)) {
 148       $row->customToken($entity, $cfID, $actionSearchResult->entity_id);
 149     }
 150     elseif (in_array($field, array_keys($this->getBasicTokens()))) {
 151       // For now we just ensure that the label fields do not override the
 152       // id field here.
 153       // Later we will add support for contribution_status_id:label
 154       $row->tokens($entity, $field, $fieldValue);
 155     }
 156     else {
 157       $row->dbToken($entity, $field, 'CRM_Contribute_BAO_Contribution', $field, $fieldValue);
 158     }
 159   }
 160
 161 }