Drupal 9

Get started with Drupal 9 on the Pantheon WebOps Platform.

Contributors: Matt Cheney, Edward Angert, Whitney Meredith.

Discuss in our Forum Discuss in Slack

Drupal 9 is available on Pantheon to all new sites, and is available as an upgrade path for Drupal 8 sites.

Since Drupal 9 on Pantheon is in active development and includes a number of significant changes from previous versions of Drupal, this doc outlines the biggest changes and answers frequently asked questions.

About Drupal 9

Drupal 9 includes many of the features and layout that Drupal users are familiar with, and it removes deprecated code to help improve future Drupal development.

Drupal 9 updates Drupal’s underlying dependencies like Symfony 4.4 and Twig 2, removes several deprecated API functions in favor of better options, and allows everyone running Drupal 8.8+ an easy upgrade path to Drupal 9 and beyond.

Drupal 9 With Integrated Composer

On the Pantheon Platform, Drupal 9 sites use Integrated Composer, letting you deploy your site on Pantheon with one-click updates for both upstream commits and Composer dependencies, while still receiving upstream updates.

Site Structure

The upstream has the following directory structure:

code/
code/
├─ .gitignore
├─ composer.json
└─ pantheon.upstream.yml
├─ README.md
└─ upstream-configuration/ or upstream-config/ for WordPress
   └─ composer.json
└─ web/
   └─ sites/ for Drupal
   └─ wp-content/ for WordPress
  • .gitignore: Prevents build artifacts generated by Composer from being committed to the upstream or site code repositories. Note that changing the tracking status of composer-managed files and directories can result in build failures or lead to unexpected errors.
  • composer.json: The two different composer.json files allow customization of individual sites without inherent merge conflicts and enable one-click updates.
    • Root-level: Site-level customizations.
    • Drupal: upstream-configuration/ or WordPress: upstream-config/:
      • composer.json: Composer automatically updates composer.json with customizations for the upstream. Avoid manually modifying this file.
  • pantheon.upstream.yml: The build_step: true directive in pantheon.upstream.yml enables the build step.

When a site is created, Pantheon runs composer install, generates a composer.lock file, and commits it back to the site’s code repository. To avoid potential merge conflicts after applying an upstream update, do not commit the composer.lock file to the upstream repository.

Build artifacts are stored in a Git tag like pantheon_build_artifacts_$BRANCHNAME, where $BRANCHNAME is the name of the environment or Multidev feature branch.

It is a requirement that all build artifacts should be ignored in the .gitignore file. Ensure you add entries to the .gitignore any time you modify the build to move installation files to a new locations.

Managing Dependencies with Composer

Learn more about working with upstream and site dependencies in the Integrated Composer documentation.

Before You Begin

  • Log in to your Pantheon account. If you don't have one, create one first and familiarize yourself with the User Dashboard before you create a new site.

  • Set up SSH Keys on your local computer and Pantheon account.

  • Install and configure Git and Composer on your local computer.

    • Mac users can use Homebrew to install both Git and Composer, along with their required dependencies:

      brew install git composer

Create a New Drupal 9 Site with Integrated Composer

Create a new Drupal 9 site from the Dashboard as you would with any new site. Integrated Composer is built in and ready to use.

Upgrade or Migrate to Drupal 9

To upgrade or migrate an existing Drupal site to Drupal 9 with Integrated Composer, see the Drupal 9 Migration Guide.

To check an existing site's compatibility to upgrade, visit the appropriate Drupal Migration Guide.

Gutenberg for Drupal 9

After you upgrade to Drupal 9 you may consider upgrading the authoring experience for your content creators as well. We recommend using Gutenberg for a better user experience, including:

  • Creating, saving, and reusing content blocks
  • Easier build process for landing pages
  • Scalable performance

You can read more about Pantheon's experience with Gutenberg in Gutenberg on Drupal 9: An Opportunity.

You can also read more about the installation process on Drupal.org.

We recommend monitoring your site's traffic using Metrics in the Site Dashboard to check for increased traffic after installing Gutenberg.

Troubleshooting and Support

See the appropriate Drupal 9 Migration Guide for help troubleshooting common issues with Drupal 9 with Integrated Composer.

Where can I report an issue?

Contact support to report any issues that you encounter.

Can I Use Lando or Localdev for Drupal 9?

Local development options for Drupal 9 are currently being implemented into Localdev.

Some users have reported success using Lando with Drupal 9, but it relies on a workaround and requires extra configuration. Check the status of the Lando repo's issue before you continue.

Manually update the landofile in the project folder, and set drupal9 as the framework:

lando.yml
# Lando issue 2831 workaround for D9
framework: drupal9

When you create a project with Lando from the Pantheon recipe, the framework will default to drupal9 for a Drupal 9 site.

If you created new project with Lando, change the value for framework to drupal9, then run lando rebuild.

Site-local Drush Is Required for Drupal 9 Sites

Do not remove drush/drush from composer.json. If it's removed, terminus drush commands will fail with errors related to Twig.