Our Drupal 9 Upgrade Story

The Drupal community is super excited for the Drupal 9 release, and so are we!

In the spirit of our tradition of keeping the QED42 website up to date with the latest Drupal releases, we decided to celebrate the Drupal 9 release day by porting our website to Drupal 9. And we’d love to share our learnings with the Drupal community.

In the DrupalCon Amsterdam Driesnote presentation, Dries stated that

Drupal 9 will be the easiest major update

And we decided to experience it first hand! Thus our journey of upgrading the QED42 website began.

The current state of our Drupal site

Before we share our Drupal 9 porting experience, it is important to understand our website’s current stack.

PHP: 7.1
MySQL: 5.6
Drupal Core: 8.8.5
Number of contributed modules: 52
Number of custom modules/themes: 5

It is a composer based project setup using drupal-composer/drupal-project as a starter-kit template.

Our Drupal 9 Upgrade Strategy and Solution

We followed these simple steps to upgrade our site to Drupal 9:

Install the upgrade status module
Update your contributed modules
Update your custom module code
Update Drupal core to Drupal 9

Lets being with the upgrade

Step 1 - Install the upgrade status module

Upgrade status module provides comprehensive support for preparing your upgrade to Drupal 9. This helps identify deprecation in contributed/custom modules and themes and suggested an update to the available version, validate the system requirements and much more. Read more about it on Drupal.org. If you are using composer based setup then use


composer require 'drupal/upgrade_status:^2.0'.

Step 2 - Update your contributed and custom modules

We identified the current state of our contributed modules - out of 52 contributed modules, only 18 were ready with Drupal 9 release.

Step 3 - Update your custom module code and theme

Next, you need to review the new dependencies and some of the most commonly used APIs that are removed in 9.0.0. Read our blog to know more about identifying deprecation /insights/coe/drupal/preview-breaking-changes-drupal-9

Step 4 - Step by Step guide for Updating Drupal core to 9

We are now at our final step to update the Drupal core, but wait we have a roadblock. Our composer setup is based on drupal-composer/drupal-project.

This project template made use of some packages that are no longer connected to the upstream and now deprecated and are in favour of new ones (drupal/recommended-project or drupal/legacy-project) that are provided by Drupal core

So, you'll need to make the following changes:

When installing Drupal core with Composer you should require drupal/core-recommended instead of drupal/core.
You have to update the drupal-composer/drupal-scaffold plugin and use the Drupal recommended drupal/core-composer-scaffold

Note: Follow the blog by Drupalize.me to know more.

We are now using the drupal/core-recommended template and the next step is to upgrade our Drupal core.
Next, you'll need to pull in the Drupal 9 version of both the core-recommended and dev-dependencies packages as dependencies. We used --no-update to avoid a chicken-and-egg problem with mutual dependencies.


composer require drupal/core-recommended:^9.0.0@rc drupal/core-composer-scaffold:^9.0.0@rc --update-with-dependencies --no-update

# If you have drupal/core-dev installed.

composer require drupal/core-dev:^9.0.0@rc --dev --update-with-dependencies --no-update

Now we are ready to update our Drupal website. However if any of your packages don’t have a release explicitly declared as D9-compatible (i.e. you are relying on a patch to make it ready), you will likely run into a dependency error when trying to update your codebase.

To get around this, you can simply add an alias to drupal/core:


composer require "drupal/core:9.0.0 as 8.9.0"

(Make sure you replace 9.0.0 and 8.9.0 to whatever versions you are using in your installation)

We are now ready to run composer update and visit our Drupal 9 website.


We hit the roadblock again! We have WSOD on few pages and Drupal logs say we still have deprecation in code.

Really? Yes, modules with stable release might have a few corner case scenarios which the upgrade status module did not report.

Here are a few issues we ran into while skimming through upgraded Drupal 9 website.


1. Twig\\\\Error\\\\RuntimeError: "The "replace" filter expects an array or "Traversable" as replace values, got "string"

2. You have requested a non-existent service "entity.manager

3. You have requested a non-existent service "path.alias_manager". Did you mean this: "path_alias.manager"?"

Few contributed modules come with a stable release but still require couple of additional patches to remove deprecated code.

Eg: config_split 8.x-1.5-rc1 stable version for Drupal 9.

https://www.drupal.org/files/issues/2020-05-05/3133805-2.patch

Multiple D9 readiness issues for a single module

For those modules which don’t have a stable release for Drupal 9 might have multiple issues on Drupal.org. You will have to collect all the issue queues.

Eg:


"drupal/image_url_formatter": {
    "Compatibility with Drupal 9": "https://www.drupal.org/files/issues/2020-03-26/3122480-2.patch",
    "Remove deprecated methods and unused imports": "https://www.drupal.org/files/issues/2020-06-02/2638620-10-deprecated-methods.patch"
},

Hurray! Finally, our site is upgraded to Drupal 9! Go ahead and check it out!

We would also love to hear about your Drupal 9 upgrade experience, do share your comments below.

We agree with Dries and do believe that Drupal 9 is the easiest upgrade ever!

Happy Drupal 9 !!!