Skip to main content

Rector - instant upgrades and automated refactoring

https://github.com/rectorphp/rector

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

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

What Rector does​

Rector automatically refactors your PHP and Drupal code to:

  • Fix deprecated Drupal APIs - prepares code for Drupal major version upgrades
  • Modernize PHP syntax - rewrites code to use PHP 8.4 language features
  • Keep code consistent - applies the same refactoring rules across the codebase

When to use Rector​

  • Before Drupal upgrades - run before upgrading Drupal major versions to fix deprecations
  • During development - run periodically (weekly/monthly) to catch deprecations early
  • In code review - it runs in the CI pipeline as one of the code quality checks
  • When refactoring legacy code - to modernize older codebases in bulk
note

Rector is often used ad hoc to perform bulk refactoring.

In Vortex, it is integrated as a regular code quality tool that can be run at any time to check for deprecated code and automatically fix issues. This keeps the codebase up-to-date continuously rather than waiting for major upgrades.

Usage​

Check for violations​

ahoy lint-be

Fix violations​

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

Configuration​

See configuration reference.

All global configuration takes place in the rector.php file.

Targets include custom modules and themes, settings and tests.

Config sets​

Rector provides config sets that enable or disable rules in bulk.

Vortex enables the PHP 8.4 sets and the Drupal sets from Drupal Rector. The Drupal sets are resolved from the installed drupal/core version, so the rules track core upgrades without changes to rector.php.

The config sets are meant to be adjusted per-project as needed. A full list of available config sets can be found on the Rules overview page.

Ignoring​

See more on the Ignoring Rules Or Paths page.

Ignoring rules globally takes place in the rector.php file:

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

To ignore all Rector rules within a file:

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

To ignore a specific rule within a file:

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

Rector does not support ignoring of the code blocks.

Cache management​

Rector caches parsed file information and analysis results in the system temp directory (/tmp/rector_cached_files) to speed up subsequent runs by reusing results for unchanged files.

Clear the cache after changing the rector.php configuration (rules, skip list, or paths), after updating the rector/rector or palantirnet/drupal-rector packages, after switching git branches with different Rector configurations, or when results look stale.

To clear the cache and check for violations:

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

To clear the cache and apply changes:

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

Ignoring fail in continuous integration pipeline​

This tool runs in the continuous integration pipeline by default and fails the build if there are any violations.

Set the VORTEX_CI_RECTOR_IGNORE_FAILURE environment variable to 1 to ignore failures. The tool will still run and report violations, if any.