PHPackages silverstripe/upgrader - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. silverstripe/upgrader ActiveLibrary silverstripe/upgrader ===================== A tool to help upgrade your code to handle API changes in packages you used. 1.4.3(6y ago)3910.0k↓100%22[56 issues](https://github.com/silverstripe/silverstripe-upgrader/issues)[2 PRs](https://github.com/silverstripe/silverstripe-upgrader/pulls)1BSD-3-ClausePHPPHP ^7.1 Since Jun 14Pushed 2y ago8 watchersCompare [ Source](https://github.com/silverstripe/silverstripe-upgrader)[ Packagist](https://packagist.org/packages/silverstripe/upgrader)[ RSS](/packages/silverstripe-upgrader/feed)WikiDiscussions master Synced 1mo ago READMEChangelog (10)Dependencies (16)Versions (22)Used By (1) **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 ======== [](#upgrader) [![Build Status](https://camo.githubusercontent.com/a72bff9c3ddd262ebbd7f4eee32c8739f41831247ecec3c4b8e96de2b020bfbe/68747470733a2f2f6170692e7472617669732d63692e636f6d2f73696c7665727374726970652f73696c7665727374726970652d75706772616465722e7376673f6272616e63683d6d6173746572)](https://travis-ci.com/silverstripe/silverstripe-upgrader)[![SilverStripe supported module](https://camo.githubusercontent.com/9b7e93d393a01f6d3091fb30983b870aa863ef076858115faaa1c74b995854ec/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f73696c7665727374726970652d737570706f727465642d3030373143342e737667)](https://www.silverstripe.org/software/addons/silverstripe-commercially-supported-module-list/) Upgrader is a framework for automating the upgrade of code to handle API changes in dependent libraries. See the [4.x upgrading guide](https://docs.silverstripe.org/en/4/upgrading/) for step-by-step instructions. Developed by @sminnee and @tractorcow with inspiration and encouragement from @camspiers Install ------- [](#install) The upgrader is available as a phar executable. To install the PHAR executable: 1. [Download the upgrader as a PHAR executable](https://silverstripe.github.io/silverstripe-upgrader/upgrade-code.phar) 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 [](#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. 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\\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 ` in your project root. If not running in the root, use --root-dir=/path. Available commands ------------------ [](#available-commands) ### Overview [](#overview) The following commands are available: - [`all`](#all): Aggregate all the commands required to upgrade a SilverStripe project. - [`add-namespace`](#add-namespace): Add a namespace to a file. - [`recompose`](#recompose): Upgrade a composer file to use the latest version of SilverStripe. - [`doctor`](#doctor): Run all cleanup tasks configured for this project - [`environment`](#environment): Migrate settings from `_ss_environment.php` to .env - [`inspect`](#inspect): Runs additional post-upgrade inspections, warnings, and rewrites to tidy up loose ends - [`reorganise`](#reorganise): Reorganise project folders from the SS3 `mysite` convention to the SS4 `app` convention - [`self-update`](#self-update): Get the latest version of the SilverStripe upgrader. - [`upgrade`](#upgrade): Upgrade a set of code files to work with a newer version of a library. - [`webroot`](#webroot): Update a SilverStripe project to use the `public` webroot. ### `all` [](#all) Run all commands in the recommended order with sensible default values. ``` upgrade-code all \ [--root-dir=] \ [--composer-path=composer] \ [--strict] \ [--recipe-core-constraint=RECIPE-CORE-CONSTRAINT] \ [--namespace] \ [--skip-reorganise] \ [--skip-webroot] \ [--skip-add-namespace] \ [--psr4] ``` Example: ``` 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` [](#add-namespace) You can run the below to add namespace to any class ``` upgrade-code add-namespace [--root-dir=] [--write] [--recursive] [--psr4] [-vvv] [--autoload] [--autoload-dev] ``` Example: ``` 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. 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. ### `recompose` [](#recompose) You can use this command to upgrade your `composer.json` dependencies from SilverStripe 3 to Silverstripe 4. ``` upgrade-code recompose [--root-dir=] [--write] [--strict] [-vvv] [--recipe-core-constraint=*] [--cwp-constraint] [--composer-path=composer] ``` Example: ``` 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` [](#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. 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=] ``` 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. ### `environment` [](#environment) You can use this command to migrate an SilverStripe 3 `_ss_environment.php` file to the `.env` format used by SilverStripe 4. ``` upgrade-code environment [--root-dir=] [--write] [-vvv] ``` Example: ``` 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` [](#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. 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 [--root-dir=] [--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. #### Visibility updates [](#visibility-updates) The command updates properties and functions to use the correct visibility of its parent if possible. Add the `--skip-visibility` option to ignore this. ### `reorganise` [](#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`. `upgrade-code reorganise [--root-dir=] [--write] [--recursive] [-vvv]` Example: `upgrade-code reorganise --root-dir=/var/www/SS_project --write -vvv` - 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` [](#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. ``` upgrade-code self-update ``` ### `upgrade` [](#upgrade) Once you have finished [namespacing your code](#add-namespace), you can run the below code to rename all references. ``` upgrade-code upgrade [--root-dir=] [--write] [--rule] [-vvv] [---prompt] ``` Example ``` 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 `--rule=config`. #### Excluding strings from upgrade [](#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. 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. Example: ``` /** @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). 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. #### Upgrading Database references to now namespaced DataObject subclasses [](#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. ``` --- Name: mymodulelegacy --- SilverStripe\ORM\DatabaseAdmin: classname_value_remapping: MyModelClass: 'Me\MyProject\Model\MyModelClass' ``` #### Upgrading localisations [](#upgrading-localisations) You can also upgrade all localisation strings in the below files: - keys in `lang/*.yml` - `_t()` method keys in all `*.php` files - ` '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 `File` and `Image` occurrences to their respectful class mappings. Add the `--prompt` option to manually approve ambiguous class renames. .upgrade.yml spec ----------------- [](#upgradeyml-spec) 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*' ``` ### `webroot` [](#webroot) Configure your project to use the `public` web root structure introduced with SilverStripe 4.1 (details. ``` upgrade-code webroot [--root-dir=] [--write] [--composer-path=composer] [-vvv] ``` Example: ``` 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. ### Health Score 35 — LowBetter than 79% of packages Maintenance0 Infrequent updates — may be unmaintained Popularity34 Limited adoption so far Community28 Small or concentrated contributor base Maturity67 Established project with proven stability Bus Factor3 3 contributors hold 50%+ of commits How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~62 days Recently: every ~42 days Total 19 Last Release 2492d ago Major Versions 0.0.5 → 1.0.0-beta12017-07-03 ### Community Maintainers ![](https://www.gravatar.com/avatar/b0cba8b534e20e6ab4fff555a97b237a18436ebca1446fc0b29c8a8b504038b9?d=identicon)[GuySartorelli](/maintainers/GuySartorelli) ![](https://www.gravatar.com/avatar/a25bc04c5720a36869d5a39c6449dde7eb43e19b7c8e666d5f632d6a9ab440b1?d=identicon)[emteknetnz](/maintainers/emteknetnz) ![](https://www.gravatar.com/avatar/afbb3dcc9ef29c1a6eedd6addcae5fce9ab1271915a85a4c349301b71237368d?d=identicon)[silverstripe-machine01](/maintainers/silverstripe-machine01) ![](https://www.gravatar.com/avatar/be6648e60fbab6f70bfc34dd8c14259562d28a47510a934ea9c01fe98633f3c2?d=identicon)[sminnee](/maintainers/sminnee) --- Top Contributors [![bergice](https://avatars.githubusercontent.com/u/541886?v=4)](https://github.com/bergice "bergice (27 commits)")[![maxime-rainville](https://avatars.githubusercontent.com/u/1168676?v=4)](https://github.com/maxime-rainville "maxime-rainville (19 commits)")[![chillu](https://avatars.githubusercontent.com/u/111025?v=4)](https://github.com/chillu "chillu (18 commits)")[![robbieaverill](https://avatars.githubusercontent.com/u/5170590?v=4)](https://github.com/robbieaverill "robbieaverill (9 commits)")[![dhensby](https://avatars.githubusercontent.com/u/563596?v=4)](https://github.com/dhensby "dhensby (7 commits)")[![emteknetnz](https://avatars.githubusercontent.com/u/4809037?v=4)](https://github.com/emteknetnz "emteknetnz (3 commits)")[![lozcalver](https://avatars.githubusercontent.com/u/1655548?v=4)](https://github.com/lozcalver "lozcalver (2 commits)")[![flamerohr](https://avatars.githubusercontent.com/u/1064889?v=4)](https://github.com/flamerohr "flamerohr (2 commits)")[![ScopeyNZ](https://avatars.githubusercontent.com/u/3260989?v=4)](https://github.com/ScopeyNZ "ScopeyNZ (2 commits)")[![elliot-sawyer](https://avatars.githubusercontent.com/u/354793?v=4)](https://github.com/elliot-sawyer "elliot-sawyer (1 commits)")[![mr-macedawg](https://avatars.githubusercontent.com/u/23121194?v=4)](https://github.com/mr-macedawg "mr-macedawg (1 commits)")[![nfauchelle](https://avatars.githubusercontent.com/u/1188162?v=4)](https://github.com/nfauchelle "nfauchelle (1 commits)")[![christopherdarling](https://avatars.githubusercontent.com/u/178039?v=4)](https://github.com/christopherdarling "christopherdarling (1 commits)")[![torleif](https://avatars.githubusercontent.com/u/67215?v=4)](https://github.com/torleif "torleif (1 commits)")[![sheadawson](https://avatars.githubusercontent.com/u/1166136?v=4)](https://github.com/sheadawson "sheadawson (1 commits)")[![ichaber](https://avatars.githubusercontent.com/u/929858?v=4)](https://github.com/ichaber "ichaber (1 commits)") --- Tags hacktoberfest ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/silverstripe-upgrader/health.svg) ``` [![Health](https://phpackages.com/badges/silverstripe-upgrader/health.svg)](https://phpackages.com/packages/silverstripe-upgrader) ``` ### Alternatives [shopware/platform The Shopware e-commerce core 3.3k1.5M3](/packages/shopware-platform)[sylius/sylius E-Commerce platform for PHP, based on Symfony framework. 8.4k5.6M646](/packages/sylius-sylius)[drupal/core Drupal is an open source content management platform powering millions of websites and applications. 19462.3M1.3k](/packages/drupal-core)[silverstripe/framework The SilverStripe framework 7213.5M2.5k](/packages/silverstripe-framework)[drupal/core-recommended Locked core dependencies; require this project INSTEAD OF drupal/core. 6939.5M340](/packages/drupal-core-recommended)[contao/core-bundle Contao Open Source CMS 1231.6M2.3k](/packages/contao-core-bundle) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)