Upgrade your project to PHP 8.2 with Rector

I wanted to upgrade a project to PHP 8.2 and figured I could use Rector for this.

Not only was that the case, but I also completely underestimated how easy it was going to be.

What is Rector?

Rector is a free and open-source tool written in PHP allowing you to automate various refactoring tasks. It analyses your code and applies whatever rules you've specified in its configuration. It is also possible to create your own rules.

How to upgrade your project to PHP 8.2

First, install Rector as a development dependency:

$ composer require --dev rector/rector

Then, generate the rector.php configuration file at the root of your project:

$ ./vendor/bin/rector init

Open that file and replace its content with the following:

<?php

declare(strict_types=1);

use Rector\Config\RectorConfig;
use Rector\Set\ValueObject\LevelSetList;

return static function (RectorConfig $rectorConfig): void {
    $rectorConfig->sets([LevelSetList::UP_TO_PHP_82]);
};

Perform a dry run to check what changes Rector is about to make (the below analyses the app folder as an example):

$ ./vendor/bin/rector process app --dry-run

Apply the changes if you're happy with them:

$ ./vendor/bin/rector process app

You can also specify the paths to analyse in the configuration file directly:

<?php

declare(strict_types=1);

use Rector\Config\RectorConfig;
use Rector\Set\ValueObject\LevelSetList;

return static function (RectorConfig $rectorConfig): void {
    $rectorConfig->paths([
        __DIR__ . '/app',
        // ...
    ]);

    $rectorConfig->sets([LevelSetList::UP_TO_PHP_82]);
};

And then simply run:

$ ./vendor/bin/rector process

What's happening under the hood?

In the above, the UP_TO_PHP_82 constant means that not only the rules to upgrade from PHP 8.1 to PHP 8.2 were applied, but so did those from PHP 8.0 to PHP 8.1, as well as all the other versions' down to PHP 5.2.

In other words, you can bring an entire code base from PHP 5.2 to the latest version with a single command, using predefined rulesets provided by Rector.

But there's more – you can check the available rules and their description here, which go way beyond version-related changes. And, as mentioned earlier, you can also create your own rules if need be.

Closing thoughts

Rector has been on my radar for a while and I even used it a few times before, yet I'm still surprised by how powerful it is.

While it seems to be getting a little more traction recently, along with other static analysis tools like PHPStan, it is still very much underused. One of the reasons is probably that developers are unaware of its potential, of which the above is just a taste.

There is a book covering Rector in depth, which I'm planning on reading soon.