Migrating a Drupal website into a Composer-managed build

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¶

1. 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.

2. 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

3. 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.

4. 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 current Drupal version, for example, "drupal/core-recommended": "<major-version>.<minor-version>.<patch>". Specifying the entire version is called pinning a package. Pinning has the advantage of ensuring a specific version is installed, but pinning also prevents using the composer update drupal/core-recommended --with-dependencies command for updates. Unpin a module after Composer migration testing is complete.
   • Contributed modules: All modules required to run your website on production should be listed in the require section. Start with contributed modules.

     Generate a list of all enabled contributed modules, which you can do with the following Drush command:
   copy

   drush pml --status=Enabled --no-core
   

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

   Package	Name	Type
   Administration	Admin Toolbar (admin_toolbar)	Module
   Chaos tool suite	Chaos tools (ctools)	Module
   Other	Pathauto (pathauto)	Module
   Other	Token (token)	Module
   Other	MTM Foundation (mtm_foundation)	Theme
   Other	ZURB Foundation (zurb_foundation)	Theme

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

   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"
   },
   

   To generate a list of installed modules preformatted for Composer:

   1. Install and enable the composerize module in a development version of your site.
   2. 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:
   copy

   "extra": {
       "installer-paths": {
           "docroot/core": ["type:drupal-core"],
           "docroot/modules/contrib/{$name}": ["type:drupal-module"],
           "docroot/profiles/contrib/{$name}": ["type:drupal-profile"],
           "docroot/themes/contrib/{$name}": ["type:drupal-theme"],
           "docroot/libraries/{$name}": ["type:drupal-library"]
       }
   }
   

   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:

   copy

   docroot/modules/custom
   docroot/themes/custom
   

   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.

5. Delete the following directories (including both the directories’ contents and the directories themselves):

   copy

   docroot/core
   docroot/modules/contrib
   docroot/themes/contrib
   docroot/vendor
   

6. Run the following command:

   copy

   composer install
   

   The composer install command should install all the packages required in the composer.json file into the proper directory, create a composer.lock file, and recreate docroot/autoload.php if the file does not exist.

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

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

1. 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.
2. Continue to delete, change the composer.json file, and install until your website is fully working.

3. 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.