The 2026 Drupal Business Survey is open. Your response will help shape the future of the Drupal business ecosystem.Some tokens use underscores, some use hyphens. How do I know which one to use? Can we standardize on the syntax for token names throughout core so contrib can follow?
| Comment | File | Size | Author |
|---|---|---|---|
| tokens.png | 205.14 KB | jenlampton |
Comments
Comment #1
dave reidThe standard for tokens that are hard-coded (tokens that we can define explicity) is to use dashes. But the ones that use underscores are dynamic and actual field machine names (provided by Token module). We will have the same debate with #1173706: Date tokens do not handle all date types. While it would be nice to always use dashes, I don't think it is a good idea to modify machine names, especially with regards to code complexity to have to convert the tokens back when replacing.
So in summary: core provides a sane standard of using dashes only because it is able to define all of its tokens and it doesn't have to handle dynamic tokens.
Comment #2
dave reidWe also have a similar problem in core: we use an entity type 'taxonomy_term' but (in)conveniently used the token type 'term'. We're going to run into this problem with other entity types as well but at least those are easier to support.
Comment #3
jenlamptonWouldn't it be easier to standardize on underscores? (and fix the taxonomy token so it is called taxonomy_term)
Comment #5
jenlamptontagging for learnability.
Comment #6
dave reidThe problem here is that core has already standardized on the usage of dashes, but things like machine names use underscores. Dashes look nicer. Either way something has to 'transform' for the sake of unity. Contrib should be using dashes wherever possible as set by the core standard.
Comment #7
gregglesI agree hyphens are better than underscores. Seems like this will require changing machine names to hyphens.
Either way it's a string change which means 8.x first (and 7.x second, if ever).
Comment #8
jenlamptonSee #1353064: Standardize on use of underscore vs hyphen in machine names for standardizing on machine name syntax.
Comment #8.0
killes@www.drop.org commentedmake image less large
Comment #17
larowlanComment #18
amber himes matzThis issue appears to be a duplicate of #1353064: Standardize on use of underscore vs hyphen in machine names (which is closed). However, in that issue, there are a few comments that point out that the Menu system still uses hyphens (and not underscores) and thus argue that the issue should be re-opened. This was addressed outside of the Drupal issue queue in the following Drupal StackExchange, where @berdir points out in the top-rated comment:
So for that reason, I'm closing this as "Closed (won't fix)".
FYI, the relevant file where the menu form provides the exception to the default underscores replacement rule is:
core/modules/menu_ui/src/MenuForm.php, line 122.
And the default behavior for machine names (in which token names are derived from I believe) is:
core/lib/Drupal/Core/Render/Element/MachineName.php, lines 248-250.
Thanks to @daravanen in the Drupal Slack #contribute channel for pointing this issue out.