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

The goal of this process is to have Composer manage the site's:

• Contrib modules

• Contrib themes

• Core upgrades

• Libraries (referred to as contributed code)

The only items from the existing site that should remain in the Git repository are custom code, custom themes, and custom modules that are specific to the existing site.

Modules and Themes

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

Composer must be aware of all contributed code before you can run composer update command within the directory. This command tells Composer to upgrade all contributed code automatically. The Pantheon dashboard will also update Composer dependencies in addition to updating the files from the upstream.

1. Review the existing site's code and check for contributed modules in:

   • /modules

   • /modules/contrib

   • /sites/all/modules

   • /sites/all/modules/contrib

2. Run the pm:list Drush command within a contributed modules folder, for example:

   • /modules

   • /themes

   • /themes/contrib

   • /sites/all/themes

   • /sites/all/themes/contrib

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

   drush pm:list --no-core --fields=name,project,version  --format=table

3. Review the list and note the versions of modules and themes you depend on.

4. Add these modules to your new codebase by running the following command for each module in the $DESTINATION directory:

   composer require drupal/PROJECT_NAME:^VERSION

   Where PROJECT_NAME is the project name from the Project field, and VERSION is the version of that module the site is currently using. Composer may pull in a newer version than what you specify, depending on what versions are available. You can read more about the caret (^) in the Composer documentation.

   Some modules use different version formats.

   • For older-style Drupal version strings:

     Chaos Tools (ctools)  8.x-3.4

     Replace the 8.x- to convert this into ^3.4

   • Semantic Versioning version strings:

     Devel (devel)  4.1.1

     Use the version directly, e.g. ^4.1.1

     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.

Other Composer Packages

You must migrate non-composer packages to your site if have added any via Composer.

1. Run the composer require command to migrate each package.

2. Run the command below to display the differences between the master and your current composer.json:

diff -Nup --ignore-all-space $SOURCE/composer.json $DESTINATION/composer.json

Libraries

Libraries can be 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 it functions correctly.

Do not forget to commit your changes during these steps.

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.

Additional Composer Configuration

Any additional Composer configuration that you have added to your site should be ported over to the new composer.json file. This can include configurations related to repositories, minimum-stability, or extra sections.

Use the diff command to get the information you need to copy:

diff -Nup --ignore-all-space $SOURCE/composer.json $DESTINATION/composer.json

Commit your changes as needed.