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 pre-configured Rector configuration for Drupal projects. The configuration is based on the configuration provided by Drupal Rector.

What is Rector?​

Rector automatically refactors your PHP and Drupal code to:

  • Fix deprecated Drupal APIs - Prepares code for Drupal major version upgrades
  • Modernize PHP syntax - Leverages PHP 8.3 language features
  • Improve code quality - Enhances readability and maintainability
  • Reduce technical debt - Automated cleanup and optimization

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
  • Code Reviews: Include in CI pipeline for automated quality checks
  • Refactoring Legacy Code: When modernizing older codebases
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 allows us to keep the codebase up-to-date continuously rather than waiting for major upgrades.

Usage​

Check for violations​

ahoy lint-be

Fix violations​

ahoy lint-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 functionality that allows to enable/disable rules in bulk.

Vortex provides the config sets for Drupal 8, 9 and 10 deprecated code and code style fixes.

The config sets are meant to be adjusted per-project as needed.

A full list of available config sets can be found in the Rules overview page.

Ignoring​

See more on 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​

How caching works​

Rector caches parsed file information and analysis results to speed up subsequent runs:

  • Cache location: /tmp/_rector (system temp directory)
  • Stores: Parsed AST, file metadata, rule analysis results
  • Performance: Subsequent runs are ~40-60% faster by reusing results for unchanged files

When to clear cache​

Clear Rector cache in these situations:

  1. After changing rector.php configuration

    • Added/removed rules
    • Changed skip list
    • Modified paths

  2. After updating Rector or Drupal Rector packages

    composer update rector/rector palantirnet/drupal-rector

  3. When seeing unexpected behavior

    • Rules not applying when they should
    • Stale results
    • False negatives in CI

  4. After switching git branches with different Rector configurations

Clear cache​

To clear cache and check for violations:

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

To clear cache and apply changes:

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

Ignoring fail in continuous integration pipeline​

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

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