Guide · Open source

How to use Rector: install, dry-run and apply PHP upgrades

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Rector is a command-line tool that scans PHP code and rewrites it using a set of rules, which can move a codebase toward newer PHP and framework versions and clean up code quality issues. This guide is for PHP developers and teams who want to try it safely on a project. After reading, you will be able to install Rector, configure a rules file, preview changes before applying them, and know what to check afterward.

Rectorrectorphp/rector · ★ 10.5k · MIT Install options & downloads

Quick start

1Check prerequisites. Confirm PHP and Composer are installed on your machine.
2Install Rector. Run composer require rector/rector --dev in your project root.
3Create rector.php. Add a rector.php file in the root directory and register the rules or sets you want.
4Dry run. Run vendor/bin/rector src --dry-run and review the diff of proposed changes.
5Apply changes. Run vendor/bin/rector src once you are satisfied with the diff.
6Format and check. Run a coding standard tool on the changed files and check any PHP and HTML mixed files manually.

What Rector needs before you install it

Rector is a PHP tool installed through Composer, so you need both PHP and Composer on the machine where you run it. It only works on PHP code, so it is not a fit for non-PHP projects.

PHP
Composer

Install Rector as a dev dependency

Install Rector into your project as a development dependency with Composer. This keeps it out of your production requirements.

composer require rector/rector --dev

Create a rector.php configuration file

Rector can be used in two main ways: a single rule, so you keep the change under control, or a group of rules called sets. Create a rector.php file in your root directory. The example below registers one rule and enables two prepared sets. Adjust the rule and set choices to match your project.

Run Rector once to generate or check the setup, then edit the file as needed.

Use a single rule when you want tightly controlled changes.
Use sets when you want a prepared group of rules applied together.

use Rector\Config\RectorConfig;
use Rector\TypeDeclaration\Rector\Property\TypedPropertyFromStrictConstructorRector;

return RectorConfig::configure()
    // register single rule
    ->withRules([
        TypedPropertyFromStrictConstructorRector::class
    ])
    // here we can define, what prepared sets of rules will be applied
    ->withPreparedSets(
        deadCode: true,
        codeQuality: true
    );

Preview changes with a dry run before applying them

Always start with a dry run. Rector shows a diff of the files it would change, but does not modify anything. Review the diff before moving on.

This is the approach the project recommends, since the README advises checking results before applying them.

Dry run prints the diff of files that would change.
Nothing on disk changes during a dry run.

vendor/bin/rector src --dry-run

Apply the changes to your code

When the diff looks right, run the same command without --dry-run. Rector then makes the changes to the files in the folder you pass in. Use version control so you can review and revert the result.

vendor/bin/rector src

Debug problems and clean up formatting

If Rector fails on a file, add --debug to print nested exception output. For Xdebug, the README says to make sure Xdebug is installed and configured, then add the --xdebug option.

Rector's output is built on an abstract syntax tree, which does not keep spacing. The README says the result can be poorly formatted, and that your project needs a coding standard tool to tidy it. The maintainers say they use ECS with a setup linked from the rector-src repository. Files that mix PHP and HTML may also need manual checking after changes.

Run with --debug to see nested exceptions.
Run with --xdebug if you use Xdebug.
Run a coding standard tool such as ECS after applying changes.
On Windows, the README suggests using cmd or bash rather than PowerShell 7 (pwsh) if parallel mode causes problems.

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

What people use it for

Moving an older PHP codebase toward a newer PHP version, using rules that cover PHP 5.3 to 8.5 according to the README.
Applying Symfony, PHPUnit or Doctrine upgrade rules to a project that uses those frameworks.
Running Rector in continuous integration so code quality is checked automatically.
Applying a single rule to one folder to make a narrow, reviewable change.

Frequently asked questions

Is Rector free to use?

Rector is released under the MIT licence, as listed on its project page. The README also mentions commercial support offered by the maintainers, which is optional.

What do I need to install Rector?

The README lists PHP and Composer as prerequisites. You install Rector with composer require rector/rector --dev.

How do I see what Rector will change without editing files?

Run vendor/bin/rector src --dry-run. Rector shows a diff of the files it would change and does not modify them.

Why does Rector output look badly formatted?

Rector uses an abstract syntax tree, which does not keep spacing. The README says to use a coding standard tool afterward to clean up the output.

Can I use Rector with Symfony, PHPUnit or Doctrine?

The README links to separate Rector packages for Symfony, PHPUnit and Doctrine, which provide framework-specific upgrade rules.

How does Rector compare with PHPStan, Psalm or PHP-CS-Fixer?

Rector rewrites code using rules, while PHPStan and Psalm are static analysis tools and PHP-CS-Fixer focuses on code style. This source does not compare them in detail, so check each project's documentation for a full comparison.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Rector suits PHP teams that want to upgrade an older codebase or automate code quality fixes and are willing to review diffs and run a formatter afterward. It is a poor fit for non-PHP projects, for teams that want changes applied with no review, or for projects with no coding standard tool.

Install options & downloads