Skip to main content

This site requires you to update your browser. Your browsing experience maybe affected by not having the most up to date version.


Latest improvements to the SilverStripe 4 upgrade experience

Since its release, many projects have been upgraded to SilverStripe 4. We’ve been listening to the community’s feedback and in response, have been busy refining the upgrader utility, filling gaps in our documentation, and patching related bugs.

Read post

SilverStripe 4 has been released for almost 20 months. Many SilverStripe projects, both large and small, have been upgraded from SilverStripe 3 to SilverStripe 4 and are now enjoying a more performant and modern CMS. 

However, some have encountered difficulties and frustrating bottlenecks while upgrading their SilverStripe projects. We’ve been listening to the community’s feedback and in response, have been busy refining the upgrader utility, filling gaps in our documentation, and patching related bugs. 

These efforts have been focused on three key areas: migrating files, improving the upgrade experience for projects on the New Zealand Common Web Platform (CWP), and facilitating upgrades for modules.

Upgrading CWP dependencies

CWP 2.0 was released in June 2018. However, our upgrading tools were not properly aligned to provide a smooth upgrade experience for CWP projects.

To remedy this, we added a new --cwp-constraint option to our upgrader utility, so Developers can target a specific CWP release when upgrading their composer dependencies.

# This command will update you project to target CWP 2.1 and use strict constraints
upgrade-code recompose --cwp-constraint ~2.1.0 --strict

We’ve made additional tweaks to the recompose command to substitute individual CWP packages with more high level recipes. The recompose command is also smarter when installing dependencies, which should reduce the number of outstanding conflicts that need to be resolved manually.

Read our Project Upgrading Guide to learn more about upgrading your composer dependencies.

Upgrading module

While we’ve provided a detailed upgrading guide, it was mostly focused on SilverStripe projects. While hundreds of modules listed on are already compatible with SilverStripe 4, there’s more work to do. 

To complement the Project Upgrading Guide, we’ve drafted a dedicated Module Upgrading Guide which cover topics of special interest to module maintainers and those with private modules in their codebase.

Upgrading a module is very similar to upgrading a project, so the new guide focuses on the differences between the two. Module maintainers should still take the time to familiarise themselves with the Project Upgrading Guide.

We’ve added better support for PSR-4 when namespacing your modules. You can now use the --psr4 and --recursive flags to recursively namespace your code when invoking the add-namespace command. If you add the --autoload option, it will automatically add a matching autoload entry to your module’s composer.json file.

Additionally, we’ve made adjustments to the upgrader utility to work more smoothly when working on modules.

Migrating files

SilverStripe 4.4 shipped with a number of enhancements related to file migration:

  • The output of the file migration is now more detailed and readable 
  • The file migration is more memory efficient and more resilient to exceptions 
  • The file migration is more modular and allows Developers to run individual sub tasks 
  • A new task has been added to convert image and file links to short codes

Other enhancements and bug fixes

We’re very grateful to SilverStripe community members who have taken the time to submit bug reports and suggestions on how to improve the upgrader utility. The result is many incremental improvements, such as:

Get the latest upgrader release

We’ll keep adding new features to the upgrader and fixing bugs. To make it easier for Developers to keep their upgrader up-to-date, we’ve added a self-update command that will update your PHAR executable to the latest release. The upgrader will also automatically notify you if you’re running an outdated version. 

If you’re using the upgrader version 1.3.0 or greater, you can get the latest upgrader release by running:

upgrade-code self-update

If you’re using an older release, you can download the upgrader as a PHAR executable (4.5MB download).

We hope this latest round of improvements will help even more teams move to SilverStripe 4. We always enjoy receiving feedback from our community members. If you discover bugs with the upgrader or wish to make a suggestion on how to improve it, please take a minute to raise an issue on the Silverstripe upgrader GitHub repository.

If you’ve recently completed an upgrade project, let us know how it went by posting a summary of your experience on the SilverStripe forum.

About the author
Maxime Rainville

Maxime is the CMS Squad Team Lead. The CMS Squad is the team inside Silverstripe that looks after Silverstripe CMS day-to-day.

Post your comment


No one has commented on this page yet.

RSS feed for comments on this page | RSS feed for all comments