Composer package naming conventions
With Drupal adopting Composer as dependency manager, the community has to follow a naming convention for composer package names to avoid conflicts.
How you define your own package with a composer.json can be found in Add a composer.json file to define your module as a PHP package.
In general, Composer only allows for package names like so: vendor/project. You cannot use more than two levels. This leads to the following conventions.
Drupal Projects
Any project hosted on drupal.org is considered a Drupal Project. This contains Drupal core, modules, themes, profiles, …. Drupal already has an existing namespace for these based on the project URL https://www.drupal.org/project/PROJECT.
Convention
Projects must use the package name:
drupal/PROJECT
where PROJECT is the part from the URL.
Examples
- Drupal is a project: https://www.drupal.org/project/drupal →
drupal/drupal - ctools is a contrib project: https://www.drupal.org/project/ctools →
drupal/ctools - Views in Drupal 7 is a contrib project: https://www.drupal.org/project/views →
drupal/views - Core is a subtree of Drupal: https://www.drupal.org/project/core →
drupal/core - Datetime is a module within Drupal Core: https://www.drupal.org/project/datetime →
drupal/datetime
Some project URLs are not accessible or point to another project, as they are reserved names. In most cases those are sub-modules or sub-themes of existing projects, like Drupal core.
Modules, Themes and Profiles
Multiple modules, themes and profiles might be part of a single Drupal project, for example system, node, standard in Drupal or page_manager, views_content in ctools. As Drupal won't let you run two modules with the same name, modules, themes, profiles and Drupal projects share the same namespace.
Convention
Sub-modules, -themes and profiles must use the package name.
drupal/SUBPROJECT
where SUBPROJECT is the machine name of the module, theme or profile.
This will not conflict with drupal/PROJECT, as Project names share the same namespace with modules, themes and profiles due to the way Drupal works.
Over time, some projects may merge into or were split from another project. For example Views was merged into Drupal 8 or Page Manager was separated from ctools for a Drupal 8 release. Because of different version numbers, these cases can be resolved by utilizing Composer's replace property and/or using different composer repositories.
In the case naming conflicts cannot be resolved, Drupal Projects shall take precedence over (sub-)modules, themes and profiles.
For avoiding dependency issues, Drupal projects declaring their own composer.json, should also add their submodules and -themes to the replace-section.
Examples
- Module
devel_generatefrom Devel →drupal/devel_generate - Drupal 8 core's Views module can be specified as
drupal/views, but the dependency will be resolved as a contrib replacement bydrupal/core.
Based on this convention, meta-packages or subtree-splits could be provided for every module, theme and profile.
Components
Drupal projects may also contain custom components (like PHP libraries). As those components are not bound to any namespace, they are likely to conflict with a given Drupal project, module, theme, etc..
Convention
Package names must be prefixed with their parent's name and a dash (-), in the case it will use the drupal/ vendor:
drupal/PARENT-COMPONENT
where PARENT is the name of the parent package and COMPONENT a sufficient name for the component.
Since the - (dash) is not used in the existing drupal namespace, it shouldn't conflict in anyway to what is currently in Drupal.