Rector is a reconstructor tool - it does instant upgrades and instant refactoring of your code. Why refactor manually if Rector can handle 80% of the task for you?
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:
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:
- 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...
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
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-runRector will show you diff of files that it would change. To make the changes, drop --dry-run:
vendor/bin/rector process srcNote: rector.php is loaded by default. For different location, use --config option.
<?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/ComplicatedFile.php',
// 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);
};For in-file exclusion, use @noRector \FQN name annotation:
class SomeClass
{
/**
* @noRector
*/
const NAME = '102';
/**
* @noRector
*/
public function foo()
{
/** @noRector \Rector\DeadCode\Rector\Plus\RemoveDeadZeroAndOneOperationRector */
round(1 + 0);
}
}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 FinalizeClassesWithoutChildrenRectorExperimental feature
In default type resolving settings, all docblocks are taken seriously.
<?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();
// [default: false]
$parameters->set(Option::SAFE_TYPES, true);
};E.g. the TypedPropertyRector rule will skip this case, as string is defined only in docblock:
<?php
class ValueObject
{
public $value;
/**
* @param string $value
*/
public function __construct($value)
{
$this->value = $value;
}
}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-diffThis option is useful in CI with pull-requests that only change few files.
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');
};- All Rectors Overview
- Create own Rule
- Generate Rector from Recipe
- How Does Rector Work?
- PHP Parser Nodes Overview
- Add Checkstyle with your CI
You can run Rector on your project using Docker:
docker run --rm -v $(pwd):/project rector/rector:latest process /project/src --set symfony40 --dry-run
# Note that a volume is mounted from `pwd` (the current directory) into `/project` which can be accessed later.Using rector.php:
docker run --rm -v $(pwd):/project rector/rector:latest process /project/app \
--config /project/rector.php \
--autoload-file /project/vendor/autoload.php \
--dry-run- Make sure XDebug is installed and configured
- Add
--xdebugoption when running Rector
Without XDebug, you can use --debug option, that will print nested exceptions output.
Do you use Rector to upgrade your code? Add it here:
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.