A tool to help upgrade your code to handle API changes in packages you used.
- dev-master / 1.3.x-dev
This package is auto-updated.
Last update: 2023-01-22 00:23:54 UTC
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.
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.
Developed by @sminnee and @tractorcow with inspiration and encouragement from @camspiers
The upgrader is available as a phar executable.
To install the PHAR executable:
- Download the upgrader as a PHAR executable or
- Make the file executable
chmod +x upgrade-code.phar
- Move the file to a folder in your path, for example
sudo mv upgrade-code.phar /usr/local/bin/upgrade-code
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.
To install globally run:
composer global require silverstripe/upgrader
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).
echo 'export PATH=$PATH:~/.composer/vendor/bin/' >> ~/.bash_profile
Then you can run this script with
upgrade-code <command> in your project root. If not running in the root,
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
inspect: Runs additional post-upgrade inspections, warnings, and rewrites to tidy up loose ends
reorganise: Reorganise project folders from the SS3
mysiteconvention to the SS4
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
Run all commands in the recommended order with sensible default values.
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]
- 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:
--skipflags allows to skip optional steps.
--psr4are relayed to the
--recipe-core-constraintare relayed to the
You can run the below to add namespace to any class
upgrade-code add-namespace <namespace> <filepath> [--root-dir=<dir>] [--write] [--recursive] [--psr4] [-vvv] [--autoload] [--autoload-dev]
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
- If you have multiple namespace levels you can add the
-rparam to also update those levels.
- If your filepath follows PSR-4 you can add the
-pparam with the recursive param to auto-complete namespaces in child directories. The
--autoload-devparameter can be used to quickly configure autoload in your
This will namespace the class file SomeCode.php, and add the mapping to the
./.upgrader.yml file in your project.
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.
You can use this command to upgrade your
composer.json dependencies from SilverStripe 3 to Silverstripe 4.
upgrade-code recompose [--root-dir=<dir>] [--write] [--strict] [-vvv] [--recipe-core-constraint=*] [--cwp-constraint] [--composer-path=composer]
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-constraintoption. If left blank, you'll be upgraded to the latest stable version.
- If you are upgrading a CWP project use
--cwp-constraintallows you to target a specific version of
- This script relies on composer to fetch the latest dependencies. If
composeris in your path and is called
composer.phar, you don't need to do anything. Otherwise you'll have to specify the
- If you specify the
--strictoption, constraints on your depdencies will be a bit more rigid.
- If you want to just do a dry-run, skip the
--writeparams. You will be given a change to save your changes at the end.
When migrating from prior versions certain project resources (e.g. .htaccess / index.php) could be outdated and leave the site in an uninstallable condition.
You can run the below command on a project to run a set of tasks designed to automatically resolve these issues:
upgrade-code doctor [--root-dir=<root>]
Tasks can be specified in
.upgrade.yml with the following syntax:
doctorTasks: SilverStripe\Dev\CleanupInstall: src/Dev/CleanupInstall.php
The given task must have an
__invoke() method. This will be passed the following args:
- 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.
You can use this command to migrate an SilverStripe 3
_ss_environment.php file to the
.env format used by
upgrade-code environment [--root-dir=<dir>] [--write] [-vvv]
upgrade-code environment --root-dir=/var/www/SS_project --write -vvv
- The command doesn't assume your
_ss_environment.phpfile is in your root folder. Like SilverStripe 3, it will recursively check the parent folder until it finds an
_ss_environment.phpor an unreadable folder.
- If your
_ss_environment.phpfile contains unusual logic (conditional statements or loops), you will get a warning.
upgrade-codewill still try to convert the file, but you should double-check the output.
- If you want to just do a dry-run, skip the
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.
This step will also warn of any upgradable code issues that may prevent a successful upgrade.
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.
You can run this command (with a necessary refresh of composer autoload files) with the below:
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.
The command updates properties and functions to use the correct visibility of its parent if possible.
--skip-visibility option to ignore this.
You can use this command to reorganise your folder structure to conform to the new structure introduced with SilverStripe 4.1.
mysite folder will be renamed to
app and your
code folder will be rename to
upgrade-code reorganise [--root-dir=<dir>] [--write] [--recursive] [-vvv]
upgrade-code reorganise --root-dir=/var/www/SS_project --write -vvv
- If you want to just do a dry-run, skip the
- The command will attempt to find any occurrence of mysite in your codebase and show those as warnings.
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.
Once you have finished namespacing your code, you can run the below code to rename all references.
upgrade-code upgrade <path> [--root-dir=<root>] [--write] [--rule] [-vvv] [---prompt]
upgrade-code upgrade ./mysite/code
This will look at all class maps, and rename any references to renamed classes to the correct value.
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
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.
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.
/** @skipUpgrade */ return Injector::inst()->get('MyService');
In the above example,
MyService will not be modified even if it would otherwise be renamed.
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).
@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.
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.
--- Name: mymodulelegacy --- SilverStripe\ORM\DatabaseAdmin: classname_value_remapping: MyModelClass: 'Me\MyProject\Model\MyModelClass'
You can also upgrade all localisation strings in the below files:
- keys in
_t()method keys in all
<% _t()method keys in all
You can run the upgrader on these keys with the below command:
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.
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.
An example of an ambiguous rename would be:
private static $has_one = [ 'Image' => 'Image', ];
You can specify what class renames should be considered ambiguous with yaml:
renameWarnings: - File - Image
The above config will show warnings when renaming the
Image occurrences to their respectful class mappings.
--prompt option to manually approve ambiguous class renames.
The .upgrade.yml file will follow the below spec:
# 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*'
Configure your project to use the
public web root structure introduced with SilverStripe 4.1 (details.
upgrade-code webroot [--root-dir=<root>] [--write] [--composer-path=composer] [-vvv]
upgrade-code webroot /var/www/ss_project
- Your project must be using
silverstripe/recipe-core4.1 or greater to use this command. Otherwise you'll get a warning.
- If you've customised your server configuration files (
web.config), you'll have to reconcile those manually with the generic ones provided by
- After running this command, you need to update your virtual host configuration to point to the newly created
publicfolder and you need to rewrite any hardcoded paths.