Problem/Motivation

All systemic changes in code have a standard way of communicating those changes to developers in a timely fashion to allow them to make changes to their customisations to support those changes.

Right now, if a token is changed there is absolutely no way to notify site-builders and other users of the token system.

Steps to reproduce

N/A

Proposed resolution

In order to make systemic changes possible in the world of tokens we need a communication channel to site-builders and users to indicate when tokens are flagged to become obsolete.

Even better would be an interactive UI to guide replacement of deprecated tokens, perhaps even facilitate automatic replacement where possible, and parallel drush commands.

Remaining tasks

Discuss and decide upon an approach

User interface changes

A new UI for managing tokens in-content?

API changes

Probably new public methods (maybe new service?) for managing tokens.

Data model changes

None foreseen at this time.

Release notes snippet

Comments

darvanen created an issue. See original summary.

andypost’s picture

andypost
he/him
Primary language Russian
commented
Related issues: +#2233353: Convert Token API into plugins, +#1222592: Architecture RFC: Field token architecture
andypost’s picture

andypost
he/him
Primary language Russian
commented
Related issues: +#514990: Add a UI for browsing tokens
berdir’s picture

berdir
Primary language German
Location Switzerland
commented

Quick thoughts:

* Unlike API changes, this is something that needs to reach site builders as you wrote, so I guess non-suppressed watchdog warnings or so. This could happen _a lot_ though. And we have fairly little context to go by.
* We currently don't require the token info for many cases of token replacements, that will likely be quite a performance hit if we need to fetch info on deprecated tokens. Maybe optimized cache entries just for a list of deprecated tokens or something.
* There are also token types to think about, for example to rename term to taxonomy_term to get it back in sync with the entity type ID, we'd also want an alias system then.
* a bulk update system seems extremely complex and very likely way out of scope here. We have no knowledge where tokens are stored.

darvanen’s picture

darvanen
he/him
Primary language English
Location Sydney, Australia
commented

#4:

  1. You're talking about warning when attempting to replace a deprecated token? I can see that working.
  2. Why would we need the token info? I was thinking more along the lines of replacing the text "[node:title]" with "[node:label]" where it exists. And where one for one replacement isn't possible, leave it to the user.
  3. Agree
  4. We have *some* knowledge of where tokens are regularly stored (config, fields), why not start with those and have a plugin template for people to contribute more locations? - I agree it's a massive undertaking and I thought perhaps it would be better as a contrib module, but as tokens are so ubiquitous I don't know how much value a deprecation system will have without some form of UI to guide users - and if we're attempting to locate tokens for a UI, it's a pretty small step to auto-replace if we've got a map.
berdir’s picture

berdir
Primary language German
Location Switzerland
commented

2. We need to know that node:title is deprecated. And the obvious place to put that information would be on the token info declaration. So that it would be declarative, like deprecated services or config schema. The actual implementation could manually trigger a deprecation message, but that will only work for tokens, not token types. And if we have no declarative system then we definitely can't do any automated replacements.
4. Core doesn't actually have that many places where it supports tokens. Many are only added by contrib modules. IMHO this is clearly something for a contrib module to experiment on. It will need some kind of batch system, I'm not sure if it really should blindly replace everything in config that looks like a token, we'll have to experiment with that. We have no efficient way to query something like this across all config, we'd either need to load config directly from storage as a string or traverse it property-by-property.

darvanen’s picture

darvanen
he/him
Primary language English
Location Sydney, Australia
commented

First, pardon the dumb question, I think I may have finally put my finger on this but what is a token type as distinct from a token? Are they respectively the first and second parts of [node:title] for instance?

2. If we're worried about a performance hit perhaps there's a way we can cache the deprecations for runtime?
4. Ok. So without any kind of GUI it's up to the user to react to the watchdog/error messages as the default and then install a module if one is created? Makes sense to me. Makes this task a lot smaller too.

Version: 9.3.x-dev » 9.4.x-dev

Drupal 9.3.0-rc1 was released on November 26, 2021, which means new developments and disruptive changes should now be targeted for the 9.4.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 9.4.x-dev » 9.5.x-dev

Drupal 9.4.0-alpha1 was released on May 6, 2022, which means new developments and disruptive changes should now be targeted for the 9.5.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 9.5.x-dev » 10.1.x-dev

Drupal 9.5.0-beta2 and Drupal 10.0.0-beta2 were released on September 29, 2022, which means new developments and disruptive changes should now be targeted for the 10.1.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 10.1.x-dev » 11.x-dev

Drupal core is moving towards using a “main” branch. As an interim step, a new 11.x branch has been opened, as Drupal.org infrastructure cannot currently fully support a branch named main. New developments and disruptive changes should now be targeted for the 11.x branch, which currently accepts only minor-version allowed changes. For more information, see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 11.x-dev » main

Drupal core is now using the main branch as the primary development branch. New developments and disruptive changes should now be targeted to the main branch.

Read more in the announcement.