Using packages.drupal.org

Last updated on
8 May 2017

Background

By default, Composer uses Packagist.org to discover packages. Packagist.org is a repository of metadata about PHP and PHP-related projects. 

Drupal projects are not listed on Packagist. Instead, Drupal.org provides its own repository of composer metadata for Drupal projects.

Using packages.drupal.org

To learn how you can use Composer (and Drupal.org Packagist) see Using Composer to manage Drupal site dependencies. For packages.drupal.org configuration in particular, see Define Drupal.org as the source of drupal packages

Converting your project from packagist.drupal-composer.org to the official packages.drupal.org service

If you originally built your project using the packagist.drupal-composer.org service, you will need to convert it to use the new official service.

Updating the Endpoints in your composer.json #

The first thing you need to do is to add the appropriate Drupal.org composer repository to your composer.json. Remember that Drupal.org provides separate endpoints for each Platform version of Drupal. For Drupal 7 use https://packages.drupal.org/7. For Drupal 8, use https://packages.drupal.org/8.
If your composer.json already has a repositories link that points to https://packagist.drupal-composer.org, and does not have additional repositories in it, then you can run the following command on the command line to replace it:
composer config repositories.0 composer https://packages.drupal.org/8

Your composer.json repository section should end up looking like this:

{
    "repositories": [
        {
            "type": "composer",
            "url": "https://packages.drupal.org/8"
        }
    ]
}

At the same time, you will likely want to remove the Drupal Packagist composer repository.

Updating the versions of your declared dependencies #

When using Drupal Packagist - the semver shim format was: Platform(D7/D8).Major.Minor. So for example, the following code required Views 7.x 3.13 through Drupal Packagist:

{
    "require": {
        "drupal/views": "7.3.13"
    }
}

When using the official packages.drupal.org service, the platform part of the version is already defined by whether you are using the Drupal 7 or Drupal 8 endpoint, therefore the rest of the translated format is as follows: Major.Minor.0

{
    "require": {
        "drupal/views": "3.13.*"
    }
}

To convert to the new format, you should update your require statements appropriately in your composer.json and either rebuild your composer.lock file, or manually edit it.

Features not yet supported

  • Drupal does not yet have a sub-tree split - installing Drupal with composer will install the full package, same as you would receive from the tarball.
  • In the same vein, sub-components of Drupal core cannot be separately installed with Composer (such as the plugin manager).
  • Distributions and install profiles are not yet supported.
  • Drush extensions are not yet supported.

Troubleshooting

What to do if you suspect packages.drupal.org is causing an issue

The Drupal.org composer services work by generating static files with the metadata for the project translated for Composer. These static files are updated every time meta data about the package changes. If you know that information about a project has changed, but Composer is still getting the old information that may indicate a problem with the cache invalidation of these static files, or with packaging itself.

You can open an issue in the packages.drupal.org (project_composer) issue queue.

What to do if Composer is failing to recognize the Drupal project you have required in your Composer.json

First, make sure that you are using the right endpoint for the major version of Drupal Core that the project you are trying to include is for. Contributed projects for Drupal 8 will only be accessible on the Drupal 8 endpoint, and the same for Drupal 7

Second, check the require format you are using to require the project, using the examples above. Double check that you are using the suggested format. Eventually, the Project page will display the Composer require line that should be added to your Composer.json file, but that feature is still under development.

What if there is a namespace collision between two modules in different Projects?

There can be issues with conflicting module names on Drupal.org. While Projects themselves must have unique names, the modules within projects do not have to be unique.

This kind of namespace collision most often occurs when a module is either moved into or out of core. One example of this is CKEditor, which has been moved into core.

This problem can be much more prevalent with themes, as many theme projects have a subtheme that is simply named default.

Whenever a collision does occur, the most popular module will be defaulted to for that namespace, and the other colliders will be given a new namespace of the format: project_modulename. For example: drupal/link-link for the link module.