​

To keep your organization at the forefront of open source security and innovation now's the time for a Drupal upgrade or migration to Drupal 9. Drupal 7’s end-of-life is November 2022, but if you’re currently on Drupal 8 the end-of-life hits in November 2021.

In this guide, we’ll cover Mediacurrent’s tried and tested approach to upgrading sites of all sizes. Kick-off with a codebase audit. Then, tackle code and compatibility issues. In the final mile, run a first-attempt upgrade to find and fix any remaining issues. And finally, the actual Drupal 9 upgrade.

Introduction

As you think about your upgrade path (whether moving from Drupal 7 or 8), a good starting point in preparing for Drupal 9 is performing a readiness audit. An audit will assess the level of effort and provide recommendations and preparations for a smooth upgrade or migration path to Drupal 9.

At a high level, a Drupal 9 upgrade process would look like this:

1. Audit the codebase for deprecated code

2. Audit the codebase for composer compatibility

3. Fix deprecated code issues

4. Fix composer compatibility issues

5. Attempt Drupal 9 upgrade and see what’s left

6. Perform actual Drupal 9 upgrade

In the first blog post of this Drupal 9 Upgrade series, I will focus on the first two steps and show you how to audit a codebase for Drupal 9 readiness. By the end, you will have a better understanding of the process and level of effort required for a successful upgrade and be more prepared to estimate a budget and timeline.

Audit for Drupal 9 Readiness

Performing an initial audit on the codebase is straightforward. This process should result in tickets in your task management system of updates to be performed way before the actual Drupal 9 upgrade release date.

Scan for deprecated code

Drupal-check is an invaluable tool for scanning files in a codebase to check their Drupal 9 readiness by looking for deprecated code -- basically code that was previously lingering around in Drupal 8 but is now removed from Drupal 9.

If drupal-check helps you during this process, and I’m sure it will, consider sponsoring the ongoing development and improvements of the project.

Install drupal-check

The most typical way to install drupal-check is to install it as part of the project via composer as a dev requirement. Be sure to review the drupal-check installation documentation.

composer require --dev mglaman/drupal-check

Run drupal-check

The drupal-check command can be run on any single file or directory. These steps assume it was installed in the project with composer, therefore the executable exists in the “vendor” folder and can be run as follows.

Here is an example of running the command against a contributed module that contains some deprecated code issues:

vendor/bin/drupal-check docroot/modules/contrib/allowed_formats

Now would be a good time to create a task in your task management system for addressing that deprecated code issue. Thankfully a solution already exists for the Allowed Formats contributed module that fixes this one particular issue.

That issue and fix were found by visiting the module’s project page that you are working on making Drupal 9 ready, search for “drupal 9” in the issue search box, and review what Drupal 9 related issues exist.

There is typically an issue labeled “Drupal 9 Deprecated Code Report”, but it may be named something else, and there may also be multiple related issues.

Here is another run of drupal-check against another contributed module, which in this case, has no deprecated code issues.

vendor/bin/drupal-check docroot/modules/contrib/crop

While it appears at this time that this module is Drupal 9 ready per the drupal-check tests, it may not be completely Drupal 9 ready yet. In the next section, we’ll look at ways to check composer compatibility, which once the module is both composer compatible and no code deprecations present, it will be in great shape for the Drupal 9 upgrade.

Good, but not perfect

The drupal-check tool is very helpful, but it is not perfect. Again, consider sponsoring the project to help continue future development and improvements!

One of the false positives drupal-check may report relates to class usage. For example, it may be validating a class that is used by a module that no longer exists in the codebase, e.g. old code from a Drupal 7 migration that’s no longer used, so there’s nothing to do about that.

Also, sometimes drupal-check does not catch certain issues. For example, the codebase had a custom module that still contained a call to the `path.alias_manager` service, but that service is no longer available in Drupal 9 and was moved to `path_alias.manager`. However, drupal-check did not report this as an issue - I only found out about this issue once the Drupal 9 site was built and I tried to access the page that was controlled by the code that contained that old, removed service class call.

An alternative to drupal-check is to use the contributed module, Upgrade Status, to check on the Drupal 9 readiness of your existing site.

You should now have a good understanding of what custom and contributed packages need work to make them Drupal 9 ready. Be sure to keep notes or skip to the Issue Tracking section below.

Check composer compatibility

In addition to the deprecated code issues, the codebase also needs to be compatible with Drupal 9 from a composer perspective. Without packages being Drupal 9 supported in composer, composer will simply not allow the codebase to upgrade to Drupal 9.

What’s Not D9 Compatible?

A quick test you can do right away is to run this command, which will list all packages that are only supported by Drupal 8. These will need to be updated to also support Drupal 9.

composer why drupal/core | grep -Ev "\^9"

Essentially, this command tells us which other packages depend on Drupal core that do not yet have a 9 version in its composer metadata. Composer will not allow a Drupal 9 upgrade. Read more about the Composer Why command.

The output of the command will look something like the following:

These values come from the composer.lock file and are basically the list of packages used in the codebase that depend on drupal/core, specifically packages that only work with Drupal 8. This should be pretty much all of the themes, modules, and profiles, unless they have been kept updated on a regular basis and when security releases are available and necessary.

Just to be clear, the first lines that start with “drupal/core” can be ignored, the only ones to focus on are the other lines that reference contributed (or custom) modules.

For instance, in the example above the Facets module has a current version of “1.4.0”, or 8.x-1.4. This module will need to be updated to a later version, or a patch added that makes it Drupal 9 compliant; it might also be worth testing the current dev snapshot, the necessary fixes might have been committed, just not available as a full release yet. It appears for Facets module, the 8.x-1.5 version adds the Drupal 9 support.

Results in this output should be added as new tickets in the ticket management system of packages needing updates to address the deprecated code and composer compatibility issues.

Issue Tracking

To track the status of packages and their Drupal 9 readiness, I recommend creating a spreadsheet that helps track the ongoing upgrade process and what needs to be done. The below is just a small subset of changes needed, but I do recommend having multiple rows per package, in the cases where there may be multiple Drupal.org issues to cover all the D9 related fixes you’ll need.

Without getting too deep into it right now (saving for the next blog post), I’ve seen deprecated code issues be addressed in one Drupal.org issue, and the fix was committed to the latest version. But simply updating to the latest version did not make it Drupal 9 ready, because there were still composer compatibility fixes, and in some more rare cases, even still some deprecated code issues that were missed in the first pass. So, those issues may be split among multiple issues on Drupal.org.

This planning, tracking, and documentation will help you as you continue through the Drupal 9 Upgrade process and keep tabs on what is remaining along the way. It may also serve as a good starting point or baseline for the next Drupal 9 upgrade process you may be involved in.

Conclusion

This blog post focused on the up-front audit process and preparation work required to understand the amount of work required to get into Drupal 9 readiness status. In the next blog post in this Drupal 9 Upgrade series, we will work on fixing the deprecated code and composer compatibility issues we discovered and documented as a result of this audit process.

Mediacurrent is a top 10 contributor on Drupal.org and has created solutions to accelerate, ease, and enhance the upgrade process. We can help you prepare for a Drupal 9 upgrade. Reach out anytime if you want to discuss your Drupal upgrade path or are interested in our team performing a Drupal 9 audit on your site and how we can help you succeed.