Our experience upgrading from Silverstripe 4 to Silverstripe 5

When you build a project using the Silverstripe CMS you know the time will come when a major version will be released, based on past experience it’s not one that necessarily fills you with joy. On May 4th 2023 Silverstripe released version 5.0 into the wild, as Silverstripe specialists we’d been keeping an eye on the alpha and beta versions. But it’s only when you get a stable release that you can really get your hands dirty and see how extensive or trivial the upgrade path is going to be.

Of course the initial hurdle with any Silverstripe project is to see which add-on authors will be proactive in supporting this new release. To the credit of the Silverstripe CMS development community, many of our tried and tested add-ons were supported at the time of, or within a few weeks of the release. We made a spreadsheet of all of the add-ons used in our projects and set about documenting their Silverstripe 5 support status. Making contact with the authors of the add-ons that weren’t currently supporting Silverstripe 5 helped us to see whether it was their intention to make the necessary update themselves or if they would welcome a pull request from us. Most already had plans to make their own updates and over the next month we only needed to send one pull request and that was merged within a week of them receiving it. It never ceases to amaze me that these non-commercial software projects get perpetually maintained and updated for the benefit of all of us. I can honestly say that the Silverstripe development community is very much alive and well.

The upgrade

We read through the Silverstripe 5 upgrade change logs and the official release blog post to see what we had in store. From what they outlined, it seemed like there were some breaking changes but a good portion of the changes came from removing deprecated code and enforcing some coding practices that were once a little lax but were now going to be enforced. We see this as a maturation of Silverstripe, it seems to be at a point now where there is evolution between versions rather than a revolution, if you’ve upgraded from 2 to 3 or 3 to 4 you’ll know exactly what I mean. While testing we put together a document of common changes we’d need to check for in all projects, mostly simple things like overwriting /public/index.php or in the template $Last || $First is now $isFirst || $isLast.

But wait, there’s more

Silverstripe 5 requires a minimum of PHP 8.1 and a maximum of PHP 8.2, we endeavoured to see if we could move our projects up to PHP 8.2, it seemed like the logical thing to do as we’d already created a testing bed for Silverstripe 5 and all of our used third party add-ons. There are breaking changes between PHP 8.1 and 8.2 so we moved carefully through our code base diligently testing and documenting as we went.

Rubber meets road

It was time to upgrade our first real project from Silverstripe 4 to 5 and PHP 8.0 to 8.2. Working locally, it went as smoothly as we could have hoped. Using our spreadsheet of supported add-on versions we updated our composer.json file, then updated our code based on our documented findings from previous testing. When we hit /dev/build?flush, most of the time we had no issues. Thorough testing of the project admin and front end templates sometimes brought out project specific edge cases, but because of our extensive planning the whole process worked seamlessly. Deploying to staging and testing again didn’t reveal any hidden surprises.

Anyone for takeaway?

Based on previous Silverstripe CMS upgrading experiences, we took a cautious approach and carved out time to prepare and research before diving into our first live project. This worked out to be much more efficient in the long run. Committing to documenting updates and fixes upfront allowed us to start a new upgrade task and undertake most changes before we ran our first build. It helped that our projects have a mature, consistent and organised codebase. We’ve taken time to make our coding standards and practices consistent across projects which makes new features, updates and upgrades more predictable to price and work on. Silverstripe CMS is now in a place where it can release a new major version without significant changes to their API. This is good news for us as we’ve invested a large amount of time and faith in Silverstripe CMS, it is the backbone of our projects and long may it continue to improve and mature.