README

silverstripe-rector

A developer utility for automatically upgrading deprecated code for Silverstripe CMS. With rules for upgrades for Silverstripe 6.

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 cambis/silverstan, too.

Note: if you need to use PHPStan v1 in your project, use v0.x of this module

composer require phpstan/extension-installer --dev
composer require cambis/silverstan  --dev
composer require wernerkrauss/silverstripe-rector --dev
vendor/bin/rector init

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

parameters:
  level: 1
  paths:
    - app/src

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 Rector\Config\RectorConfig;
use Rector\Set\ValueObject\SetList;
use Netwerkstatt\SilverstripeRector\Rector\DataObject\EnsureTableNameIsSetRector;
use Netwerkstatt\SilverstripeRector\Rector\Injectable\UseCreateRector;
use Rector\Set\ValueObject\LevelSetList;
use Rector\Set\ValueObject\SetList;
use Netwerkstatt\SilverstripeRector\Set\SilverstripeSetList
use Netwerkstatt\SilverstripeRector\Set\SilverstripeLevelSetList

return RectorConfig::configure()
    ->withPaths([
        __DIR__ . '/app/_config.php',
        __DIR__ . '/app/src',
        __DIR__ . '/app/tests',
    ])
    ->withPreparedSets(deadCode: true);
    ->withSets([
        //rector lists
        LevelSetList::UP_TO_PHP_83,
        SetList::CODE_QUALITY,
        SetList::CODING_STYLE,
        //silverstripe rector
        SilverstripeSetList::CODE_STYLE,
        SilverstripeLevelSetList::UP_TO_SS_6_0
    ])
    ->withRules([
        EnsureTableNameIsSetRector::class,
        UseCreateRector::class
    ])
       
    // any rules that are included in the selected sets you want to skip
    ->withSkip([
//        ClassPropertyAssignToConstructorPromotionRector::class,
//        ReturnNeverTypeRector::class
    ]);

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 general 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.

Other useful modules you should know about

• cambis/silverstripe-rector

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

Thanks to

xini for updating this module to Rector V2 and adding a lot of Silverstripe 6 rules.

Need Help?

If you need some help with your Silverstripe project, feel free to contact me ✉️.

See you at next StripeCon 👋