Photo of a person with their hands on the back of their head, looking at a screen with drawings of gears in the background

Rector saves a lot of manual work by automating code upgrades from Drupal 8 to Drupal 9.

Historically, upgrading to a new major version of Drupal has been a time-consuming and expensive process involving first building an entirely new website in Drupal (content modeling, module installation, setting configuration, creating a new theme), and then creating a detailed process to migrate content from the previous Drupal website.

Then Drupal 8 came along five years ago with a new promise: Making Drupal upgrades easy forever.

Here’s how it works: Minor versions (8.1, 8.2, 8.3, etc) are being released every 6 months. They include bug fixes, new features, and API improvements. Some APIs may also get deprecated between minor versions. Major versions (9.0, 10.0, 11.0, etc) are being released when external dependencies (Symfony 3, etc.) have reached end-of-life and new versions are needed that would break backwards compatibility.

Major versions are similar to a minor version release, with two distinctions:

  1. Updates to external dependencies (new PHP version, new Symfony version, etc)
  2. Removing all parts of the API that have been marked as deprecated for this major version.

Assuming the environment is compatible, a website that doesn’t have any deprecated API calls in its modules / themes / custom code can be upgraded to the next major version as easily as a minor version upgrade.

Chart: Drupal 9.0 API = Drupal 8.9 API minus deprecated parts plus third party dependencies updated
Drupal 9 guide on Drupal.org

Getting your Drupal 8 site ready for Drupal 9

To remove deprecated code today, you would:

  1. Upgrade all contrib modules/themes to the latest version available
  2. Run drupal-check or Upgrade Status to get a list of all deprecations in your project
  3. For each project in the report, check its corresponding drupal.org page to see if it has Drupal 9 plans that would point to the issue summarizing Drupal 9 readiness plans and efforts.
  4. Apply the patches that are already available.
  5. Run drupal-check or Upgrade Status again to get the list of all the rest of the deprecations that are left in your project
  6. For every deprecation found:
    1. Search for documentation (Upgrade Status module help to find them)
    2. Manually fix the code

The current way of fixing deprecated API use involves a lot of manual and repetitive work. If one type of deprecation appears multiple times in your code, you will need to figure out how to fix it for each occurrence.

Chart: All drupal.org project errors by fixability
All Drupal.org project errors by fixability

There are approximately 33,000 occurrences of deprecated code in all contributed modules today. That’s a lot of repetitive manual work to get ready for Drupal 9!

The light at the end of the tunnel

While Googling various topics regarding Drupal upgrades, I stumbled upon a proof of concept called Drupal 8 Rector, by Dezső Biczó at Pronovix. I discovered the brilliant tool that powered it, called Rector.

What is Rector?

Rector automates PHP code upgrades.
Rector understands PHP which allows complex edge cases.

Rector PHP, by @VotrubaT, is one of the most useful projects that PHP developers overlook. It automates the upgrade and refactoring of your code (e.g. upgrades your Symfony 3 app to Symfony 4). @symfony_en

How does Rector work?

  1. Parses PHP code into an abstract syntax tree (AST)
  2. Runs  a set of upgrade rules
  3. Saves all changes back to a PHP file

What can Rector already do?

  • Rename classes, methods, properties, namespaces or constants
  • Upgrade code from PHP 5.3 to PHP 7.4
  • Upgrade code from Symfony 3 Symfony 4

Drupal 8 Rector was the missing bridge to enable automated code upgrades from Drupal 8 to 9. While Dezső unfortunately did not have time to continue working on it any more, the tremendous potential value was clear. Palantir was very interested in taking it further and making development for it easier, as we saw this as a tool that could save us time (and avoid creating new bugs) when manually fixing modules that our clients will need for Drupal 9. So we started cleaning up the repository, paired it down to its essentials and published under a new name, Drupal-Rector

What is Drupal-Rector?

A set of Rector rules. Each rule upgrades code for a deprecated API use in Drupal.

When can I start using Drupal-Rector?

Today! Just go to https://github.com/palantirnet/drupal-rector or run

composer require palantirnet/drupal-rector --dev

Image of terminal window running composer command for drupal-rector

What's the status of Drupal-Rector?

It has one Rector rule so far that fixes only one deprecation: `drupal_set_message` (Originally implemented by Dezső in the proof of concept, thank you!) This depreciation alone occurs over 8,000 times in various contributed modules and it roughly accounts for a quarter of all deprecated API uses!

https://dev.acquia.com/drupal9/deprecation_status/graphs

Our immediate goal 

Is to create Rector rules for the 15 most popular deprecations. Those 15 rules will cover 50% of all Drupal deprecations!

What are potential future goals?

We are exploring the possibility of Drupal.org integration, which would allow Drupal-Rector to be run on drupal.org projects and automatically create issues with patches. The ultimate situation would be if each API change came with a new rector rule, so projects can stay evergreen without much manual effort as the rules would be executed on them continually. 

Help us make it a better tool!

See https://github.com/palantirnet/drupal-rector. Issues are maintained on drupal.org at https://drupal.org/project/rector. We also plan to be leading contribution activities at upcoming Drupal events, including:

  • MidCamp in Chicago on March 18-21, 2020
  • DrupalCon in Minneapolis on May 18-22, 2020

We hope to see you there!

Additional Resources:

Special thanks to Jennifer Shaal, Adam Bergstein, Dan Montgomery, Gábor Hojtsy, AmyJune Hineline and George DeMet for their contributions to this post.

Development Drupal Open Source