Version 0.15.0 for Drupal 8.x and 9.x deprecations. Note that Drupal 9 deprecation testing recommends PHP 8. Show
Release notes
Note that GitHub does not let us have different default homepage and merge branches. If you checked out the project using packagist/composer, read the docs for your version. IntroductionYou can read more details in the following blog post: https://www.palantir.net/blog/jumpstart-your-drupal-9-upgrade-drupal-rector DocumentationDevelopment guides, individual deprecation overviews, and other resources can be found here: https://www.palantir.net/rector Scope and limitationsThe development of this tool is prioritized by the perceived impact of the deprecations and updates. There are many deprecations that often involve several components and for each of these there are several ways to address the deprecation. We've tried to determine impact based on:
So, high impact (the code works in newer versions of Drupal for a large number of people), low effort (we can develop the rule based on our knowledge of Rector). Common limitationsKnown limitations are listed in the comment documentation for each rule. Common limitations include:
Our hope is that as we learn more about Rector, we may be able to update these rules to add these features. Issues are managed on drupal.orghttps://www.drupal.org/project/issues/rector For contribution suggestions, please see the later section of this document. InstallationNOTE: To have the best experience with Drupal Rector, your Drupal site should be running version 8.9 or higher. Install Drupal Rector inside a Drupal project.$ composer require --dev palantirnet/drupal-rector Create a configuration file in your projectYou will need to have a cp vendor/palantirnet/drupal-rector/rector.php . 1 configuration in the root of your repository. This should sit beside your document root such as cp vendor/palantirnet/drupal-rector/rector.php . 2 or cp vendor/palantirnet/drupal-rector/rector.php . 3.This project uses cp vendor/palantirnet/drupal-rector/rector.php . 4 to find your document root that contains Drupal.To get started, copy the cp vendor/palantirnet/drupal-rector/rector.php . 1 configuration file provided by this package:cp vendor/palantirnet/drupal-rector/rector.php . By default, Drupal Rector will fix deprecated code for all versions of Drupal. If you want to change this behavior, modify the sets used in the cp vendor/palantirnet/drupal-rector/rector.php . 1 config. For example, if your site is still on Drupal 9.3, and you cannot fix deprecations made in Drupal 9.4, use the following configuration:$rectorConfig->sets([ Drupal9SetList::DRUPAL_90, Drupal9SetList::DRUPAL_91, Drupal9SetList::DRUPAL_92, Drupal9SetList::DRUPAL_93, ]); This is more granular than the cp vendor/palantirnet/drupal-rector/rector.php . 7 set.Suggested workflow
$ vendor/bin/rector process web/modules/contrib/[YOUR_MODULE] --dry-run
$ vendor/bin/rector process web/modules/contrib/[YOUR_MODULE] You can find more information about Rector here. TroubleshootingPhpStan composer issuesYou may need to upgrade cp vendor/palantirnet/drupal-rector/rector.php . 8 with Composer before installing this package.Rector itself has conflicts with older versions of PhpStan. Unable to find Rector rule classesIf you are getting errors like cp vendor/palantirnet/drupal-rector/rector.php . 9You may need to rebuild your autoload file. $rectorConfig->sets([ Drupal9SetList::DRUPAL_90, Drupal9SetList::DRUPAL_91, Drupal9SetList::DRUPAL_92, Drupal9SetList::DRUPAL_93, ]);0 FileLocator::locate() must be compatible with FileLocatorInterface::locate()If you are getting errors like
You may need to check that you are
Sometimes people install composer dependencies from one machine (host machine) and run Drupal Rector from another (such as a Lando VM). If you are having these issues try running Rector from the environment that has Php 7.2 or greater. Drupal Rector does not need a fully functional web server, it only (more or less) needs Php and access to a standard Drupal set of files. Iconv error when running Rector in Alpine DockerIf you are getting errors like $rectorConfig->sets([ Drupal9SetList::DRUPAL_90, Drupal9SetList::DRUPAL_91, Drupal9SetList::DRUPAL_92, Drupal9SetList::DRUPAL_93, ]);2 You can fix it in Dockerfile with
Credits to @zolotov88 in Development and contribution suggestionsThanks for your interest in contributing! Our goal is to make contributing to this project easy for people. While we've made certain architectural decisions here to hopefully achieve that goal, it's a work in progress and feedback is appreciated. Development environmentSee the instructions in Adding a Rector ruleIf you would like to submit a Rector rule, we are looking for the following:
GuidesA few guides are currently available and we encourage people to create additional guides to provide their perspective and help us better understand this tool together. Video guide on creating a rector rulehttps://www.palantir.net/rector/creating-drupal-rector-rule Additional documentation and linkshttps://www.palantir.net/rector Quick(?) overviewCreate a Rector rule classRector rules should be named after the deprecation, including the class name. $rectorConfig->sets([ Drupal9SetList::DRUPAL_90, Drupal9SetList::DRUPAL_91, Drupal9SetList::DRUPAL_92, Drupal9SetList::DRUPAL_93, ]);8 -> $rectorConfig->sets([ Drupal9SetList::DRUPAL_90, Drupal9SetList::DRUPAL_91, Drupal9SetList::DRUPAL_92, Drupal9SetList::DRUPAL_93, ]);9 $ vendor/bin/rector process web/modules/contrib/[YOUR_MODULE] --dry-run0 -> $ vendor/bin/rector process web/modules/contrib/[YOUR_MODULE] --dry-run1 We would like one Rector rule per deprecation. Some deprecations include updating multiple things and those would be separate rules. To avoid duplication, we have created base classes for simple repeated patterns where possible. These end in $ vendor/bin/rector process web/modules/contrib/[YOUR_MODULE] --dry-run2 and are located in $ vendor/bin/rector process web/modules/contrib/[YOUR_MODULE] --dry-run3. In many of these rules, you will extend the base class, define class properties, add a class comment, and define the definition. Rector supports passing parameters to rules and you can also define your rules in a variety of ways. To avoid confusion for new developers, we're trying to avoid these advanced features so that someone with limited familiarity with the tool can easily determine where things are located and what they are doing. If the copy & paste challenge isn't worth this trade-off, we can re-evaluate it as we go. Suggestions appreciated. Create examplesWe are creating pairs of example files. These should be named the same thing as the deprecation. So, $ vendor/bin/rector process web/modules/contrib/[YOUR_MODULE] --dry-run4 has a $ vendor/bin/rector process web/modules/contrib/[YOUR_MODULE] --dry-run5 example. An example $ vendor/bin/rector process web/modules/contrib/[YOUR_MODULE] --dry-run6 should also be created to show the updated code. You can run Drupal Rector on this file to show the update. Example $ vendor/bin/rector process web/modules/contrib/[YOUR_MODULE] --dry-run4 -> $ vendor/bin/rector process web/modules/contrib/[YOUR_MODULE] --dry-run5 and $ vendor/bin/rector process web/modules/contrib/[YOUR_MODULE] --dry-run6 If you would like to show how the code is used in a class, you can add the class to the appropriate place in the $ vendor/bin/rector process web/modules/contrib/[YOUR_MODULE]0 or $ vendor/bin/rector process web/modules/contrib/[YOUR_MODULE]1 directories. Most of the examples in the example module are $ vendor/bin/rector process web/modules/contrib/[YOUR_MODULE]2 in that they are stand alone classes. Since these classes can use static calls, dependency injection, or traits to get access to services, constants, etc, we have added more details to some class names. For example, $ vendor/bin/rector process web/modules/contrib/[YOUR_MODULE]3 to indicate that the class is not using dependency injection. Example $ vendor/bin/rector process web/modules/contrib/[YOUR_MODULE] --dry-run4 -> $ vendor/bin/rector process web/modules/contrib/[YOUR_MODULE]5 and $ vendor/bin/rector process web/modules/contrib/[YOUR_MODULE]6 Create / Update a configuration fileThe configuration files in $rectorConfig->sets([ Drupal9SetList::DRUPAL_90, Drupal9SetList::DRUPAL_91, Drupal9SetList::DRUPAL_92, Drupal9SetList::DRUPAL_93, ]);6 are broken down by Drupal minor versions. Add your Rector rule to the relevant file. The key is the fully qualified class name of the Rector rule. The key is the yaml null value $ vendor/bin/rector process web/modules/contrib/[YOUR_MODULE]8. Update the index fileThe index file is used in part to provide automated updates to https://dev.acquia.com/drupal9/deprecation_status/errors which is a helpful way to track coverage. The $ vendor/bin/rector process web/modules/contrib/[YOUR_MODULE]9 messages are listed there as well as in the change record comments throughout the Drupal codebase. Pinning dev dependenciesIf there are conflicts with Rector, the package version can be conflicted with 0 on 1.For development, the 2 is on 3 which is 4 and that includes the 4 of all its packages. |