rector/README.md

Rector - Speedup Your PHP Development

Rector helps you with 2 areas - major code changes and in daily work.

• Do you have a legacy code base? Do you want to have that latest version of PHP or your favorite framework? → Rector gets you there with instant upgrade.

• Do you have code quality you need, but struggle to keep it with new developers in your team? Do you wish to have code-reviews for each member of your team, but don't have time for it? → Add Rector to you CI and let it fix your code for you. Get instant feedback after each commit.

It's a tool that we develop and share for free, so you anyone can automate their refactoring.

Hire us to skip learning Rector, AST and nodes, to educate your team about Rectors benefits and to setup Rector in your project - so you can enjoy the 300 % development speed 👍

• Online DEMO
• Explore 500+ Rector Rules

---

Sponsors

Rector grows faster with your help, the more you help the more work it saves you. Check out Rector's Patreon. One-time donations are welcome through PayPal.

Thank you:

Open-Source First

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

It supports all versions of PHP from 5.2 and many open-source projects:

What Can Rector Do for You?

• Upgrade 30 000 unit tests from PHPUnit 6 to 9 in 2 weeks
• Complete @var annotations or parameter/return type declarations
• Complete PHP 7.4 property type declarations
• Upgrade your code from PHP 5.3 to 8.0
• Migrate your project from Nette to Symfony
• Refactor Laravel facades to dependency injection
• And much more...

Install

composer require rector/rector --dev

• Having conflicts during composer require? → Use the Rector Prefixed
• Using a different PHP version than Rector supports? → Use the Docker image

Running Rector

There a 2 main ways to use Rector:

• a single rule, to have the change under control - pick from over 550 rules
• or group of rules called sets - pick from sets

Sets are suitable for open-source projects and design patterns, like .

To use them, create a rector.php in your root directory:

<?php

// rector.php

declare(strict_types=1);

use Rector\Core\Configuration\Option;
use Rector\Php74\Rector\Property\TypedPropertyRector;
use Rector\Set\ValueObject\SetList;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

return static function (ContainerConfigurator $containerConfigurator): void {
    // get parameters
    $parameters = $containerConfigurator->parameters();

    // here we can define, what sets of rules will be applied
    $parameters->set(Option::SETS, [SetList::CODE_QUALITY]);

    // get services
    $services = $containerConfigurator->services();

    // register single rule
    $services->set(TypedPropertyRector::class);
};

Then dry run Rector:

vendor/bin/rector process src --dry-run

Rector will show you diff of files that it would change. To make the changes, drop --dry-run:

vendor/bin/rector process src

Note: rector.php is loaded by default. For different location, use --config option.

Configuration

<?php

// rector.php

declare(strict_types=1);

use Rector\CodeQuality\Rector\If_\SimplifyIfReturnBoolRector;
use Rector\Core\Configuration\Option;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

return static function (ContainerConfigurator $containerConfigurator): void {
    $parameters = $containerConfigurator->parameters();

    // paths to refactor; solid alternative to CLI arguments
    $parameters->set(Option::PATHS, [__DIR__ . '/src', __DIR__ . '/tests']);

    // is there a file you need to skip?
    $parameters->set(Option::EXCLUDE_PATHS, [
        // single file
        __DIR__ . '/src/ComplicatedFile.php',
        // or directory
        __DIR__ . '/src',
        // or fnmatch
        __DIR__ . '/src/*/Tests/*',
    ]);

    // Rector relies on autoload setup of your project; Composer autoload is included by default; to add more:
    $parameters->set(Option::AUTOLOAD_PATHS, [
        // autoload specific file
        __DIR__ . '/vendor/squizlabs/php_codesniffer/autoload.php',
        // or full directory
        __DIR__ . '/vendor/project-without-composer',
    ]);

    // is there single rule you don't like from a set you use?
    $parameters->set(Option::EXCLUDE_RECTORS, [SimplifyIfReturnBoolRector::class]);

    // is your PHP version different from the one your refactor to? [default: your PHP version]
    $parameters->set(Option::PHP_VERSION_FEATURES, '7.2');

    // auto import fully qualified class names? [default: false]
    $parameters->set(Option::AUTO_IMPORT_NAMES, true);

    // skip root namespace classes, like \DateTime or \Exception [default: true]
    $parameters->set(Option::IMPORT_SHORT_CLASSES, false);

    // skip classes used in PHP DocBlocks, like in /** @var \Some\Class */ [default: true]
    $parameters->set(Option::IMPORT_DOC_BLOCKS, false);

    // skip directory/file by rule
    $parameters->set(Option::SKIP, [
        Rector\CodeQuality\Rector\Array_\CallableThisArrayToAnonymousFunctionRector::class => [
            // single file
            __DIR__ . '/src/ComplicatedFile.php',
            // or directory
            __DIR__ . '/src',
            // or fnmatch
            __DIR__ . '/src/*/Tests/*',
        ],
        Rector\CodeQuality\Rector\Array_\ArrayThisCallToThisMethodCallRector::class => [
            // single file
            __DIR__ . '/src/ComplicatedFile.php',
            // or directory
            __DIR__ . '/src',
            // or fnmatch
            __DIR__ . '/src/*/Tests/*',
        ],
    ]);

    // Run Rector only on changed files
    $parameters->set(Option::ENABLE_CACHE, true);
};

Configuring Rectors

Every rector can have its own configuration. E.g. the DowngradeTypedPropertyRector rule will add a docblock or not depending on its property ADD_DOC_BLOCK:

<?php

// rector.php

declare(strict_types=1);

use Rector\DowngradePhp74\Rector\Property\DowngradeTypedPropertyRector;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

return static function (ContainerConfigurator $containerConfigurator): void {
    // Set configuration
    // ...

    // get services
    $services = $containerConfigurator->services();

    // Don't output the docBlocks when removing typed properties
    $services->set(DowngradeTypedPropertyRector::class)
        ->call('configure', [[
            DowngradeTypedPropertyRector::ADD_DOC_BLOCK => false,
        ]]);
};

Ignore Rector Rule in File

For in-file exclusion, use @noRector \FQN name annotation:

<?php

declare(strict_types=1);

class SomeClass
{
    /**
     * @noRector
     */
    public const NAME = '102';

    /**
     * @noRector
     */
    public function foo(): void
    {
        /** @noRector \Rector\DeadCode\Rector\Plus\RemoveDeadZeroAndOneOperationRector */
        round(1 + 0);
    }
}

Run Just 1 Rector Rule

Do you have config that includes many sets and Rectors? You might want to run only a single Rector. The --only argument allows that, e.g.:

vendor/bin/rector process src --set solid --only Rector\SOLID\Rector\Class_\FinalizeClassesWithoutChildrenRector

# or just a short class name
vendor/bin/rector process src --set solid --only FinalizeClassesWithoutChildrenRector

Limit Execution to Changed Files

Execution can be limited to changed files using the process option --match-git-diff. This option will filter the files included by the configuration, creating an intersection with the files listed in git diff.

vendor/bin/rector process src --match-git-diff

This option is useful in CI with pull-requests that only change few files.

Symfony Container

To work with some Symfony rules, you now need to link your container XML file

<?php

// rector.php

declare(strict_types=1);

use Rector\Core\Configuration\Option;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

return static function (ContainerConfigurator $containerConfigurator): void {
    $parameters = $containerConfigurator->parameters();

    $parameters->set(
        Option::SYMFONY_CONTAINER_XML_PATH_PARAMETER,
        __DIR__ . '/var/cache/dev/AppKernelDevDebugContainer.xml'
    );
};

More Detailed Documentation

• All Rectors Overview
• Create own Rule
• Generate Rector from Recipe
• How Does Rector Work?
• PHP Parser Nodes Overview
• Add Checkstyle with your CI

How to Contribute

See the contribution guide.

Run Rector in Docker

You can run Rector on your project using Docker. To make sure you are running latest version, use docker pull rector/rector.

Note that Rector inside Docker expects your application in /project directory - it is mounted via volume from the current directory ($pwd).

docker run --rm -v $(pwd):/project rector/rector:latest process src --set symfony40 --dry-run

Using rector.php config:

docker run --rm -v $(pwd):/project rector/rector:latest process src \
    --config rector.php \
    --dry-run

Debugging

1. Make sure XDebug is installed and configured
2. Add --xdebug option when running Rector

Without XDebug, you can use --debug option, that will print nested exceptions output.

Community Packages

Do you use Rector to upgrade your code? Add it here:

• palantirnet/drupal-rector by Palantir.net for Drupal
• sabbelasichon/typo3-rector for TYPO3

Known Drawbacks

How to Apply Coding Standards?

Rector uses nikic/php-parser, that build on technology called abstract syntax tree (AST). AST doesn't care about spaces and produces mall-formatted code in both PHP and docblock annotations. That's why your project needs to have coding standard tool and set of rules, so it can make refactored nice and shiny again.

Don't have any coding standard tool? Add ECS and use prepared ecs-after-rector.php set.