Support for Drupal 7 is ending on 5 January 2025—it’s time to migrate to Drupal 10! Learn about the many benefits of Drupal 10 and find migration tools in our resource center.Problem/Motivation
The examples in the API documentation for the menu system say that the "machine name" for e.g. a local action should match that for the route. However:
- The API documentation in question doesn't explain what "machine name" means, or is used for, nor do they link to a standard explanation.
- It also doesn't explain why e.g. the menu action machine name should be the same as the route name, and what the consequences are if they're not the same (even if it's "a human reading the YAML might get confused or lose track.")
- The Routing documentation linked to doesn't explain what "machine name" is either.
- The Coding standards don't seem to even mention machine names. If they're discussed in a subpage of the coding standards, it isn't obvious which one (e.g. they're not on Services and extending Symfony.)
Proposed resolution
The API documentation as a whole needs to make clear what "machine name" means, either: with reference other API documentation or a coding standard; or by writing new documentation to clarify.
The API documentation for the menu and routing components (and any other relevant components) needs to make clear why e.g. local action machine names should match route names, and what the consequences are if they don't
Remaining tasks
- Either find existing documentation on "machine name", or:
- Agree on what is and is not a machine name (allowed characters, namespacing, uniqueness etc.)
- Turn that agreement into something easy to read and find a place for it either in Drupal core or on d.o e.g. in the coding standards.
- Link to this documentation from Drupal Core's API documentation wherever "machine name" is used (menu, routing - and anywhere else.)
- Explain in the menu documentation in Drupal Core why e.g. local action machine names must not only conform to the standard for "machine name", but should also match the route name; and explain what happens if they don't match, if anything.
User interface changes
None.
API changes
None.
Data model changes
None.
Comments
Comment #2
cilefen CreditAttribution: cilefen commentedThere is a form element validator.
Comment #3
jp.stacey CreditAttribution: jp.stacey at Magnetic Phield commented@cilefen thanks for hunting that out: it certainly gives us a framework for how to start describing what a machine name *is*!
There's a lot left unspecifieid within the context of just this method, though:
* the replacement character (it says "usually a hyphen", although I'd have gone for an underscore) for - disallowed characters? I note it doesn't do any replacement itself, just checks that the machine name is not just e.g. "-" or "_"
* the disallowed characters (a pattern can be passed in)
So maybe the phrase "machine name" is context-sensitive, and the docs should instead talk about "YAML machine names" or even "Routing YAML machine names"? I'll dig further and see what code is specifically checking the validation in the context of this particular documentation bug.
Comment #4
jp.stacey CreditAttribution: jp.stacey at Magnetic Phield commentedThere appears to be no validation of the machine name (basically
$plugin_id) in\Drupal\Core\Menu\LocalTaskManager#processDefinition().I added weird characters to my own example
.links.task.ymlkeys, to try to fire some kind of error: one key ended up including whitespace and punctuation:test.sub_page_ !"$£$^%^*&^()task.I then ran a
drush cr, added avar_dumpinprocessDefinition(), and refreshed the page.Result? a load of YAML keys dumped out, including my wacky one above: and no errors. The particular task with the weird key showed up just fine as a tab.
This suggests that, even though the docs specify machine names for YAML keys, the format is not mandatory. So where do we go from here? :)
Comment #5
jp.stacey CreditAttribution: jp.stacey at Magnetic Phield commentedComment #6
jp.stacey CreditAttribution: jp.stacey at Magnetic Phield commentedAnother link that @ekes has unearthed:
https://www.drupal.org/docs/7/understanding-drupal/glossary#machine-name
However (a) it's a pretty empty definition when it comes to giving newbies guidance and (b) it doesn't help explain the contextualness of different naming guidelines e.g. why module names shouldn't have dots in them, but route names can and indeed should (dots being an informal namespace separator.)
Ideally we could do with something as unambiguous as we have for nodes or views....
Comment #7
joachim CreditAttribution: joachim as a volunteer commentedIn D7 at least, a machine name was something matching /[a-z0-9_]+/, possibly with the additional condition that it not start with a number.
I would be inclined to say that is still true in D8, and that routes have names, not machine names, and configuration has keys, not machine names. (And that those terms need to be clearly explained too.)
It would be interesting to see which uses of that validator allow a hyphen.