Composer package naming conventions

Last updated on
20 September 2016

This is WIP documentation for #2401519: [policy] Decide on Composer Package Names.


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

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.

Drupal (Sub-)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 wont 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

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.

Examples

  • Datetime becomes drupal/core-datetime
  • Diff becomes drupal/core-diff
  • This also allows contrib to expose components like so: drupal/panels-renderer or drupal/ds-builder