Adding Drupal Rector to a site
Drupal Rector is a command-line tool that helps developers update deprecated Drupal code. The tool will report a list of recommended changes and can also update the code.
Installing Drupal Rector
Drupal Rector can be installed in a composer managed Drupal 8 site. Run the following command from the project root directory:
composer require --dev palantirnet/drupal-rector
This command will add Drupal Rector to your 'composer.json' and 'composer.lock' files, download and install the project and its dependencies.
--dev flag is used so that Drupal Rector is not included when a deployment artifact is created.
Configuring Drupal Rector
Drupal Rector is configured with a '/rector.yml' file in the root of your repository.
You can copy one of the sample files:
These only differ in the paths used to define where classes are stored:
parameters: autoload_paths: - 'web/core' - 'web/core/modules' - 'web/modules' - 'web/profiles'
Configuration defaults (Advanced and optional)
The default configuration is set up to:
- Apply all Drupal 8 deprecations
- Scan files with the following extensions
If you would like to add additional sets or exclude certain directories, please see the Rector documentation available at https://github.com/rectorphp/rector. Drupal Rector is built on top of this tool.
Using Drupal Rector to suggest changes
Drupal Rector can be run on a folder or individual file and will output a list of suggested changes.
vendor/bin/rector process web/modules/contrib/[YOUR_MODULE] --dry-run
vendor/bin/rector process web/modules/contrib/[YOUR_MODULE]/src/[YOUR FILE] --dry-run
This command calls
rector with the
process task on the folder or file specified. The
--dry-run option tells Rector not to make changes to files.
You should see output that looks like a Git diff that shows the before and after changes per line with a summary of which Drupal Rector rules were applied.
Testing Drupal Rector
If you would like to test that Drupal Rector is working, you can copy the example module from https://github.com/palantirnet/drupal-rector/tree/master/rector_examples into your modules/custom folder and run the command against this folder.
This example module contains examples of each deprecation that Drupal Rector can help update.
Using Drupal Rector to apply changes
When you have reviewed your changes, you can run the command without the
vendor/bin/rector process web/modules/contrib/[YOUR_MODULE]
vendor/bin/rector process web/modules/contrib/[YOUR_MODULE]/src/[YOUR FILE]
These commands will output the same report noted above and will update the files on your site.
Reviewing and committing your code
You should review the changes and test your code to make sure it still works as expected.
Drupal Rector should be able to make updates for common use cases, but more complex use cases may result in code updates that break functionality. Each Rector rule includes documentation about some of these problem cases.
If you find additional cases that you would like to report or would like to contribute to the project, please visit https://www.drupal.org/project/rector to file an issue.
Identifying all deprecations
Drupal Rector does not fix every deprecation and does not identify deprecations that are not fixed.
You may want to use Drupal Check (https://github.com/mglaman/drupal-check) alongside Drupal Rector to identify deprecated code.