README

silverstripe-rector

A developer utility for automatically upgrading deprecated code for Silverstripe CMS

WIP currently collecting ideas what to automate

About rector

rector is a tool for automatic code upgrades and refactorings. See rector homepage for more information.

Installation

This module is installable via composer. As rector uses phpstan, it's a good idea to install syntro/silverstripe-phpstan, too.

composer require syntro/silverstripe-phpstan --dev
composer require wernerkrauss/silverstripe-rector
vendor/bin/rector init

Create a basic phpstan.neon file in your project root:

includes:
    - vendor/syntro/silverstripe-phpstan/phpstan.neon

This will add all requirements and create a file called rector.php in your project root. You'll need to adjust it, e.g. add the code directories to upgrade and the rules to use.

A basic rector config can look like

<?php

declare(strict_types=1);

use Netwerkstatt\SilverstripeRector\Rector\Injector\UseCreateRector;
use Netwerkstatt\SilverstripeRector\Rector\Misc\AddConfigPropertiesRector
use Netwerkstatt\SilverstripeRector\Set\SilverstripeSetList;
use Netwerkstatt\SilverstripeRector\Set\SilverstripeLevelSetList;
use Rector\CodeQuality\Rector\Class_\InlineConstructorDefaultToPropertyRector;
use Rector\Config\RectorConfig;
use Rector\Set\ValueObject\LevelSetList;
use Rector\Set\ValueObject\SetList;


return static function (RectorConfig $rectorConfig): void {
    $rectorConfig->paths([
        __DIR__ . '/app/_config.php',
        __DIR__ . '/app/src',
    ]);
    $rectorConfig->autoloadPaths([
        //composer autoload is already loaded
    ]);
    //add needed files from modules, that don't support composer autoload yet
    $rectorConfig->bootstrapFiles([
        __DIR__ . '/vendor/path/to/code/Foobar.php'
    ]);



//    // register a single rule
    $rectorConfig->rule(InlineConstructorDefaultToPropertyRector::class);

//    // define sets of rules
    $rectorConfig->sets([
        //rector lists
        LevelSetList::UP_TO_PHP_74,
        SetList::CODE_QUALITY,
        SetList::CODING_STYLE,
        //silverstripe rector
        SilverstripeSetList::CODE_STYLE,
        SilverstripeLevelSetList::UP_TO_SS_4_13
    ]);

    //add @config properites to configurations for phpstan
    //configure your own configs    
    $rectorConfig->ruleWithConfiguration(
        AddConfigPropertiesRector::class,
        [
            MyClass::class => [
                'my_config', 
                'another_config'
            ]
        ]
    );
};

Silverstripe-rector comes with two types of SetLists: SilverstripeSetList for single sets of rectors (e.g. upgrading from 5.0 to 5.1 or for genereal Silverstripe code styles) and SilverstripeLevelSetList for combining all set lists up to a given Silverstripe CMS version, e.g. running all upgrades to Silverstripe 5.1.

Running rector

Once it's configured, you can run rector in the command line using the following command:

vendor/bin/rector --dry-run

The option --dry-run prints the code changes; if you're happy with the changes you can remove that option and rector will actually change the files.

Useful options:

--debug for debugging verbosity. Which files and rules are processed?
--xdebug switch that allows running xdebug.

See vendor/bin/rector --help for more options.

TODO

SS3 to SS4 upgrades (before running official upgrader tool)

rename Foo_Controller to FooController
- how can this be made dynamically? via config script that scans the current project?
configure PSR4 Class To File
maybe add namespace to src dir
various deprecations.
- Is it possible to automate stuff that was once configured in PHP and is now configured in YML?
- easy fix would be to switch to new config layer in PHP and add an annotation to fix this manually
fix old Image functions in templates that got deprecated in SS3.2
- this needs another file parser for Silverstripe templates
class Object to trait, see ParentClassToTraitsRector

SS4 upgrades

add $table_name if missing - use short classname instead
- see similar UnifyModelDatesWithCastsRector
various deprecations
- to be configured manually in set lists
fix missing $owns for Image and File relations
- configurable exclude list if it's not wanted
- configurable which relations should be automatically owned (e.g. other versioned DataObjects)

General

Misc

create SetLists for easier configuration

Code Quality

convert new Foo() to Foo::create() if it's a Silverstripe / Injectable class
- see NewToStaticCallRector
add @config param to $db, $has_one, etc.
use Request handler instead of superglobal $_GET and $_POST

wernerkrauss / silverstripe-rector

Maintainers

Details