Introducing Sulu Rector
Some weeks ago, we attended the hackday of our Partner MASSIVE ART Webservices. For this hackday I focused on implementing Rector into the Sulu ecosystem.
What is Rector?
Rector is a CLI command to automate library and PHP version upgrades. Rector ships with many rules to upgrade, for example PHP, Symfony, PHPUnit and Doctrine versions. We are already using Rector in our own projects, and we used it for the Sulu 2.4 release to upgrade a no-longer-maintained library (goodby-csv) to support PHP 8.1.
The aim of rector is to automate 90% of the upgrade job for a library, so that a developer can concentrate on the important 10% of difficult cases.
What will Sulu Rector do?
Sulu Rector will provide rules to upgrade the PHP code of your project to the version you want to upgrade to. As an example, Sulu will support with Sulu 2.5 the new Symfony 6 version. To make this possible, some return types need to be added. If for example somebody did overwrite the `User::getRoles()` method in their project, they now need to add an array return type to that method (`User::getRoles(): array`).
And this is the kind of task that Sulu Rector will automate.
How it can be used?
To use Sulu Rector takes minutes. First, you install Rector and the Sulu Rector package via composer:
composer require rector/rector --devcomposer require sulu/sulu-rector --dev
Then in your project root directory, create a `rector.php` file with the following configuration:
<?php
use Rector\Sulu\Set\SuluLevelSetList;
use Rector\Config\RectorConfig;
return static function (RectorConfig $rectorConfig): void {
$rectorConfig->sets([
SuluLevelSetList::UP_TO_SULU_25,
]);
};
After this you can apply the upgrade rules via the vendor/bin/rector process command.
How does it work?
Rector itself is based on rules. The Sulu Rector repository will provide upgrade rules for every version in its configuration files. A rule adding a return type for the above example with getRoles looks like the following:
<?php
use PHPStan\Type\ArrayType;
use Rector\Config\RectorConfig;
use Rector\TypeDeclaration\Rector\ClassMethod\AddReturnTypeDeclarationRector;
use Rector\TypeDeclaration\ValueObject\AddReturnTypeDeclaration;
return static function (RectorConfig $rectorConfig): void {
$rectorConfig->ruleWithConfiguration(
AddReturnTypeDeclarationRector::class,
[
// @see https://github.com/sulu/sulu/pull/6582
new AddReturnTypeDeclaration(
'Sulu\Bundle\SecurityBundle\Entity\User',
'getRoles',
new ArrayType(new IntegerType(), new StringType()),
),
],
);
};
So in future, every required and recommended (deprecated) change should provide upgrade rules. With the +500 rules already provided by the Rector core and the possibility of creating your own rector rules – it should be possible to automate most of our upgrade changes.
Your help is welcome
There will always be cases were Sulu Rector cannot automate something. If you stumble over something in an upgrade which could be automated and is not yet part of the Sulu Rector rulset, please create an issue or a pull request on the Github Sulu Rector Repository. This way we can work together to make Sulu upgrades easier, step by step.
Big Thanks to Tomas Votruba
Tomas Votruba is the person behind Rector and I want to thank him not only for the great tool, but also for supporting us to set up the entire Sulu Rector repository. We can be sure that Sulu Rector is following the best practices of Rector.
Find out more about Rector
- See the documentation How does Rector work.
- Dive under the the hood to find out how it works with PHP Parser in the book Rector - The Power of Automated Refactoring.
What is coming next?
We got great feedback about dropping <= PHP 7.4 and Symfony 4.4, so we are currently finishing the work on Sulu 2.5 to support Symfony 6. In addition, we are working on new Block features, 2FA authentication and password policies for the Sulu admin. We are planning to release an alpha version for 2.5 soon.
As always, we are happy to hear your feedback about newly released features and bug fixes. Feel free to create an issue or a discussion on GitHub for bugs and feature requests. You can also contact us via Slack or our website anytime.
