Migrating an existing website running Drupal into a Composer-managed build requires you build a composer.json file including all the required packages for your website.

The structure of your repository should shift as follows:

The key differences include the new top-level composer.json and composer.lock files, and the top-level location of the vendor directory.

Before you start

To compare Composer changes, Acquia recommends you start with a website generally structured the way you want the website built.

• Contributed modules: Drupal best practice is to place contributed modules in docroot/modules/contrib. If your modules are not in docroot/modules/contrib, consider moving all contributed modules to the specified location.
• Custom modules: Drupal best practice is to place custom modules in docroot/modules/custom. If your modules are not in docroot/modules/custom, consider moving all custom modules to the specified location.
• Themes: Drupal best practice is to reflect the same custom/contrib structure for themes as for modules. Each one of the changes may require you to run drush cr to ensure your Drupal website knows the new module/theme location. Acquia recommends you run drush cr first to reduce potential complications migrating to Composer.

• Custom code: If you have made any modifications to Drupal core files or contributed module files, you must create patches for the files, and store them in a top level patches/ directory. The composer update command will overwrite all core and contributed module files, but the command applies patches after an update is applied. Creating the patches now will save you trouble later.

  If you have modified the composer.json file located at docroot/composer.json, you must make a note of the modifications as the composer update command overwrites the composer.json file. After the composer update command completes execution, add your requirements to the top-level composer.json file.

All the changes should be committed, tagged, and, if possible, merged to master: your new, permanent, file structure.

Procedure

• Create a development branch containing your composer.json file. Do not create a development branch on master. The branch should contain all code required to work on production.

• Secure a working template for you to use as reference. Acquia recommends that you use the following template:

  https://github.com/acquia/acquia-ra-composer/blob/master/composer.json

• Save the file at the top level of your repository: repo/composer.json.

  Note

  The instructions in the procedure are based on the linked composer.json file.

• To simplify the migration, Acquia strongly recommends you install the exact version of Drupal and all contributed modules already running on your website.

  To pin the module to a specific version, open your composer.json file, and then edit the require section based on the following:

  copy

  "require": {
      "drupal/core-composer-scaffold": "^9.2",
      "composer/installers": "^1.0"
  },

  • Drupal core: Require Drupal core by changing "drupal/core-recommended": "^<major-version>.<minor-version>", to your , for example, . Specifying the entire version is called a package. Pinning has the advantage of ensuring a specific version is installed, but pinning also prevents using the command for updates. a module after Composer migration testing is complete.

  "extra": {
    "drupal-scaffold": {
        "locations": {
            "web-root": "./docroot"
        },
     ...
    }
}

return require __DIR__ . '/../vendor/autoload.php';

• Test your now-working website by using git diff to compare directories or particular files. Pinned modules or core files (except autoload.php) will display little differences. The entire vendor directory has moved, and the packages in the vendor directory are different as there may be a more recent version than the version on your existing website. The changes are fine as the module itself is the same. Ensure you check all parts of your Drupal website, noting if you must run drush cr, or if modules are missing.
• Continue to delete, change the composer.json file, and install until your website is fully working.

• Whenever your website is ready, you should commit the composer.json changes, composer.lock, and all generated code. Remember you are committing pinned versions of your modules ensuring composer installs the exact versions running on your existing website. Your next step, either in the existing branch, or after the existing branch has been tested and merged to master, is to change all the versioning in the require section to use the caret (^), and more open versioning:

  copy

  "require": {
      "drupal/core-composer-scaffold": "^9.2",
      "drupal/core-recommended": "^9.2",
      "drupal/admin_toolbar": "^1.1",
      "drupal/ctools": "^3.0",
      "drupal/pathauto": "^1.0",
      "drupal/token": "^1.0",
      "drupal/zurb_foundation": "^6.x",
      "composer/installers": "^1.0"
  },

If you run composer update drupal/core-recommended --with-dependencies, Composer updates your website to the latest version. Ensure that you pin your website to a version after you test the migration with the pinned version.

Migrating a Drupal website into a Composer-managed build

Migrating an existing website running Drupal into a Composer-managed build requires you build a composer.json file including all the required packages for your website.

The structure of your repository should shift as follows:

The key differences include the new top-level composer.json and composer.lock files, and the top-level location of the vendor directory.

Before you start

To compare Composer changes, Acquia recommends you start with a website generally structured the way you want the website built.

Note

In a Drupal application that uses the Drupal recommended project, the default web root is docroot/. This is the standard for running a Drupal application on Cloud Platform. For more information, see https://github.com/acquia/drupal-recommended-project/blob/master/composer.json#L75.

• Contributed modules: Drupal best practice is to place contributed modules in docroot/modules/contrib. If your modules are not in docroot/modules/contrib, consider moving all contributed modules to the specified location.
• Custom modules: Drupal best practice is to place custom modules in docroot/modules/custom. If your modules are not in docroot/modules/custom, consider moving all custom modules to the specified location.
• Themes: Drupal best practice is to reflect the same custom/contrib structure for themes as for modules. Each one of the changes may require you to run drush cr to ensure your Drupal website knows the new module/theme location. Acquia recommends you run drush cr first to reduce potential complications migrating to Composer.

• Custom code: If you have made any modifications to Drupal core files or contributed module files, you must create patches for the files, and store them in a top level patches/ directory. The composer update command will overwrite all core and contributed module files, but the command applies patches after an update is applied. Creating the patches now will save you trouble later.

  If you have modified the composer.json file located at docroot/composer.json, you must make a note of the modifications as the composer update command overwrites the composer.json file. After the composer update command completes execution, add your requirements to the top-level composer.json file.

All the changes should be committed, tagged, and, if possible, merged to master: your new, permanent, file structure.

Procedure

• Create a development branch containing your composer.json file. Do not create a development branch on master. The branch should contain all code required to work on production.

• Secure a working template for you to use as reference. Acquia recommends that you use the following template:

  https://github.com/acquia/acquia-ra-composer/blob/master/composer.json

• Save the file at the top level of your repository: repo/composer.json.

  Note

  The instructions in the procedure are based on the linked composer.json file.

• To simplify the migration, Acquia strongly recommends you install the exact version of Drupal and all contributed modules already running on your website.

  To pin the module to a specific version, open your composer.json file, and then edit the require section based on the following:

  copy

  "require": {
      "drupal/core-composer-scaffold": "^9.2",
      "composer/installers": "^1.0"
  },

  • Drupal core: Require Drupal core by changing "drupal/core-recommended": "^<major-version>.<minor-version>", to your , for example, . Specifying the entire version is called a package. Pinning has the advantage of ensuring a specific version is installed, but pinning also prevents using the command for updates. a module after Composer migration testing is complete.

Important

The top-level composer.json in turn must define where the web root is located. It does so via the locations mapping, as shown below:

copy

  "extra": {
    "drupal-scaffold": {
        "locations": {
            "web-root": "./docroot"
        },
     ...
    }
}

 

Note

If you have an existing docroot/autoload.php, you can delete or manually modify the following path in docroot/autoload.php so that it looks like the following:

copy

return require __DIR__ . '/../vendor/autoload.php';

 

• Test your now-working website by using git diff to compare directories or particular files. Pinned modules or core files (except autoload.php) will display little differences. The entire vendor directory has moved, and the packages in the vendor directory are different as there may be a more recent version than the version on your existing website. The changes are fine as the module itself is the same. Ensure you check all parts of your Drupal website, noting if you must run drush cr, or if modules are missing.
• Continue to delete, change the composer.json file, and install until your website is fully working.

• Whenever your website is ready, you should commit the composer.json changes, composer.lock, and all generated code. Remember you are committing pinned versions of your modules ensuring composer installs the exact versions running on your existing website. Your next step, either in the existing branch, or after the existing branch has been tested and merged to master, is to change all the versioning in the require section to use the caret (^), and more open versioning:

  copy

  "require": {
      "drupal/core-composer-scaffold": "^9.2",
      "drupal/core-recommended": "^9.2",
      "drupal/admin_toolbar": "^1.1",
      "drupal/ctools": "^3.0",
      "drupal/pathauto": "^1.0",
      "drupal/token": "^1.0",
      "drupal/zurb_foundation": "^6.x",
      "composer/installers": "^1.0"
  },

If you run composer update drupal/core-recommended --with-dependencies, Composer updates your website to the latest version. Ensure that you pin your website to a version after you test the migration with the pinned version.

If you use multisites, inspect all multisites to ensure your contributed module list is complete. Results should display similarly to the following:

Add each module and theme to the require section. Using the previous example, your require section should display like the following:

To generate a list of installed modules preformatted for Composer:

• Install and enable the composerize module in a development version of your site.
• Go to admin/reports/composerize/ on your site.

Copy the list of dependencies from the require section of composer.json on the page. Paste the list of modules into the require section of your composer.json template.

• Module paths: Requiring composer/installers allows you to specify, in the extras section, where composer should download packages of a particular type:

Drupal best practice recommends placing contributed modules in docroot/modules/contrib. Your current branch should already reflect the decision you made before starting the migration process. If your modules are not in docroot/modules/contrib, you must change the installer path by removing /contrib.

• Libraries: If contributed modules require manually adding libraries (for example, the module does not use a composer.json file to download its required libraries), you may add the libraries directly to your require section. For an example, see enyo/dropzone in both the require section, and in the installer-paths section of the following template:

  https://github.com/acquia/acquia-ra-composer/blob/master/composer-templates/composer-libraries.json

• Custom modules and themes: The following methods handle custom modules and themes:
  • Circumvent Composer entirely, and directly commit your custom modules and themes to your repository.
  • Create your custom modules, and themes as Composer packages, ensure Composer downloads them, and then include the custom modules, and themes as you would other packages.

Circumventing Composer is easier than creating Composer packages, but if more than one Composer-built website uses your theme or module, creating your custom code as discrete Composer packages may be more efficient and developer-friendly.

In either case, custom code should live in demarcated custom directories:

Custom directories allow you to delete the contributed themes and modules by deleting the parent contributed directory entirely, and allowing Composer to rebuild the contributed directory from scratch.

If you use multisites, inspect all multisites to ensure your contributed module list is complete. Results should display similarly to the following:

Add each module and theme to the require section. Using the previous example, your require section should display like the following:

To generate a list of installed modules preformatted for Composer:

• Install and enable the composerize module in a development version of your site.
• Go to admin/reports/composerize/ on your site.

Copy the list of dependencies from the require section of composer.json on the page. Paste the list of modules into the require section of your composer.json template.

• Module paths: Requiring composer/installers allows you to specify, in the extras section, where composer should download packages of a particular type:

Drupal best practice recommends placing contributed modules in docroot/modules/contrib. Your current branch should already reflect the decision you made before starting the migration process. If your modules are not in docroot/modules/contrib, you must change the installer path by removing /contrib.

• Libraries: If contributed modules require manually adding libraries (for example, the module does not use a composer.json file to download its required libraries), you may add the libraries directly to your require section. For an example, see enyo/dropzone in both the require section, and in the installer-paths section of the following template:

  https://github.com/acquia/acquia-ra-composer/blob/master/composer-templates/composer-libraries.json

• Custom modules and themes: The following methods handle custom modules and themes:
  • Circumvent Composer entirely, and directly commit your custom modules and themes to your repository.
  • Create your custom modules, and themes as Composer packages, ensure Composer downloads them, and then include the custom modules, and themes as you would other packages.

Circumventing Composer is easier than creating Composer packages, but if more than one Composer-built website uses your theme or module, creating your custom code as discrete Composer packages may be more efficient and developer-friendly.

In either case, custom code should live in demarcated custom directories:

Custom directories allow you to delete the contributed themes and modules by deleting the parent contributed directory entirely, and allowing Composer to rebuild the contributed directory from scratch.