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 anyone can automate their refactoring.

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

Open-Source First

Rector instantly upgrades and refactors the PHP code of your application. It supports all versions of PHP from 5.3 and major open-source projects:

What Can Rector Do for You?

• Complete 2800 @var types in 2 minutes
• Upgrade 30 000 unit tests from PHPUnit 6 to 9
• Complete PHP 7.4 Property Types
• Migrate from Nette to Symfony
• Refactor Laravel Facades to Dependency Injection
• And much more...

Documentation

• Explore 450+ Rector Rules
• How Does Rector Work?
• PHP Parser Nodes

Advanced

• Auto Import Names
• How to Ignore Rule or Paths
• Static Reflection and Autoload
• How to Configure Rule
• How to Generate Configuration file

Contributing

• How to add Test for Rector Rule
• How to work with Doc Block and Comments
• How to Create New Rector Rule

Install

composer require rector/rector --dev

• Having conflicts during composer require? → Use the Rector Prefixed with PHP 7.1+ version
• 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
• or group of rules called sets

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

vendor/bin/rector init

And modify it:

// rector.php
use Rector\Php74\Rector\Property\TypedPropertyRector;
use Rector\Set\ValueObject\SetList;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

return static function (ContainerConfigurator $containerConfigurator): void {
    // here we can define, what sets of rules will be applied
    // tip: use "SetList" class to autocomplete sets
    $containerConfigurator->import(SetList::CODE_QUALITY);

    // register single rule
    $services = $containerConfigurator->services();
    $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

// rector.php
use Rector\Core\Configuration\Option;
use Rector\Core\ValueObject\PhpVersion;
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 your PHP version different from the one your refactor to? [default: your PHP version], uses PHP_VERSION_ID format
    $parameters->set(Option::PHP_VERSION_FEATURES, PhpVersion::PHP_72);

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

    // Path to phpstan with extensions, that PHPSTan in Rector uses to determine types
    $parameters->set(Option::PHPSTAN_FOR_RECTOR_PATH, getcwd() . '/phpstan-for-config.neon');
};

How to Contribute

See the contribution guide.

Debugging

You can use --debug option, that will print nested exceptions output:

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

Or with Xdebug:

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

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

To assist with simple debugging Rector provides a 2 helpers to pretty-print AST-nodes:

use PhpParser\Node\Scalar\String_;

$node = new String_('hello world!');

// prints node to string, as PHP code displays it
print_node($node);

// dump nested node object with nested properties
dump_node($node);
// 2nd argument is how deep the nesting is - this makes sure the dump is short and useful
dump_node($node, 1);

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, built on technology called an abstract syntax tree (AST). An AST doesn't know about spaces and when written to a file it produces poorly formatted code in both PHP and docblock annotations. That's why your project needs to have a coding standard tool and a set of formatting rules, so it can make Rector's output code nice and shiny again.

We're using ECS with this setup.