Come together with the global Drupal community in Rotterdam, 28 Sept – 1 Oct 2026. Sessions, contribution, connection, and Early Bird savings until 8 June.Problem/Motivation
There is no documentation or specification about the valid character set or maximum length for a plugin ID.
The api.d.o topic just speaks of "a unique string identifier". (Which doesn't even explain in which domain it has to be unique.)
Proposed resolution
[a-zA-Z0-9_-]+
(alphanumeric, underscore, hyphen)
Remaining tasks
Decide if this is adequate
Document it!
User interface changes
N/A
API changes
Depends on if it is enforced or only documented
Data model changes
N/A
Comments
Comment #2
jhodgdonGood question. Let's put this into the plugin system component for now to see if we can get an answer. For the moment assigning to tim.plunkett, one of the plugin system maintainers.
Comment #3
xanoThe plugin system only required plugin IDs to be strings. However, you are advised to make sure all IDs are valid machine names (alphanumeric, plus underscores). Note that plugin IDs contain colons when you use core's derivative decorators. This means that such plugin IDs cannot be used as config IDs, for instance, as those are used as filenames and those cannot contain colons.
Comment #4
drunken monkeyI know, sorry, I didn't make that quite clear: I meant that colons would probably cause problems in normal, "underived" plugin IDs since they'd then be mistaken for derived ones.
Anyways, thanks for answering! So should we maybe make "alphanumeric plus underscores" a requirement? (Plus colons only for derived ones.) What exactly would or might break with other IDs? And, are IDs starting with numbers or underscores fine, too?
Also, if we want to document this, where should it be documented? In the api.d.o topic?
Comment #5
cilefen commentedIs this something we should throw an exception about in addition to documenting?
Comment #6
tim.plunkettYes, colons should only be in derivatives.
We could document this as matching the rules for function names, variables, and "other labels":
Comment #7
tim.plunkettStill following, just unassigning
Comment #8
drunken monkeyWe currently have the problem in Facets and Search API that we want to create plugins (type A) based on plugins of a different type (type B). The "natural" way would be to use the plugin IDs from type B as the second part of the plugin IDs for type A. But if the plugins from type B are already derivatives, that would make the plugin IDs contain two colons.
Would that cause problems (if the base plugin ID doesn't contain any colon), or should that still be avoided?
In the latter case, does anyone know of a clever way to implement this without that risk?
Comment #10
drunken monkeyI just noticed that the block plugins created by Views do not follow the normal machine name format, since they contain a dash (-) between view ID and display ID.
So, if we'd decide that plugin IDs need to be valid machine names (except for a single colon for derived ones), Views would violate that rule (currently).
Comment #14
tim.plunkettUpdating the IS with a concrete proposal
Comment #15
drunken monkeyDo we really want to allow uppercase characters? Seems that could potentially make problems with MySQL (which ignores case by default).
Identifiers are usually also forbidden from starting with a digit (or be digits-only) – could also be a problem.
Allowing dashes is unexpected, but I don't see why it would cause problems. (Could even open up possibilities for the problem I mention in #8: If we define display plugin IDs in the Search API as not allowing dashes, we can just replace colons with dashes when re-using them as derivative IDs in Facets. Not sure if that would be clear enough, but still.)
Finally, this would obviously just cover the base ID and derivative ID in the case of a derived plugin – we'd need to document this clearly (if people deal with plugins generically, they have to take into account that IDs can contain a single colon), but it of course makes sense.
My suggestion:
[a-z_][a-z_0-9-]*I.e.:
- lowercase only
- has to start with letter or underscore
Comment #17
cilefen commented#2920682: Add config validation for plugin IDs
Comment #18
jayelless commentedThe use of plugin id strings containing uppercase, spaces or special chars is causing an issue for ultimate_cron - see #2968661: Queue names can contain special characters.
Comment #19
jayelless commentedComment #20
joachim commented> [a-z_][a-z_0-9-]*
This allows hyphens AFAICT.
Are there any cases where a form ID is derived from a plugin ID? If that's the case, then a hyphen would break form alter hooks.
We also have quite a few plugins in core that would violate the lowercase rule, e.g.:
AFAICT the plugins with uppercase IDs are all either Constraint or Archiver plugins.
We can't change plugin names because of BC, so we'd need to devise a way to allow some plugin managers to opt out of the ID format validation.
Comment #21
jayelless commentedThere are plugins in some contrib modules that violate the "machine_name standards". For instance the SendGrid integration module has a queue worker with an id of "SendGridResendQueue". Also as a test case, I have created a queue worker with an id of "Testbed Queue: #1" which works perfectly well under the core queue subsystem.
Comment #23
chi commentedI propose the documentation also suggests prefixing the plugin ID with module machine name to avoid ID clashing.
Comment #24
drunken monkeyAh, yes, definitely!
This should really just be defined for any global identifiers, but apparently we currently list all types individually.
Comment #32
pwolanin commentedLooks like a bit of a stale issue?
We already use "." in custom code, and I think some other chars like "+", "|", "/", etc. could be semantically useful, especially for building up combined IDs.
Comment #35
dydave commentedJust wanted to mention the use of the slash character
'/'in plugin IDs can cause issues when rendering URLs with the plugin ID, see related issue #3426088: InvalidParameterException: Parameter "queueName" for route "queue_ui.inspect" must match "[^/]++" ("queue_unique/mymodule_entity_update" given) to generate a corresponding URL, where naming a queue with the plugin ID prefixed with'queue_unique/'ends up breaking contrib module Queue UI when it tries generating path withpath: admin/config/system/queue-ui/inspect/{queueName}.The suggestion at #15 certainly makes sense and would help preventing these types of issues.
Thanks in advance for your help and feedbacks !
Comment #36
mxr576What about the maximum length of a plugin id?
Comment #37
mxr576IMO it would be awesome if the plugin class's FQCN could be used as a plugin id because the id is just one additional magic string that you have to remember or should not forget updating if you change it in source. But that is not possible currently, the idea falling apart here and there...
Comment #38
mxr576Opened #3440178: Support FQCN as plugin id and reported #3440170: Forked DocParser incorrectly parses ::class notations.