Convert a Standard Drupal 8 Site to a Composer Managed Site
Drupal 8 sites often require the usage of Composer to manage site dependencies. The need to begin using Composer for a site build can often surface after a site is in development, necessitating a divergance from the Pantheon managed upstream.
Contributors: Dustin LeBlanc
Converting to a Composer managed site removes the ability to apply updates via the site dashboard. This is for advanced users who are comfortable taking complete responsibility for the management of site updates.
If you don't need Composer as part of your site, we strongly suggest sticking to the standard Drupal core.
Before You Begin
As packages pulled by Composer are updated (along with their dependencies), version compatibility issues can pop up. Sometimes you may need to manually alter the version constraints on a given package within the
require-dev section of
composer.json in order to update packages. See the updating dependencies section of Composer's documentation for more information.
As a first troubleshooting step, try running
composer update to bring
composer.lock up to date with the latest available packages (as constrained by the version requirements in
- Review our documentation on Git, Composer, and Terminus, and have them installed and configured on your local computer.
- Clone your current Pantheon site repository to a working directory on your local computer.
- Review Serving Sites from the Web Subdirectory
This guide uses the local command line environment, and there are several commands dependent on your specific site. Before we begin, set the variable
$site in your terminal session to match your site name:
Checkout a New Branch
You're about to make some massive changes to the codebase. We recommend you to do this work on a new branch, as it might take you some time to complete and rolling back can be complicated:
In your local terminal, change directories to your site project. For example, if you keep your projects in a folder called
projectsin the home directory:
Create the new branch:
git checkout -b composify
You can replace
composifywith a branch name of your choosing, but all following steps assume this name.
Setup a Multidev (optional)
If your Pantheon account has access to multidev, create a multidev to push your new code to:
git push origin composify && terminus env:create $site.dev composify
This will setup the multidev environment to receive and demo our changed code.
Create a New Composer Project
In your local terminal, from the repository root of your Pantheon site, move a directory up:
Use Composer to create a new project, using the Pantheon Drupal 8 Composer repository:
composer create-project pantheon-systems/example-drops-8-composer $site-composer
This will create a new directory based on the example project pantheon-systems/example-drops-8-composer in the
Since the drops-8 upstream has a
pantheon.upstream.yml and the example-drops-8-composer upstream does not, copy over our old file for the platform to properly load the site. From the
$site-composer directory, run:
cp ../$site/pantheon.upstream.yml .
ls should reveal that the new code repository now has a copy of the
Add in your Contrib/Custom code
What makes your site code unique is your selection of contributed modules and themes, and any custom modules or themes your development team has created. These customizations need to be replicated in your new project structure.
A Composer managed site should be able to include all custom code via Composer. Begin by reviewing your existing site's code. Check for contributed modules in
/sites/all/modules/contrib. Add these modules to your new codebase using Composer by running the following for each module in the
composer require drupal/module_name
module_name is the machine name of the module in question.
Repeat the same process with themes, checking
/sites/all/themes/contrib. Use Composer in the same way as above to require these.
Libraries can be handled in the same way, 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.
Modules and Themes
Custom code should be manually copied from the existing site repository to the Composer managed directory.
cp -r /modules/custom/awesome_module ../$site-composer/web/modules/custom
cp -r /themes/custom/great_theme ../$site-composer/web/themes/custom
Follow suit with any other custom code you need to carry over.
Your existing site may have customizations to
settings.php or any other config 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.
It is not wise to completely overwrite the
settings.php file with the old one, as there are customizations for moving the configuration directory you don't want to overwrite, as well as platform specific customizations.
settings.php should have no
The preferred (and assumed) location of the configuration directories when using a nested docroot and Composer is at the root of the repository next to the web directory:
my-site-composer |-web |-config <--Here! |-vendor |-composer.json |-etc...
Locate the configuration files in your existing site and move them here. If they are stored in the files directory on your existing site, retrieve them via SFTP, as the Git clone would not contain them. The example project is configured to use this location.
Prepare to Deploy
At this point, your new project directory should contain all of the unique code from your existing Drupal 8 site, plus all of the code required to make a Composer driven project work. Since Pantheon requires all runtime code to be present when deploying to the platform, if no CI solution is a part of your workflow, you must now modify the project to be deployable straight to Pantheon.
If you do plan on using a CI solution, refer to our Build Tools guide at this point.
$site-composer directory, run the following:
> DrupalProject\composer\ScriptHandler::prepareForPantheon means the command was successful. This should modify the
.gitignore file and cleanup any errant
.git directories in the codebase, to prepare your new code for direct deployment to Pantheon.
Commit your work to the git repo. From the
$site directory, run the following:
cp -r .git ../$site-composer/ cd ../$site-composer git add . git commit -m "Convert to Composer based install"
You should see a large amount of files committed to the new branch we created earlier.
You've now committed the code to a branch. If your site has multidev, you can deploy that branch directly to a new multidev and test the site in the browser. If the site doesn't load properly, clear the cache. If there are any issues, utilize your site's logs via
terminus drush $site.composify -- wd-show to inspect the watchdog logs, or follow the directions on our documentation on log collection.
Once you have confirmed the site is working, merge
master, and follow the standard workflow to QA a code change before going live.
If your plan does not include multidev, you will have to merge to master before deploying, then follow the rest of the steps above. If you have a local development solution, consider testing your
composify branch locally before merging.
Your Pantheon site is no longer compatible with traditional upstream updates. Avoid confusion by moving your site to an empty upstream:
terminus site:upstream:set $site empty
Ongoing Core Updates
Core updates are carried out via Composer:
git pull origin master composer update drupal/core --with-dependencies composer prepare-for-pantheon
Review and commit file changes, then push back to Pantheon.