Add Contrib and Custom Code

This section describes how to replicate your selection of contributed modules and themes, and any custom modules or themes your development team has created in your new project structure.

Contributed Code

Modules and Themes

The goal of this process is to have Composer manage all the site's contrib modules, contrib themes, core upgrades, and libraries (we'll call this contributed code). The only things that should be migrated from the existing site are custom code, custom themes, and custom modules that are specific to the existing site.

The steps here ensure that any modules and themes from drupal.org are in the composer.json require list.

Once Composer is aware of all the contributed code, you'll be able to run composer update from within the directory to have Composer upgrade all the contributed code automatically.

Begin by reviewing the existing site's code. Check for contributed modules in /modules, /modules/contrib, /sites/all/modules, and /sites/all/modules/contrib.

1. Review the site and make a list of the exact versions of modules and themes you depend on.

   One way to do this is to run the pm:list Drush command from within a contributed module's folder (e.g. /modules, /themes, /themes/contrib, /sites/all/themes, /sites/all/themes/contrib, etc.).

   This will list each module, followed by which version of that module is installed:

   terminus drush $SITE.dev pm:list -- --no-core --fields=name,version --format=table

   If you are already using Composer to manage your site dependencies, you can go to composer.json in your source site to get the package names and versions.

2. Add these modules to your new codebase using Composer by running the following for each module in the $SITE directory:

   composer require drupal/MODULE_NAME:^VERSION

   Composer might pull in a newer version than what is specified (depending on version availability), if the machine name for the module is MODULE_NAME, and the version of that module is VERSION. You can read more about the caret (^) in the Composer documentation.

   Some modules use different version formats.

   • For older Drupal version strings:

     Chaos Tools (ctools)  8.x-3.4

     Replace the 8.x- with a ^ to convert it into ^3.4.

   • Semantic Versioning version strings:

     Devel (devel)  4.1.1

     Use the version directly, e.g. ^4.1.1.

Libraries

Libraries are handled similarly to modules, but the specifics depend on how your library code was included in the source site. If you're using a library's API, you may have to do additional work to ensure that library functions properly.

Custom Code

Next, manually copy custom code from the existing site repository to the Composer-managed directory.

Modules and Themes

To move modules, use the following commands:

git checkout master web/modules/custom
git mv web/modules/custom web/modules/
git commit -m "Copy custom modules"

git checkout master modules/custom
git mv modules/custom web/modules/
git commit -m "Copy custom modules"

To move themes, use the following commands:

git checkout master web/themes/custom
git mv web/themes/custom web/themes/
git commit -m "Copy custom themes"

git checkout master themes/custom
git mv themes/custom web/themes/
git commit -m "Copy custom themes"

settings.php

Your existing site may have customizations to settings.php or other configuration files. Review these carefully and extract relevant changes from these files to copy over. Always review any file paths referenced in the code, as these paths may change in the transition to Composer.

We don't recommend that you completely overwrite the settings.php file with the old one, as it contains customizations for moving the configuration directory that shouldn't be overwritten, as well as platform-specific customizations.

git status # Ensure working tree is clean
git show master:web/sites/default/settings.php > web/sites/default/original-settings.php
diff -Nup --ignore-all-space web/sites/default/settings.php web/sites/default/original-settings.php
# edit web/sites/default/settings.php and commit as needed
rm web/sites/default/original-settings.php

git status # Ensure working tree is clean
git show master:sites/default/settings.php > web/sites/default/original-settings.php
diff -Nup --ignore-all-space web/sites/default/settings.php web/sites/default/original-settings.php
# edit web/sites/default/settings.php and commit as needed
rm web/sites/default/original-settings.php

The resulting settings.php should have no $databases array.

Commit your changes as needed.