Automated removal of deprecations for easy Drupal 9 upgrades

One of the most important Drupal news of late 2021 is that Drupal 8 has reached its end of life on November 2. This means it’s high time to upgrade websites to Drupal 9 for all those who have not already. Moreover, Drupal 10 is planned for release in 2022 (most probably in June), so D8 websites are at risk of getting too far behind. Here is where the opportunities for automated deprecated code removal come in handy. Read on to find out more from this blog post by our development team.

Deprecations and their role in Drupal 9 upgrades

Upgrading a site to Drupal 9 is not a problem. In the last couple of years, the development circles have been buzzing with discussions of “upgrades made easy forever.” Yes, you can quickly and effortlessly move from D8 to D9 (and D10 in the future) if you make sure you are not using deprecated code. You need to find and replace deprecations on your website with the defined alternatives that work better and are more modern.

Deprecations are part of Drupal’s lifecycle and there is nothing new in them — they are present in many programming languages including PHP. Deprecated code includes methods, classes, and APIs that are flagged as something that shouldn’t be used any longer and officially removed during a major Drupal core version change.

Before removal, legacy code remains functional for some time because some other code relies on it. It is also important for developers to know ahead of time that, for example, some API is flagged for deprecation so they can update their code accordingly. However, the moment comes when it’s officially gone so you get an error if you attempt to upgrade your website to a new major version and still use something deprecated (for example, your website has deprecated API calls in its modules, themes, or custom code).

In many cases, updating deprecations means replacing a few lines of code, while some require more detailed refactoring. Who should do this, largely depends on the type of project. In the case of the core and contributed modules, it’s up to their maintainers to take care of the legacy code, so the projects just need to be updated — all you need to find out is which contributed module versions are compatible with Drupal 9. Sometimes, module maintainers forget to update their projects, in which case you can create an issue in the module's issue queue on drupal.org or make a patch to fix the deprecation.

Custom code requires much more attention — you will need to find where it is relying on a deprecated API or feature and update it accordingly. It is present on almost every Drupal website and needs to be cleaned up from deprecations manually.

Wait, why manually? Automation makes the world go round, and it would be surprising if developers did not create automated workflows for removing deprecations. We are going to discuss them right now.

Automated removal of deprecated code on Drupal websites

The automation of the deprecation removal is especially useful for websites with plenty of custom modules that otherwise would take a lot of time to clean up. But whatever the amount of custom code is, automated removal of deprecations offers a smart way of doing things, reduces the upgrade time & costs, and eliminates the chance of human error.

1. Preparation: finding deprecated code

First of all, deprecations need to be found so you can assess your website’s Drupal 9 compatibility and move on with the automatic clean-up. There are several tools that you might consider adding to your toolkit:

• Drupal-check is a static PHP analysis tool that allows you to run an executable from the terminal and get a full report of all website’s deprecations, including those in contributed and custom modules. The tool suggests a fix when it finds a deprecation. It’s possible to integrate the tool with build processes and CI (continuous integration) systems.
• The Upgrade Status module is built on top of the Drupal-check and allows you to use the Drupal administrative interface in order to get your website’s deprecations report. You can also use the command line thanks to the Drush support offered by the module. Similarly, it checks contributed and custom code. The module also offers additional features such as per-project checking, storage, multi-result export, issue categorization, deprecated Twig syntax checking, deprecated Drupal libraries checking, notes on the missing core version requirement keys, and more.
• Drupal 9 Deprecation Status by Acquia is convenient for checking contributed modules. The tool shows you the Drupal 9 compatibility of the drupal.org projects. It uses the Drupal Association’s analysis of all contributed projects as a data source.
• Drupal.org's testing system is a useful tool for contributed module maintainers to discover the use of deprecated code. The two ways to do this are to run a static deprecation analysis and/or configure your tests to fail when deprecations are found.
• Drupal.org project pages are also a great way to check whether the contributed modules or themes you are using are Drupal 9 compatible (or their maintainers have plans to make them compatible soon).
• PHPstan Drupal integration can test your codebase for deprecations using PHPStan — the PHP Static Analysis Tool.

2. Removing deprecated code automatically with Rector

All the above-listed tools are great but they will not automatically fix the code for you. It’s Rector that is able to do that. Rector is an open-source PHP-based CLI tool that enables you to apply rules that refactor your code. It comes with its own rules, some of which are framework-specific and some can work on any PHP code. The rules can be organized into sets. Rector uses AST (Abstract Syntax Tree) for parsing the code.

Rector can do both easy and complicated refactoring. For example, it can find a specific class, method, property, namespace, or constant throughout the codebase and automatically rename it everywhere based on the rule. Among more complex things are updating the version of PHP or PHP-based framework (Symfony, Laravel, etc) or migrating the code from one framework to another. The automated fixes applied by Rector can also improve the quality of code and make sure the best practices are used.

There is a special Drupal implementation of the tool — Drupal Rector maintained by the Palantir team. It is a wrapper around Rector designed to automate the removal of deprecated code and do other refactoring in the process of preparing a D8 website for D9. Drupal Initiative coordinator Gábor Hojtsy called the tool “amazing at providing automated fixes for an increasing number of deprecated APIs.”

Drupal Rector covers the most common cases of cleaning up the code from deprecations. After applying the rules, it outputs the refactored version. Since it makes changes to your codebase, it is recommended you use a Git branch, which allows you to view the changes, and revert to the previous version if you are not happy with the result.

There was also a special package called Rector for Drupal 8 meant to provide instant fixes to your D8 code by using Rector. However, it is now abandoned and no longer maintained, so the creators suggest using the Drupal Rector package instead.

Currently, the latest Drupal Rector version is 0.12.0 for Drupal 8.x and 9.x deprecations. The module’s maintainers emphasize that D9 deprecation testing recommends PHP 8.

In order to use the tool, you will need to:

• install drupal-rector using Composer
• create a rector.yml configuration file and make settings
• execute Drupal Rector.

You can view more details for running and troubleshooting the tool on the project’s GitHub page.

For all those who are more comfortable with the administrative interface, there is also a contributed module named the Upgrade Rector that was created by Gábor Hojtsy. It integrates with the Upgrade Status module that checks the site for deprecations. The Upgrade Rector allows you to pick your projects and generate patches. There is a great video by Gábor Hojtsy that shows off the capabilities of the Upgrade Rector.

Is your website ready for a Drupal 9 upgrade?

With amazing tools at your disposal, it’s time to finally make your website Drupal 9 ready and also pave the way for the future D10 upgrade, which promises to be even easier. If you need a professional hand in removing deprecations from your site, you can reach out to the Golems team!