silverstripe-rector

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

Table of Contents

• About rector
• Installation
• Running rector
• Docs
• IDE Support (PHPStorm)
• Other useful modules you should know about
• Developing
• TODO
• Thanks to
• Need Help?

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 Netwerkstatt\SilverstripeRector\Set\SilverstripeLevelSetList;
use Netwerkstatt\SilverstripeRector\Set\SilverstripeSetList;
use Rector\Config\RectorConfig;

return RectorConfig::configure()
    ->withPreparedSets(
        deadCode: true,
        codeQuality: true,
        codingStyle: true,
        typeDeclarations: true,
        instanceOf: true,
        earlyReturn: true,
        rectorPreset: true
    )
    ->withPhpSets() //automatically gets the PHP version from composer.json
    ->withSets([
        //silverstripe rector
        SilverstripeSetList::CODE_STYLE,
        SilverstripeLevelSetList::UP_TO_SS_6_0
    ]);

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.

See also Rector documentation for more configuration possibilities.

You can find a list of Rectors provided by this module in the documentation.

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.

Docs

• Changelog

• See a list of custom Silverstripe related rectors in the docs.

• Update from Silverstripe 5 to Silverstripe 6: article on s2-hub.com

• Better PHP with rector: Talk at StripeConEU 2023 in Hamburg

Changelog Analysis Process

To keep up with new Silverstripe releases, we use an AI-assisted workflow:

1. Sync Changelogs: Download both HTML (for reference) and Markdown (for analysis) files.

   ddev changelog-sync 6.2.0

2. Generate AI Prompt: This script extracts the most relevant sections (API changes, renames, deprecations) from the Markdown file.

   ddev changelog-analyze-ai 6.2.0

3. Process with AI: Copy the generated prompt into an AI (like ChatGPT or Claude).
4. Update TODOs: Copy the AI's response into docs/todos/ss-X.Y.Z.md.

Standard TODO Format:

• [RENAME/MOVE] Old\Namespace\Class has been renamed to New\Namespace\Class
• [DEPRECATED] Method OldClass::method() is deprecated, use NewClass::method() instead
• [REMOVED] Class/Method ... has been removed.

IDE Support (PHPStorm)

Since Rector uses PHPStan, which is often distributed as a PHAR file, your IDE might not find classes like PHPStan\Type\ObjectType.

To fix this in PHPStorm:

1. Include PHPStan classes:

   • Go to Settings > Languages & Frameworks > PHP.
   • In the Include Path tab, click +.
   • Add the directory vendor/phpstan/phpstan. PHPStorm will automatically find and index the phpstan.phar inside it.
   • Alternatively: Install the phpdoc-parser which provides many type definitions:

     composer require --dev phpstan/phpdoc-parser

2. Exclude fixtures: To avoid "Duplicate class" errors from test fixtures, exclude the tests/**/Fixture directories from your project:

   • Right-click on the Fixture folder in the project tree.
   • Select Mark Directory as > Excluded.

Other useful modules you should know about

• cambis/silverstripe-rector

Developing

This module provides Composer scripts for environments without DDEV. The equivalent DDEV commands add the container-specific setup where needed.

PHP Code Sniffer

Code Sniffer is a tool to detect violations of a defined coding standard (mostly PSR-12)

See phpcs.xml.dist for the ruleset used.

Detect violations

ddev lint

or without DDEV:

composer lint

Fix most violations automatically

ddev fix

or:

composer fix

PHPStan

PHP Static Code Analyzer is a tool to detect bugs in your code without running it. It can be used to detect type errors, dead code, and other issues.

Don't be too much annoyed by the errors. Rector can fix a lot of them automatically.

A level of 4 should be doable.

ddev stan

or:

composer stan

Rector

Rector is a tool to refactor code automatically. It can be used to upgrade code to a newer version of Silverstripe or PHP.

See rector.php for rules and configuration.

ddev rector --dry-run #dry-run
ddev rector

or:

composer rector:dry
composer rector

Jack

Jack is a tool to check for outdated dependencies, especially major version updates that might require manual intervention.

ddev check-outdated-dependencies

The deprecated ddev jack command remains available as an alias for older projects.

Everything in one command

There are CI shortcuts for both environments. The Composer command runs PHPUnit, linting, Rector in dry-run mode and PHPStan, stopping at the first failure:

composer ci

The DDEV command additionally runs the DDEV-configured frontend and outdated dependency checks:

ddev ci

Current migration work

The current migration work is tracked in GitHub Issues. Version-specific Silverstripe analysis and remaining upgrade candidates are documented in docs/todos/.

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 👋