4 +--------------------------------------------------------------------+
5 | Copyright CiviCRM LLC. All rights reserved. |
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 +--------------------------------------------------------------------+
13 use Civi\ActionSchedule\Event\MailingQueryEvent
;
14 use Civi\Token\AbstractTokenSubscriber
;
15 use Civi\Token\TokenProcessor
;
16 use Civi\Token\TokenRow
;
19 * Class CRM_Contribute_Tokens
21 * Generate "contribution.*" tokens.
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.
26 class CRM_Contribute_Tokens
extends AbstractTokenSubscriber
{
31 private function getEntityName(): string {
32 return 'contribution';
36 * Get the relevant bao name.
38 public function getBAOName(): string {
39 return CRM_Core_DAO_AllCoreTables
::getFullName(ucfirst($this->getEntityName()));
43 * Metadata about the entity fields.
47 protected $entityFieldMetadata = [];
50 * Get a list of tokens whose name and title match the DB fields.
53 protected function getPassthruTokens(): array {
55 'contribution_page_id',
63 'contribution_cancel_date',
67 'contribution_status_id',
76 protected function getAliasTokens(): array {
78 'id' => 'contribution_id',
79 'payment_instrument' => 'payment_instrument_id',
80 'source' => 'contribution_source',
81 'type' => 'financial_type_id',
82 'cancel_date' => 'contribution_cancel_date',
87 * Get tokens supporting the syntax we are migrating to.
89 * In general these are tokens that were not previously supported
90 * so we can add them in the preferred way or that we have
91 * undertaken some, as yet to be written, db update.
93 * See https://lab.civicrm.org/dev/core/-/issues/2650
97 protected function getBasicTokens(): array {
98 return ['contribution_status_id' => ts('Contribution Status ID')];
102 * Get pseudoTokens - it tokens that reflect the name or label of a pseudoconstant.
104 * @internal - this function will likely be made protected soon.
108 public function getPseudoTokens(): array {
110 foreach (array_keys($this->getBasicTokens()) as $fieldName) {
111 if (!empty($this->entityFieldMetadata
[$fieldName]['pseudoconstant'])) {
112 $return[$fieldName . ':label'] = $this->entityFieldMetadata
[$fieldName]['html']['label'];
113 $return[$fieldName . ':name'] = ts('Machine name') . ': ' . $this->entityFieldMetadata
[$fieldName]['html']['label'];
122 public function __construct() {
123 $this->entityFieldMetadata
= CRM_Contribute_DAO_Contribution
::fields();
124 $tokens = CRM_Utils_Array
::subset(
125 CRM_Utils_Array
::collect('title', $this->entityFieldMetadata
),
126 $this->getPassthruTokens()
128 $tokens['id'] = ts('Contribution ID');
129 $tokens['payment_instrument'] = ts('Payment Instrument');
130 $tokens['source'] = ts('Contribution Source');
131 $tokens['type'] = ts('Financial Type');
132 $tokens = array_merge($tokens, $this->getPseudoTokens(), CRM_Utils_Token
::getCustomFieldTokens('Contribution'));
133 parent
::__construct('contribution', $tokens);
137 * Check if the token processor is active.
139 * @param \Civi\Token\TokenProcessor $processor
143 public function checkActive(TokenProcessor
$processor) {
144 return !empty($processor->context
['actionMapping'])
145 && $processor->context
['actionMapping']->getEntity() === 'civicrm_contribution';
149 * Alter action schedule query.
151 * @param \Civi\ActionSchedule\Event\MailingQueryEvent $e
153 public function alterActionScheduleQuery(MailingQueryEvent
$e): void
{
154 if ($e->mapping
->getEntity() !== 'civicrm_contribution') {
158 $fields = CRM_Contribute_DAO_Contribution
::fields();
159 foreach ($this->getPassthruTokens() as $token) {
160 $e->query
->select("e." . $fields[$token]['name'] . " AS contrib_{$token}");
162 foreach (array_keys($this->getPseudoTokens()) as $token) {
163 $split = explode(':', $token);
164 $e->query
->select("e." . $fields[$split[0]]['name'] . " AS contrib_{$split[0]}");
166 foreach ($this->getAliasTokens() as $alias => $orig) {
167 $e->query
->select('e.' . $fields[$orig]['name'] . " AS contrib_{$alias}");
174 public function evaluateToken(TokenRow
$row, $entity, $field, $prefetch = NULL) {
175 $actionSearchResult = $row->context
['actionSearchResult'];
176 $fieldValue = $actionSearchResult->{"contrib_$field"} ??
NULL;
178 $aliasTokens = $this->getAliasTokens();
179 if (in_array($field, ['total_amount', 'fee_amount', 'net_amount'])) {
180 return $row->format('text/plain')->tokens($entity, $field,
181 \CRM_Utils_Money
::format($fieldValue, $actionSearchResult->contrib_currency
));
183 if (isset($aliasTokens[$field])) {
184 $row->dbToken($entity, $field, 'CRM_Contribute_BAO_Contribution', $aliasTokens[$field], $fieldValue);
186 elseif ($cfID = \CRM_Core_BAO_CustomField
::getKeyID($field)) {
187 $row->customToken($entity, $cfID, $actionSearchResult->entity_id
);
189 elseif (array_key_exists($field, $this->getPseudoTokens())) {
190 $split = explode(':', $field);
191 $row->tokens($entity, $field, $this->getPseudoValue($split[0], $split[1], $actionSearchResult->{"contrib_$split[0]"} ??
NULL));
193 elseif (in_array($field, array_keys($this->getBasicTokens()))) {
194 $row->tokens($entity, $field, $fieldValue);
197 $row->dbToken($entity, $field, 'CRM_Contribute_BAO_Contribution', $field, $fieldValue);
202 * Get the value for the relevant pseudo field.
204 * @param string $realField e.g contribution_status_id
205 * @param string $pseudoKey e.g name
206 * @param int|string $fieldValue e.g 1
209 * Eg. 'Completed' in the example above.
211 * @internal function will likely be protected soon.
213 public function getPseudoValue(string $realField, string $pseudoKey, $fieldValue): string {
214 if ($pseudoKey === 'name') {
215 $fieldValue = (string) CRM_Core_PseudoConstant
::getName($this->getBAOName(), $realField, $fieldValue);
217 if ($pseudoKey === 'label') {
218 $fieldValue = (string) CRM_Core_PseudoConstant
::getLabel($this->getBAOName(), $realField, $fieldValue);
220 return (string) $fieldValue;