Use consistent token syntax for pseudoconstants
At some point we want to have consolidated token code. One thing that is missing at the moment is agreement as to what tokens we are working towards. (this came out of discussion fixing for php8 in https://github.com/civicrm/civicrm-core/pull/20591) I want to constrain this issue to the very narrow question of syntax for pseudoconstants & unique names in tokens.
If we look at the test we can see the current tokens supported by the existing code. A somewhat different set is supported by the TokenProcessor class for contributions
So we can see that in one place you would pass
{contribution.contribution_status_id} to get 'Pending'
and in the other it would be {contribution.status}
We are also 'promoting' (by presenting in the UI selector) {contribution.contribution_source} over {contribution.source} in how we present tokens, even though in this case I think both work.
I would propose that our preferred tokens adhere to apiv4 style conventions as much as possible. Preferring means that we work towards the following (on an ad hoc basis).
- the tokens that are selectable in the UI on the form return the preferred variants
- we support the preferred variants in tested code on both token methods
- we run db update scripts to replace the less preferred with the preferred in the msg_template and action_schedule tables as we feel safe doing so
- we deprecate less preferred variants by adding deprecation notices to places where they are used, when we feel safe doing so.
Proposed conventions
- deprecate unique name prefixing - ie prefer {contribution.source} over {contribution.contribution_source}
- actual field name returns the value of that field - ie {contribution.contribution_status_id} would return a number rather than a string
- we use apiv4 style tokens for labels - ie {contribution.contribution_status_id:label}
(out of scope for this issue = apiv4 style custom field names or custom fields in general, returning calculated values for eg. contribution.check_number)
If we go with the above the specific action I will add to my (long) todo list is to engage with fixing contribution_status_id to make it consistent between the 2 classes and the selector - ie
- Replace the 'advertised' token from
'contribution.contribution_status_id:label' => 'Contribution Status'
'contribution.contribution_status_id:label' => 'Contribution Status' - add tested support for
'contribution.contribution_status_id:label'
to both classes - fix any core message templates to use 'contribution.contribution_status_id:label'
- fix the upgrade script to str_replace 'contribution.contribution_status_id' in the message template table (only)
The other fields in this space that are currently inconsistent are
- financial_type_id, campaign, payment instrument id, cancel_date, source