Config Configuration

Reference of RectorConfig::configure() options. Sets, levels and CLI flags have their own pages, this one covers everything else.

Provide Config

By default, Rector picks rector.php in your project root as the configuration file. To change that, use:

vendor/bin/rector process --config rector-custom-config.php

Pro tip: You can see current default values in the Rector config file:

  • on Github: config/config.php
  • or locally in: /vendor/rector/rector/config/config.php

Sets, Levels and Rules


Spacing and Indents

Default formatting is 4 spaces and UNIX newlines. You can override:

use Rector\Config\RectorConfig;

return RectorConfig::configure()
    ->withIndent(indentChar: ' ', indentSize: 4);

Paths to Process

Define which directories or files Rector should refactor:

<?php

use Rector\Config\RectorConfig;

return RectorConfig::configure()
    ->withPaths([
        __DIR__ . '/src',
        __DIR__ . '/tests',
        __DIR__ . '/packages/Domain',
    ]);

You can also include all the *.php files from root directory:

use Rector\Config\RectorConfig;

return RectorConfig::configure()
    ->withPaths([
        __DIR__ . '/src',
    ])
    ->withRootFiles();

Skip Paths, Files and Rules

To exclude directories or files from processing, use ->withSkip(). It accepts absolute paths, single files and * masks:

use Rector\Config\RectorConfig;

return RectorConfig::configure()
    ->withPaths([
        __DIR__ . '/src',
    ])
    ->withSkip([
        // skip an exact directory
        __DIR__ . '/src/Legacy',

        // skip a single file
        __DIR__ . '/src/Bootstrap/container.php',

        // skip any "Fixture" directory, anywhere in the paths
        '*/Fixture/*',

        // skip files by name mask
        '*/*.generated.php',
    ]);

Skip a rule everywhere:

use Rector\Config\RectorConfig;

return RectorConfig::configure()
    ->withSkip([
        SomeRule::class,
    ]);

Skip a rule for specific files only:

use Rector\Config\RectorConfig;

return RectorConfig::configure()
    ->withSkip([
        SomeRule::class => [
            __DIR__ . '/src/SpecialCase.php',
        ],
    ]);

Skips that never match can be reported, see Reporting Unused Skips.


File Extensions

By default, Rector processes only .php files. To add more extensions, use:

use Rector\Config\RectorConfig;

return RectorConfig::configure()
    ->withFileExtensions(['php', 'phtml']);

PHP Version

Rector only uses PHP features compatible with your code. That means it will not add attributes, unless you're at least on PHP 8.

The best practise is to let Rector pick up the PHP version from composer.json:

{
    "require": {
        "php": "^7.4"
    }
}

If it's not there, Rector looks into other places, in this order:

  • PHP version defined in rector.php
  • composer.json require of PHP
  • composer.json config platform of PHP
  • the current PHP version runtime

It's very rare to use different PHP version than one provided by composer.json, as it might use newer syntax and break your code. If you still need to force a different version, you can override it manually at your own risk:

use Rector\ValueObject\PhpVersion;

return RectorConfig::configure()
    ->withPhpVersion(PhpVersion::PHP_81);

Parallel Execution

Rector runs in parallel by default. Tune it or turn it off:

use Rector\Config\RectorConfig;

return RectorConfig::configure()
    ->withParallel(timeoutSeconds: 120, maxNumberOfProcess: 32, jobSize: 16);
    // or
    ->withoutParallel();

When to change which value is in Troubleshooting Parallel.


Cache & Temp Directories

By default, Rector uses sys_get_temp_dir() . '/rector_cached_files' path to store cache files. E.g. to verify if files were changed since last run, to run only on new or changed files. You can customize it:

use Rector\Config\RectorConfig;

return RectorConfig::configure()
    ->withCache(__DIR__ . '/var/rector');

On CI, persist that directory between jobs, see Run in CI.


Autoloading & Bootstrap

Rector loads vendor/autoload.php by default. For code outside composer autoload use withAutoloadPaths(), for constants and custom autoloaders use withBootstrapFiles(). Both are explained in Static Reflection and Autoload.


Empower Rector to change public and non-final elements

By default, some Rector rules change types on private and final classes. Why? Because these classes and properties cannot be used by its children. Public and non-final elements can be used anywhere, e.g. adding a property type declaration can be risky.

Read more in Why Final Classes make Rector and PHPStan more powerful.

If you feel confident in your codebase and want to make it even more reliable, you can empower Rector to run these rules on public and non-final elements as well:

use Rector\Config\RectorConfig;

return RectorConfig::configure()
    ->withTreatClassesAsFinal();

Nicer Fluent Call output

By default, php-parser prints new fluent calls in a single line:

$some->select(...)->where(...)->getResult(...);

If you prefer per-line method call:

$some->select(...)
    ->where(...)
    ->getResult(...);

You can enable it:

use Rector\Config\RectorConfig;

return RectorConfig::configure()
    ->withFluentCallNewLine();

PHPStan integration

Rector load phpstan.neon and phpstan.neon.dist by default if they exist in your project root. Extensions are ignored on purpose, as some of them run project code (e.g. Doctrine) and breaks idea of static analysis. Most extensions do not bring any value to Rector, as Rector works mostly with native type declaration.

Still, there is a way to load PHPStan extension configs, in case they are needed for your specific Rector rule use case:

use Rector\Config\RectorConfig;

return RectorConfig::configure()
    ->withPHPStanConfigs([
        __DIR__ . '/config/custom-phpstan-extension.neon',
    ]);

Symfony Integration

Some Symfony Rector rules require container metadata. Provide Symfony Container to let Rector access services (name and type mostly) and route definitions.

If your Symfony project was not run yet, dump the container first:

bin/console debug:container

Use in config:

use Rector\Config\RectorConfig;

return RectorConfig::configure()
    // in XML
    ->withSymfonyContainerXml(
        __DIR__ . '/var/cache/dev/App_KernelDevDebugContainer.xml'
    );

    // or PHP (depending on version)
    ->withSymfonyContainerPhp(
        __DIR__ . '/var/cache/dev/App_KernelDevDebugContainer.php'
    );