Latest improvements to the SilverStripe 4 upgrade experience

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 addons.silverstripe.org 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:

• Updating the recomposer command to take into consideration development dependencies
• Updating the upgrade command to replace Object references with the equivalent traits
• Adding logic to automatically correct public static configuration variables
• Adjusting the inspect command to avoid ambiguous substitution for common class names
• Avoiding adding use statements for PHP types

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.