Upgrade a Drupal Site with Integrated Composer to the Latest Version of Drupal

This page shows how to upgrade an existing Pantheon-hosted Drupal site using Integrated Composer to the latest version of Drupal using Integrated Composer.

If this is not your scenario, see Drupal Migration Guides for additional upgrade paths.

Overview

The goal of this upgrade is to set the Drupal core dependency to Drupal (Latest Version). This upgrade allows Composer to manage dependencies in the new site.

Will This Guide Work for Your Site?

You must be on Drupal using Integrated Composer to use this guide. You can confirm that Integrated Composer is set up by checking that your site has the Pantheon drupal-composer-managed repo in its upstream.

Confirm the site requirements in the sections below before upgrading to the latest version of Drupal.

Verify the Repository

1. Check that your site has the Pantheon drupal-composer-managed repo in its upstream.

2. Use Terminus to Confirm the drupal-composer-managed Upstream:

   terminus site:info $SITE

   The following values indicate that a site is using the drupal-composer-managed upstream:

• The Framework is drupal8

• The Upstream includes https://github.com/pantheon-upstreams/drupal-composer-managed

  The following is an abridged example of the output for the terminus site:info $SITE command, if the site upstream is set to drupal-composer-managed:

  terminus site:info $SITE
  ------------------ -------------------------------------------------------------------------------------
  ID                 abdc3ea1-fe0b-1234-9c9f-3cxeAA123f88
  Name               anita-drupal
  Label              AnitaDrupal
  Created            2019-12-02 18:28:14
  Framework          drupal8
  ...
  Upstream           897fdf15-992e-4fa1-beab-89e2b5027e03: https://github.com/pantheon-upstreams/drupal-composer-managed
  ...
  ------------------ -------------------------------------------------------------------------------------

Prepare the Local Environment

1. Review the documentation on Git, Composer, and Terminus, and install and configure them on your local computer. Pantheon requires Composer 2, at minimum.

   • Mac users can use Homebrew to install Git, Composer, and PHP, along with their required dependencies. Note: Terminus 3 should be used for PHP >= 8.0. Restart the shell or terminal environment after entering the following command:

     brew install git composer php

   • Windows users can install Composer and Git, and may need to install XAMPP or similar to satisfy some dependencies.

2. Set the temporary variable $SITE in your terminal session to match the name of your site.

   This doc uses several commands that use the temporary command line alias, $SITE, to make entering command examples easier. Refer to the steps further in this doc to see which sites should be aliased (it may be more than one), then replace anita-drupal in this example:

   export SITE=anita-drupal && echo "New alias set as $SITE"

   How to Use Terminus to Find the Site Name

   Use terminus site:list for a list of sites you have access to:

   terminus site:list
   --------------------------- --------------------- ------------- ----------------------------------- -------------------- --------------------- ------------- ------------
   Name                        ID                    Plan          Framework          Region           Owner                Created               Memberships   Is Frozen?
   --------------------------- --------------------- ------------- ------------------- ---------------- -------------------- --------------------- ------------- ------------
   anita-drupal                abdc80ce-286c-1234-   Sandbox       drupal8             Canada           3374708c-987e-1234   2020-12-15 19:40:42   d3ecc20c-395a falseanita-wordpres              abdc9954-fab2-1234-   Sandbox       wordpress           United States    c96ddb25-336a-1234   2020-09-02 07:18:51   d3ecc20c-395a false

   The site name is listed under Name. In this example, the site name is anita-drupal.

Apply All Available Upstream Updates

Update the site to the latest Pantheon Drupal Composer Managed Upstream and apply all available updates.

1. Use Terminus to list all available updates:

   terminus upstream:updates:list $SITE.dev
   [warning] There are no available updates for this site.

2. Run the following code to apply available updates:

   terminus upstream:updates:apply $SITE.dev --updatedb

You can also use the Pantheon Dashboard to apply upstream updates.

Ensure Dependencies are Compatible with the Latest Version of Drupal

Make sure all the components of your site are compatible with the latest version before you change the Drupal core version to it. Review the steps in Upgrading Drupal for details, and use Upgrade Status to check the compatibility of all contributed modules and themes.

Set Drupal Core Version

1. Set the Drupal core version to the latest version of Drupal:

   composer require --update-with-dependencies --no-update 'drupal/core-recommended:^10' 'drupal/core-composer-scaffold:^10'
   composer update drupal/core* -W
   git add composer.*
   git commit -m "upgrade to Drupal 10"

Ongoing Core Updates

One-click core updates can be made through the Dashboard:

1. Navigate to Code in the Dev tab of the site's Dashboard.

2. Click Check Now.

3. Click Apply Updates if updates are available.

Troubleshooting

Version compatibility issues can occur when packages pulled by Composer are updated along with their dependencies. If this happens, you will need to manually alter the version constraints on a given package in the require or require-dev section of composer.json to update the packages. Refer to the updating dependencies section of the Composer documentation for more information.

Troubleshoot package updates by running composer update. This updates composer.lock to the latest available packages. Package updates are constrained by version requirements in composer.json.

More Resources

• Composer Fundamentals and Workflows
• Drupal 10 on Pantheon