Skip to Main Content
Menu
Close Menu

Adding Drupal Rector to a site

Overview

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.

The --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:

https://github.com/palantirnet/drupal-rector/blob/master/rector-config-docroot-dir.yml

https://github.com/palantirnet/drupal-rector/blob/master/rector-config-web-dir.yml

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
    • php
    • module
    • theme
    • install
    • profile
    • inc
    • engine

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

-Or-

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 --dry-run flag.

vendor/bin/rector process web/modules/contrib/[YOUR_MODULE]

-Or-

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.

See https://github.com/palantirnet/drupal-rector/tree/master/src/Rector/Deprecation.

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.

References

Github Repository
https://github.com/palantirnet/drupal-rector

Packagist page
https://packagist.org/packages/palantirnet/drupal-rector>

Drupal Check
https://github.com/mglaman/drupal-check

Let’s work together.

Have an exceptional idea? Let's talk and see how we can help.
Contact Us