If you've been following the Audit module for DruScan, you might have noticed something odd when installing it via Composer. Instead of the clean drupal/audit you'd expect, the package was called drupal/audit-audit. Not exactly elegant. Here's why that happened and how I got it fixed.
How Composer Namespaces Work in Drupal
When you publish a module on drupal.org and it gets added to the Composer endpoint at packages.drupal.org, it automatically gets a namespace in the format drupal/project-name. So if your project is called audit, your Composer package should be drupal/audit. Simple.
The problem is that Drupal doesn't just register top-level projects. It also registers submodules. If a contributed module has a submodule inside it, that submodule gets its own Composer namespace too. And here's where things get messy: the namespace is based on the submodule's machine name, not the parent project's name.
So if someone creates a project called fancy_tools and inside it puts a submodule called audit, that submodule grabs the drupal/audit namespace. First come, first served.
What Happened with the Audit Module
That's exactly what happened here. There's a project on drupal.org called audit_custom. It was created back in 2017 and has a submodule inside it that's simply called audit. That submodule registered the drupal/audit namespace before the actual drupal/project/audit project existed on the Composer endpoint.
When I took over the Audit project and started developing it as the core module for DruScan, I found that my project was assigned drupal/audit-audit instead of drupal/audit. The system detected the conflict and appended the project name with a hyphen followed by the module name to avoid the collision.
Running composer show drupal/audit --all showed something that clearly wasn't my module. The description was in Chinese characters (审批模型), the homepage pointed to audit_custom, and it was a metapackage with no actual code distribution. Not ideal.
Why This Was a Problem
Beyond the aesthetics of having a duplicated name, this created real confusion:
- Documentation had to explain that
composer require drupal/audit-auditwas the correct command, which looks like a typo. - Anyone searching for
drupal/auditon Packagist would find the wrong module. - The installation instructions felt unprofessional for something I'm building as a serious product.
Filing the Namespace Request
Drupal.org has a process for handling these conflicts through the packages.drupal.org issue queue. I filed a request explaining the situation and asking for the namespace to be reassigned.
The case was pretty clear-cut. The audit_custom project is marked as "Seeking new maintainer" (basically abandoned), has zero reported installations, and isn't even covered by Drupal's security advisory policy. On top of that, Drupal's own Composer naming conventions state that in case of namespace conflicts, projects take precedence over submodules.
After some back and forth — the namespace request queue isn't exactly the fastest lane on drupal.org — the team approved the change.
What This Means Now
The Audit module now lives where it should: drupal/audit. Installing it is as clean as it gets:
composer require drupal/audit
No more double name. No more confused looks when people read the installation instructions.
I've already updated the module's documentation on drupal.org and the DruScan landing page to reflect the new namespace. If you installed the module before the change using drupal/audit-audit, you'll want to update your composer.json accordingly.
Lessons Learned
This whole experience taught me something about the Drupal ecosystem that isn't well documented: when you create a new module, check if any existing project already has a submodule with your machine name. You can do this by running composer show drupal/your-module-name --all against the Drupal Packagist endpoint before you even start.
If you find a conflict, file the namespace request early. It takes time. And make sure your case is solid — having an active, maintained project with a clear roadmap definitely helps when asking the infrastructure team to reassign a namespace.
One more thing off the checklist. Back to building.