silverstripe/upgrader

A tool to help upgrade your code to handle API changes in packages you used.

The Silverstripe CMS Upgrader has mostly served its purpose. The core Silverstripe CMS team is not actively looking at doing more work on it in the near future. If a community member would like become a maintainer, then we're happy to grant them merge access after some basic due diligence. Please raise an issue to let us know if you would like to maintain this repo., _(*1)

Upgrader

, _(*2)

Upgrader is a framework for automating the upgrade of code to handle API changes in dependent libraries. See the 4.x upgrading guide for step-by-step instructions., _(*3)

Developed by @sminnee and @tractorcow with inspiration and encouragement from @camspiers, _(*4)

Install

The upgrader is available as a phar executable., _(*5)

To install the PHAR executable:, _(*6)

1. Download the upgrader as a PHAR executable or wget https://silverstripe.github.io/silverstripe-upgrader/upgrade-code.phar
2. Make the file executable chmod +x upgrade-code.phar
3. Move the file to a folder in your path, for example sudo mv upgrade-code.phar /usr/local/bin/upgrade-code

Install the upgrader globally with composer

You can install the upgrader globally with composer. This can make it easier to update to newer releases, however you can get dependency conflicts if you have other packages installed globally., _(*7)

To install globally run:, _(*8)

composer global require silverstripe/upgrader, _(*9)

Make sure your $HOME/.composer/vendor/bin directory is in your PATH (or the equivalent for your OS e.g. C:\Users\<COMPUTER NAME>\AppData\Roaming\Composer\vendor\bin on Windows)., _(*10)

echo 'export PATH=$PATH:~/.composer/vendor/bin/' >> ~/.bash_profile, _(*11)

Then you can run this script with upgrade-code <command> in your project root. If not running in the root, use --root-dir=/path., _(*12)

Available commands

Overview

The following commands are available: * all: Aggregate all the commands required to upgrade a SilverStripe project. * add-namespace: Add a namespace to a file. * recompose: Upgrade a composer file to use the latest version of SilverStripe. * doctor: Run all cleanup tasks configured for this project * environment: Migrate settings from _ss_environment.php to .env * inspect: Runs additional post-upgrade inspections, warnings, and rewrites to tidy up loose ends * reorganise: Reorganise project folders from the SS3 mysite convention to the SS4 app convention * self-update: Get the latest version of the SilverStripe upgrader. * upgrade: Upgrade a set of code files to work with a newer version of a library. * webroot: Update a SilverStripe project to use the public webroot., _(*13)

all

Run all commands in the recommended order with sensible default values., _(*14)

upgrade-code all \
    [--root-dir=<root>] \
    [--composer-path=composer] \
    [--strict] \
    [--recipe-core-constraint=RECIPE-CORE-CONSTRAINT] \ 
    [--namespace] \
    [--skip-reorganise] \
    [--skip-webroot] \
    [--skip-add-namespace] \
    [--psr4]

Example:, _(*15)

upgrade-code all

• Unless your site is very simple, it's highly unlikely this command will be successful the first time you run it. It's designed to be run successively to help you find errors and debug them. If the command runs successfully, you'll get a summary of all warnings at the end.
• All changes are written. This is necessary because some of the later commands expect specific steps to have been performed beforehand.
• It's equivalent to running the following steps in the following order:
  • recompose
  • environment
  • add-namespace
  • upgrade
  • inspect
  • reorganise
  • webroot
• the --skip flags allows to skip optional steps.
• --namespace and --psr4 are relayed to the add-namespace command.
• --strict, cwp-constraint and --recipe-core-constraint are relayed to the recompose command.

add-namespace

You can run the below to add namespace to any class, _(*16)

upgrade-code add-namespace <namespace> <filepath> [--root-dir=<dir>] [--write] [--recursive] [--psr4] [-vvv] [--autoload] [--autoload-dev]

Example:, _(*17)

upgrade-code add-namespace "My\Namespace" ./mysite/code/SomeCode.php --write -vvv

• Make sure you run this in your project root, or set the root with --root-dir.
• Note that it's important to either quote or double-escape slashes in the namespace.
• If you want to just do a dry-run, skip the --write param.
• If you have multiple namespace levels you can add the --recursive or -r param to also update those levels.
• If your filepath follows PSR-4 you can add the --psr4 or -p param with the recursive param to auto-complete namespaces in child directories. The --autoload and --autoload-dev parameter can be used to quickly configure autoload in your composer.json file.

This will namespace the class file SomeCode.php, and add the mapping to the ./.upgrader.yml file in your project., _(*18)

Once you've added namespaces, you will need to run the upgrade task below to migrate code that referenced the un-namespaced versions of these classes., _(*19)

recompose

You can use this command to upgrade your composer.json dependencies from SilverStripe 3 to Silverstripe 4., _(*20)

upgrade-code recompose [--root-dir=<dir>] [--write] [--strict] [-vvv] [--recipe-core-constraint=*] [--cwp-constraint] [--composer-path=composer]

Example:, _(*21)

upgrade-code recompose --root-dir=/var/www/SS_project --write --recipe-core-constraint="4.1"

• You may end up with broken dependencies after running this command. You'll have to resolve those broken issues manually.
• You can specify which version of SilverStripe you want to upgrade to via the --recipe-core-constraint option. If left blank, you'll be upgraded to the latest stable version.
• If you are upgrading a CWP project use --cwp-constraint instead of --recipe-core-constraint. --cwp-constraint allows you to target a specific version of cwp/cwp-core.
• This script relies on composer to fetch the latest dependencies. If composer is in your path and is called composer or composer.phar, you don't need to do anything. Otherwise you'll have to specify the --composer-path option.
• If you specify the --strict option, constraints on your depdencies will be a bit more rigid.
• If you want to just do a dry-run, skip the --write params. You will be given a change to save your changes at the end.

doctor

When migrating from prior versions certain project resources (e.g. .htaccess / index.php) could be outdated and leave the site in an uninstallable condition., _(*22)

You can run the below command on a project to run a set of tasks designed to automatically resolve these issues:, _(*23)

upgrade-code doctor [--root-dir=<root>]

Tasks can be specified in .upgrade.yml with the following syntax:, _(*24)

doctorTasks:
  SilverStripe\Dev\CleanupInstall: src/Dev/CleanupInstall.php

The given task must have an __invoke() method. This will be passed the following args:, _(*25)

• InputInterface $input
• OutputInterface $output
• string $basePath Path to project root

Note: It's advisable to only run this if your site is non-responsive, as these may override user-made customisations to .htaccess or other project files., _(*26)

environment

You can use this command to migrate an SilverStripe 3 _ss_environment.php file to the .env format used by SilverStripe 4., _(*27)

upgrade-code environment [--root-dir=<dir>] [--write] [-vvv]

Example:, _(*28)

upgrade-code environment --root-dir=/var/www/SS_project --write -vvv

• The command doesn't assume your _ss_environment.php file is in your root folder. Like SilverStripe 3, it will recursively check the parent folder until it finds an _ss_environment.php or an unreadable folder.
• If your _ss_environment.php file contains unusual logic (conditional statements or loops), you will get a warning. upgrade-code will still try to convert the file, but you should double-check the output.
• If you want to just do a dry-run, skip the --write params.

inspect

Once a project has all class names migrated, and is brought up to a "loadable" state (that is, where all classes reference or extend real classes) then the inspect command can be run to perform additional automatic code rewrites., _(*29)

This step will also warn of any upgradable code issues that may prevent a successful upgrade., _(*30)

Note: This step is separate from upgrade because your project code is loaded into real memory during this step in order to get the complete project context. In order to prepare for this step your site should be updated to a basic stage, including all module upgrades and namespace changes., _(*31)

You can run this command (with a necessary refresh of composer autoload files) with the below:, _(*32)

composer dump-autoload
upgrade-code inspect <path> [--root-dir=<root>] [--write] [-vvv] [--skip-visibility]

This will load all classes into memory and infer the types of all objects used in each file. It will use these inferred types to automatically update method usages., _(*33)

Visibility updates

The command updates properties and functions to use the correct visibility of its parent if possible., _(*34)

Add the --skip-visibility option to ignore this., _(*35)

reorganise

You can use this command to reorganise your folder structure to conform to the new structure introduced with SilverStripe 4.1. Your mysite folder will be renamed to app and your code folder will be rename to src., _(*36)

upgrade-code reorganise [--root-dir=<dir>] [--write] [--recursive] [-vvv], _(*37)

Example:, _(*38)

upgrade-code reorganise --root-dir=/var/www/SS_project --write -vvv, _(*39)

• If you want to just do a dry-run, skip the --write params.
• The command will attempt to find any occurrence of mysite in your codebase and show those as warnings.

self-update

This command will update the upgrader tool itself to the newest release. It does not take any arguments. It's important to keep the tool updated since its under active development, and continuously improves., _(*40)

upgrade-code self-update

upgrade

Once you have finished namespacing your code, you can run the below code to rename all references., _(*41)

upgrade-code upgrade <path> [--root-dir=<root>] [--write] [--rule] [-vvv] [---prompt]

Example, _(*42)

upgrade-code upgrade ./mysite/code

This will look at all class maps, and rename any references to renamed classes to the correct value., _(*43)

In addition all .yml config files will have strings re-written. In order to upgrade only PHP files you can use the --rule=code. If you have already upgraded your code, you can target only config files with --rule=config., _(*44)

Excluding strings from upgrade

When upgrading code that contains strings, the upgrader will need to make assumptions about whether a string refers to a class name or not, and will determine if that is a candidate for replacement., _(*45)

If you have a code block with strings that do not represent class names, and thus should be excluded from rewriting (even if they match the names of classes being rewritten) then you you can add a docblock with the @skipUpgrade tag, and the upgrader will not alter any of this code., _(*46)

Example:, _(*47)

/** @skipUpgrade */
return Injector::inst()->get('MyService');

In the above example, MyService will not be modified even if it would otherwise be renamed., _(*48)

This doc block can be applied either immediately before the statement with the string, or before a block of code (such as a method, loop, or conditional)., _(*49)

Note that @skipUpgrade does not prevent upgrade of class literals, and only affects strings, as these are not ambiguous, and the upgrader can safely update these references., _(*50)

Upgrading Database references to now namespaced DataObject subclasses

If any DataObject subclasses have been namespaced, we will need to specify them in a config file ie. legacy.yml. This tells SilverStripe to remap these class names when dev/build is run., _(*51)

---
Name: mymodulelegacy
---
SilverStripe\ORM\DatabaseAdmin:
  classname_value_remapping:
    MyModelClass: 'Me\MyProject\Model\MyModelClass'  

Upgrading localisations

You can also upgrade all localisation strings in the below files:, _(*52)

• keys in lang/*.yml
• _t() method keys in all *.php files
• <%t and <% _t() method keys in all *.ss files

You can run the upgrader on these keys with the below command:, _(*53)

upgrade-code upgrade <path> --rule=lang

Since this upgrade is normally only done on projects that provide their own strings, this rule is not included by default when running a normal upgrade., _(*54)

Class renaming

Class mappings can be used to convert string literal references to namespaced classes. Sometimes it is unclear whether a string literal is referring to the mapped class or not. This is where renameWarnings are handy., _(*55)

An example of an ambiguous rename would be:, _(*56)

private static $has_one = [
    'Image' => 'Image',
];

You can specify what class renames should be considered ambiguous with yaml:, _(*57)

renameWarnings:
  - File
  - Image

The above config will show warnings when renaming the File and Image occurrences to their respectful class mappings., _(*58)

Add the --prompt option to manually approve ambiguous class renames., _(*59)

.upgrade.yml spec

The .upgrade.yml file will follow the below spec:, _(*60)

# Upgrade these classes
mappings:
  OldClass: My\New\Class
  SS_MyClass: NewClass
# File extensions to look at
fileExtensions:
  - php
# Don't rewrite these `private static config` settings
skipConfigs:
  - db
  - db_for_versions_table
# Don't rewrite these keys in YML
skipYML:
  - MySQLDatabase
  - Filesystem
# Namespaces to add (note: It's recommended to specify these on the CLI instead of via config file)
add-namespace:
  namespace: The\Namespace
  path: src/
# List of tasks to run when running `upgrade-code doctor`
doctorTasks:
  SilverStripe\Dev\CleanupInstall: src/Dev/CleanupInstall.php
warnings:
  classes:
    MyClass:
      message: 'MyClass has been removed'
      url: 'http://my-domain/upgrade-instructions'
  methods:
    'MyClass->myInstanceMethod()':
      message: 'Use otherMethod() instead'
      replacement: 'otherMethod'
    'MyClass::myStaticMethod()':
      message: 'Use otherMethod instead'
      replacement: 'otherMethod'
    'obsoleteMethod()':
      message: 'obsoleteMethod is removed'
  props:
    'MyClass->myInstanceProp'
      message: 'Use otherProp instead'
      replacement: 'otherProp'
    'MyClass::myStaticProp'
      message: 'Use otherProp instead'
      replacement: 'otherProp'
    'obsoleteProp':
      method: 'obsoleteProp is removed'
  functions:
    'myFunction()':
      message: 'Use otherFunction() instead'
      replacement: 'otherFunction'
  constants:
    'MY_CONSTANT':
      message: 'Use OTHER_CONSTANT instead'
      replacement: 'OTHER_CONSTANT'
    'MyClass::MY_CONSTANT':
      message: 'Use OTHER_CONSTANT instead'
      replacement: 'OTHER_CONSTANT'
excludedPaths:
  - '*thirdparty*'

webroot

Configure your project to use the public web root structure introduced with SilverStripe 4.1 (details., _(*61)

upgrade-code webroot [--root-dir=<root>] [--write] [--composer-path=composer] [-vvv]

Example:, _(*62)

upgrade-code webroot /var/www/ss_project

• Your project must be using silverstripe/recipe-core 4.1 or greater to use this command. Otherwise you'll get a warning.
• If you've customised your server configuration files (.htaccess and/or web.config), you'll have to reconcile those manually with the generic ones provided by silverstripe/recipe-core.
• After running this command, you need to update your virtual host configuration to point to the newly created public folder and you need to rewrite any hardcoded paths.