Jumpstart Your Drupal 9 Upgrade with Drupal Rector
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:
- Updates to external dependencies (new PHP version, new Symfony version, etc)
- 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.
Getting your Drupal 8 site ready for Drupal 9
To remove deprecated code today, you would:
- Upgrade all contrib modules/themes to the latest version available
- Run drupal-check or Upgrade Status to get a list of all deprecations in your project
- 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.
- Apply the patches that are already available.
- Run drupal-check or Upgrade Status again to get the list of all the rest of the deprecations that are left in your project
- For every deprecation found:
- Search for documentation (Upgrade Status module help to find them)
- 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.
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?
- Parses PHP code into an abstract syntax tree (AST)
- Runs a set of upgrade rules
- 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 to 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, pared 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 download the source code or run
composer require palantirnet/drupal-rector --dev
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!
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!
Visit the code respository. Issues are maintained on drupal.org. We also plan to be leading contribution activities at upcoming Drupal events, including:
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.
