Rector
- Neill Magill
New in ExamSys 7.7.0
Rector is a tool we are using to help us upgrade ExamSys for new versions of PHP. It makes automatic changes to the code based on the rules we have configures it to use.
For the PHP rules these will very often be converting code to use new language features introduced in that version of PHP.
Rector is installed using composer, it will be installed automatically then you initialise a Behat or PHPUnit site.
From the root directory of ExamSys you can run it without it making any changes using:
vendor/bin/rector process --dry-runor making changes using:
vendor/bin/rector processRector is configured via the rector.php file in the root directory of ExamSys
Code we write must meet the standards that our Rector configuration has declared.
Using Rector to upgrade ExamSys for a new version of PHP
When using Rector to upgrade ExamSys for a new version of PHP our aim should be to step up versions with reasonably small sets of automatic changes.
General steps
Update the Rector configuration
Do a dry run and sense check what you see
Modify the configuration until you have a set you are able to review
Commit the configuration changes
Do a Rector run that updates ExamSys code
Code review the changes it makes yourself
Run Behat, Code checker and PHPUnit
Commit the changes if you are happy with them
Make any manual modifications required to conform with the ExamSys coding style, or fix issues you noticed during your review or from the automatic tests.
Do a dry run of Rector to verify that it will not make further changes
Commit the changes
Configuration for PHP upgrades
In the configuration file there will be a call to ->withPhpSets() this should be modified so that we bump it at most by a single version of PHP at one time, for example withPhpSets(php81: true) to withPhpSets(php82: true).
If we find that there are large numbers of changes we can use the dry run to temporarily remove some rules from processing using the ->withSkip()method. You will be able to find the generalised name of rules when doing a dry run. We must document the reason we have any skipped rules in the configuration:
use Rector\Php71\Rector\FuncCall\RemoveExtraParametersRector;
use Rector\Php80\Rector\Class_\ClassPropertyAssignToConstructorPromotionRector;
...
->withSkip([
// Some function calls are incorrectly modified with this rule,
// we should look for ways to correct this in the future.
RemoveExtraParametersRector::class,
// The following rules have been temporarily excluded to reduce the
// size of the change we are reviewing. We will stop skipping them in
// new commits soon:
ClassPropertyAssignToConstructorPromotionRector::class,
])We should skip rules if:
They break our code
As a way to make the number of automatic changes into an easier to review number. When we do this we would expect further changes to remove those rules
Structure of a Rector change
When making changes via Rector we require that there are either two or three commits. The commits must be:
The Rector configuration change
The changes made by Rector (you must not include any manual modifications in this commit)
Any manual changes you need to make to fix any code style or other issues created by the automatic changes
This structure is required so that we can adequately review what has happened during the change.