Drupal 9 has been around since June 3, 2020, and many websites have already upgraded to it.
According to Drupal core usage statistics on drupal.org, there are 23,753 websites using the 9.0.x and 26,411 using the 9.1.x branch. 162,090 websites are currently on the 8.9.x branch, so they are really very close to a seamless Drupal 9 upgrade.

To upgrade websites to Drupal 9, developers have great tools in their arsenal. In this blog post, our Drupal development team that runs through these tools and takes a closer look at one of them — Drupal Rector.

The formula of successful Drupal 9 upgrades

In every Drupal 9 review, you will hear that one of its best features is the easiest Drupal upgrades ever. Back in 2017, Drupal founder and lead developer Dries Buytaert wrote about the ambition to “make Drupal upgrades easy forever,” and we can now see this becoming a reality. Time-consuming and expensive upgrades, like the ones we used to see in a transition from Drupal 7 to 8, are gone into history.

What is it that has made Drupal 9 upgrades so easy? It’s D9’s backwards compatibility with D8.9.x and the magic formula “Drupal 9.0 = Drupal 8.9 - deprecated code.” In other words:

Upgrade to Drupal 9 = Update to Drupal 8.9 + Remove deprecations

As you can see, in addition to updating your core and contributed modules and themes to their latest versions, an essential part of the Drupal 9 upgrade process will be removing deprecations from your website’s codebase.

What are deprecations?

There are numerous methods and classes that are marked as outdated (deprecated) in every major Drupal release. Deprecations became especially common as the CMS moved from procedural to object oriented programming and started using Symfony components.

Deprecated elements need to be found in your code and replaced with new alternatives so your project becomes compatible with a newer core version. If a module works on D8 and has its deprecated APIs removed, it will work on D9 as well.

Maintainers of thousands of contributed modules have already fixed deprecations in their projects. See them on the Drupal 9 compatibility list for all Drupal projects maintained by the Acquia team. Gábor Hojtsy, Drupal Initiative Coordinator, wrote in his “State of Drupal 9” presentation that 87% of top 200 modules and themes are explicitly Drupal 9 compatible!

Depending on the scope of your website, removing deprecations can take a lot of tedious manual work. Of course, programmers are people who would never agree to that in the XXI century! That’s why helpful tools have been invented that automate the deprecation fixes.

A brief review of useful Drupal 9 upgrade tools

Gábor Hojtsy mentioned the upgrade tools that report the use of deprecated APIs and the ones that suggest fixes for these deprecated APIs. So it’s best to combine both types of tools for your D9 upgrade:

1) Start with a check:

• Drupal Check is a CLI tool that discovers which elements in your Drupal codebase are deprecated and need to be updated for Drupal 9 compatibility.
• Upgrade Status is a contributed module based on Drupal Check that gives you a user interface for discovering the deprecations.

2) Continue with a fix:

• Drupal Rector is a tool that suggests deprecation fixes and automates the fixing process.
• Upgrade Rector is a contributed module based on Drupal Rector that gives you a user interface for automating your deprecation fixes.

Drupal Rector: a great tool for smooth upgrades

Drupal Rector is a tool that provides automatic fixes for deprecated code and performs the refactoring needed to make a project compatible with D9. It finds the methods, classes, and other PHP code elements that have been marked as deprecated and replaces them with the new ones. The tool eliminates the need for repetitive tasks, streamlines the upgrade process, and significantly reduces its upgrade time and costs.

Drupal Rector can work with the Drupal core, contributed modules, and custom modules. According to its creators, not all modules can be fixed automatically by DR, but more than half of the modules can.

The creation of Drupal Rector was inspired by another awesome tool — Drupal 8 Rector by Dezső Biczó at Pronovix. However, the development of D8 Rector was not active due to lack of its creator’s time, so the Palantir team decided to build a new project — Drupal Rector — that would inherit the best capabilities of its predecessor.

Both these tools are based on a very powerful PHP project called Rector that was made by developer Tomas Votruba. Rector is a tool meant to automate PHP code upgrades. Its creator describes it as a tool for instant upgrades and instant refactoring. It can upgrade classes, properties, methods, and much more, as well as upgrade PHP and Symfony code from an older to a newer version. Rector’s capabilities include architectural refactoring, which requires more complex work than simple renaming. On the tool’s main page, it’s mentioned that you can delegate boring work to Rector and speed up your development process by 300%.

How does Drupal Rector work?

Basically, Rector’s work resembles the common “find and replace” feature. For example, if the tool needs to replace an outdated PHP method, it finds all places in the codebase where it is used and replaces it in all of them.

How does Rector know what to replace and how? This is defined by Rector rules. When we speak about the general Rector tool, it has a set of rules, some of which are framework-specific and some are multipurpose. Drupal Rector, in its turn, uses Drupal-specific rules for refactoring the codebase and outputting an updated one.

DR allows you to fine-tune your code update process by creating your own rules. The Palantir team, the creators of Drupal Rector, have shared a blog post about creating Rector rules. The process includes three steps:

1. creating an example PHP file that shows the deprecated code we need to update
2. creating a Rector file that replaces the deprecated code
3. adding the Rector rule to the list of deprecations in the configuration rector.yml file

The Drupal Rector repository contains examples and base classes that will help you set up the Rector rules.

How to start working with Drupal Rector?

First, you need to make sure you are using a PHP version that is not older than 7.2, and then install DR either by going to its Git repository or by using the Composer command:

composer require palantirnet/drupal-rector --dev

Then you should create a rector.yml configuration file at the root of your Drupal project that tells Rector which rules to use, where to look at your project’s code, and more. Please do not forget about the security principles when working with tools that change your codebase — use a Git branch so you can revert the changes at any time.

Upgrade Rector: user interface for Drupal Rector

Drupal will always have a user-friendly module for every powerful tool. The Drupal Upgrade Rector contributed module provides a user interface for working with DR. The module gives you automated code fix suggestions and makes it easy to generate patches.

The Upgrade Rector is made for D8 websites so they can have a smoother Drupal 8 to 9 upgrade. It is still in its alpha version, but is already compatible with D9.

Upgrade to Drupal 9 if you haven’t yet!

Drupal Rector and all the other Drupal 9 upgrade tools are most effective when used by experienced developers. Discover Drupal services by Golems and give your Drupal site a new start. If you need any help with upgrades, Drupal 9 installation, and much more, contact us.

Let’s transfer your D8 or D7 site to Drupal 9 using the best tools and practices available today!

Waiting to hear from you!
Your Golems