Skip to main content
Version: v1

Rector - instant upgrades and automated refactoring

The Rector project describes the tool as follows:

Rector instantly upgrades and refactors the PHP code of your application.

Every Drupal major release removes the APIs that the previous major release deprecated. Rector rewrites your code to replace them and moves it onto PHP 8.4 language features. It applies each refactoring across the whole codebase at once. Because Rector runs in every ahoy lint-be run and every CI build, the deprecations Drupal Rector covers are already fixed when a major upgrade starts.

Vortex comes with a pre-configured Rector configuration for Drupal projects, based on the configuration provided by Drupal Rector.

This page is for developers who keep custom code current with Drupal and PHP. It shows how to run Rector and clear its cache, which rule sets Vortex enables and how to skip a rule or a file.

Vortex runs Rector as a regular code quality check:

  • ahoy lint-be reports the code Rector would change.
  • ahoy lint-be-fix applies the changes.
  • The lint job in CI fails while any change is pending.

Run ahoy lint-be-fix before a Drupal major upgrade to clear the remaining deprecations, and when you modernize legacy code in bulk.

Usage​

Check for violations​

Both commands run Rector as a dry run. The Ahoy command runs it last, after PHPCS and PHPStan. The Docker Compose command runs Rector alone. To check for code that Rector would change, run 1 of the following commands:

ahoy lint-be

Confirm that Rector found nothing to change: the output ends with [OK] Rector is done!. When Rector would change files, it prints a diff for each file and exits with code 2, which fails the check.

Fix violations​

To apply the changes, run 1 of the following commands:

# Fix all back-end lint issues (Rector, then PHPCBF).
ahoy lint-be-fix

Cache management​

Rector caches parsed files and analysis results in the system temp directory, /tmp/rector_cached_files inside the CLI container, so later runs reuse the results for files that haven't changed.

Clear the cache in any of the following cases:

  • After you change the rector.php configuration, such as its rules, skip list or paths
  • After you update the rector/rector or palantirnet/drupal-rector packages
  • After you switch to a Git branch with a different Rector configuration
  • Whenever the results look stale

To clear the cache and check for violations, run 1 of the following commands:

ahoy cli vendor/bin/rector process --clear-cache --dry-run

To clear the cache and apply changes, run 1 of the following commands:

ahoy cli vendor/bin/rector process --clear-cache

Convert procedural hooks to hook classes​

Drupal runs hooks implemented as methods of a class in a module's or theme's src/Hook directory. A #[Hook] attribute on each method names the hook it implements. The ys_demo module and the custom theme that Vortex ships already use these classes.

Drupal Rector's HookConvertRector rule moves procedural hook functions into these classes. rector.php leaves the rule out because the rule writes each class straight to disk. A dry run writes nothing, so ahoy lint-be would never show the new class. Run the conversion once, as its own Rector pass.

The rule converts a function only when its docblock reads Implements hook_.... Install-time hooks, such as hook_install() and hook_schema(), stay as functions.

To convert the hooks in your custom modules and themes:

  1. In each hook function's docblock, replace Implements template_preprocess_ with Implements hook_preprocess_. For example, Implements template_preprocess_html(). becomes Implements hook_preprocess_html()..

  2. Fix the deprecations in your code:

    ahoy lint-be-fix

    Rector doesn't process the new class in the run that writes it. Fix the deprecations first, or the deprecated calls move into the class unfixed.

  3. Convert the hooks with the configuration that Drupal Rector ships:

    ahoy cli vendor/bin/rector process \
    --config=vendor/palantirnet/drupal-rector/rector-hook-convert.php \
    web/modules/custom web/themes/custom

    For each .module, .theme or .inc file with hooks, Rector writes a class to src/Hook, such as src/Hook/YsDemoHooks.php for ys_demo.module.

  4. Reformat the new classes to the project's coding standards:

    ahoy lint-be-fix
  5. Move each helper function that a hook calls, such as _your_site_theme_preprocess_navigation(), into the hook class as a protected method.

  6. Delete the code that Rector leaves behind:

    • Each function marked #[LegacyHook]. It calls the new method for Drupal versions before 11.1, and Vortex requires Drupal 11.4.
    • Each .module or .theme file that holds only its @file docblock and use statements. Move any constant or include it still holds before you delete it.
    • The hook class entries that Rector adds to <module>.services.yml, and the <theme>.services.yml file it creates in a theme. Drupal registers every hook class as an autowired service.
  7. Rebuild the caches, so Drupal registers the hook classes in place of the deleted functions:

    ahoy drush cr
  8. Run ahoy lint-be and fix what it reports.

Rector keeps the \Drupal::service() calls inside the moved methods. To inject the services instead, add them as type-hinted constructor arguments.

Configuration​

See the Rector documentation.

All global configuration lives in the rector.php file.

Rector processes the following paths, which withPaths() in rector.php lists:

  • web/modules/custom
  • web/themes/custom
  • web/sites/default/settings.php
  • web/sites/default/includes
  • tests

withPaths() leaves out scripts, which PHPCS and PHPStan check.

Config sets​

Rector provides config sets that each turn on a group of related rules. Vortex enables the following sets:

  • The PHP sets up to the lowest PHP version that the require.php constraint in composer.json allows, through withPhpSets(), which reads that constraint when called without an argument. The shipped constraint, >=8.4, resolves to PHP 8.4. The sets follow composer.json, so a PHP version change needs no edit to rector.php.
  • The Drupal sets from Drupal Rector, turned on by withComposerBased() and resolved from the installed drupal/core version, so the rules track core upgrades.
  • The codeQuality, codingStyle, deadCode, privatization and typeDeclarations prepared sets. The codeQuality set adds declare(strict_types=1) to type-safe files.
  • The Behat attribute sets, which convert Behat annotations to PHP 8 attributes. They ship only when Behat is selected during installation.

On top of the sets, rector.php adds YieldDataProviderRector when PHPUnit is selected. The rule turns array-returning data providers into generators. withImportNames() is called with importNames: FALSE, so Rector adds no use statements to the files it changes.

To adjust the sets, edit the withPhpSets(), withAttributesSets() and withPreparedSets() calls in rector.php. The Set Lists page describes the available sets, and the Find a Rector rule page lists the individual rules.

Ignore violations​

For every way to skip a rule or a path, see the Rector configuration documentation.

To skip a rule across the project, add it to withSkip() in the rector.php file:

->withSkip([
SimplifyIfReturnBoolRector::class,
])

The shipped withSkip() list already skips the following 12 rules everywhere, based on the project's coding standards:

  • ArrayToFirstClassCallableRector
  • CatchExceptionNameMatchingTypeRector
  • ChangeSwitchToMatchRector
  • InlineArrayReturnAssignRector
  • NewlineAfterStatementRector
  • NewlineBeforeNewAssignSetRector
  • NewlineBetweenClassLikeStmtsRector
  • PrivatizeFinalClassMethodRector
  • PrivatizeFinalClassPropertyRector
  • PrivatizeLocalGetterToPropertyRector
  • RemoveAlwaysTrueIfConditionRector
  • SimplifyEmptyCheckOnEmptyArrayRector

The list skips RemoveUnusedPublicMethodParameterRector for the src/Hook classes of custom modules and themes, and StringClassNameToClassConstantRector for the settings includes. The list also skips the vendor and node_modules directories.

To skip all Rector rules for a file, add its path to withSkip():

->withSkip([
'file.php',
'*/other_file.php',
])

To skip a specific rule for a file, map the rule to the file's path in withSkip():

->withSkip([
SimplifyIfReturnBoolRector::class => ['file.php'],
])

Rector doesn't support ignoring code blocks.

Continuous integration​

Rector runs in the lint job of the continuous integration pipeline and fails the build on violations.

Ignore failures​

To let the build pass anyway, set the VORTEX_CI_RECTOR_IGNORE_FAILURE CI variable to 1. Rector still runs and prints the changes it would make in the job log, so you can see what you're letting through.

➡️ See Continuous integration > Ignore tool failures