Leveling up your SilverStripe CMS website

Going through the upgrade process is a bit like leveling up your character in a Role Playing Game. You need to get all your force multipliers in a row to boost your experience points and ensure your character (or in this case website) stays valuable and can take advantage of the new powers awarded at each level. For SilverStripe CMS, these new powers take the form of improved user interfaces, features and APIs your website can make use of. We've previously written about the reasons to upgrade your website to SilverStripe 3.2, so I won't go into a "these feature will make you want to upgrade" rant in this post. I will simply make the assumption that you've chosen to "up" your site to a level 3.2 Paladin, good stuff!

I recently went through this process myself with the silverstripe.org website, like any RPG there is a fair amount of grinding you have to get through to prepare your character. So to give you a fast forward for your character, I mean website…  I thought I would share 3 force multipliers that helped me out and should help your own upgrade go smoothly.

1. Companion guides

RPG companion guides are handy indeed. They give you a lot of character backstory, strategies and, of course, the ever useful spells and weapons you can make use of. With SilverStripe CMS, we have our upgrading guides. These work in a similar way, giving a detailed list of any bug fixes, security improvements and any other changes your need to know about to level up your website. If you are upgrading from a version prior to 3.1, you may need to head back to some of the older guides (like moving from 2.x to 3.x) and work your way through a few campaigns towards 3.2. You might want to start a fresh character, that is, take the time to revisit your website project as a whole alongside moving to 3.2. Maybe it's time to make the site responsive or refactor that feature like you always meant to?

In our case, we've been playing this RPG for a while and have been strengthening our silverstripe.org warlock whenever we can. In this instance, I went through our 3.1 codebase and checked for anything in the 3.2 upgrade guide we might need to address. The upgrade mostly worked out of the box and a quick change to our projects composer dependencies (using silverstripe/cms ^3.2 is the way to go!), we did encounter a few gremlins though.

First, we had subclassed the "Image" class which has had a significant refactor in 3.2 (as has the ORM however this seemed to give us no issues). We found we had been relying on a "cast type" classname of GD (the image manipulation extension tool in PHP) and this had been changed to "Image_Backend" to make use of some of the other image tools in PHP. A small breaking change here, not ideal for Semantic Versioning (SEMVER). However, stricter adherence to this standard is something the CMS project is aiming for going forward and lucky this was a simple fix to just replace the name of the class (It'll take some short-term pain for implementing a good long-term open standard).

Next, due to a security improvement to controller actions, we had to add some custom routing into our project yaml configuration. Many of our custom controllers subclass Page_Controller. We relied on a controller named the same as the classname being magically exposed to the public. You should really be consciously aware of what is public and what is not in your web application, so this change is a welcome necessity. Again, a simple fix here, following the notes in the upgrading guide and we were good to carry on our quest.

Lastly, websites with a lot of forms should know that form inputs automatically generate their ID has changed to better meet W3C standards (and as I've mentioned I'm happy to take the hit if we're moving to consistent open standards in the long run). This was to ensure that no input field on a page had the same ID as another and if you have a lot of CSS styles attached to IDs you'll need to revisit and alter those.

So while I've raised some gripes here, minor as they were, there is also some great stuff listed in the upgrade guide. I'm mostly excited about the ability to now enable the PDO database driver for a quick speed bump (a one line change to your environment file in our case, a quick change of configuration on our SilverStripe Platform stack) and SilverStripe core becoming more modular.

Speaking of modules...

2. Managing your power-ups

Throughout your website's journey, it's likely that it will have picked up a bunch of amulets, potions and random seemingly unrelated items like a golden duck feather (that usually turn out to out to be critical later on in the game). Your tardis like rucksack of inventory needs to be well managed. For the SilverStripe ecosystem, Composer is fast becoming the tool we turn to for this. SilverStripe.org is a reasonably complex site relying on many community and commercially supported modules.

One of the most time-consuming aspects of our upgrade process was not the SilverStripe CMS 3.2 upgrade itself, rather uncovering the many modules we rely on haven't been tagged for 3.2 compatibility. Modules developed for SilverStripe 3.1 will often work from a code point of view (where they didn't we also provided some code improvements to the maintainers). What you will have to counter here is composer dependency hell sent up from the underworld to cause trouble.

Let me explain… if a module's composer meta data has defined strictly SilverStripe 3.1 as a requirement (and you now have SilverStripe CMS 3.2), composer won't be able to work out what it should be installing, those pesky dependency versions have essentially just cast a confusion spell. When you strike an encounter like this you can play a few strategies to restore our trusty side-kick composer's health.

1. Make a pull request to the module in question to track version ^3.1 of SilverStripe CMS. This is a composer dependency convention which helps track closely to SEMVER and means dependencies will be able to be installed up to, but excluding SilverStripe 4 (coming out next year, and should be a mighty adventure!). Fixing these issues in open source is preferable. It only takes 1 pull request per module to correct this (assuming the module code itself is compatible with 3.2). This is the shared maintenance model of open source code in action!
   
   

2. You can 'fork' the module, make the change and use this in your project (temporarily of course until it's fixed in the original module repository). It's as easy as adding your personal forked repository into a "repositories" element in your composer metadata. Using personal forks while handy during your upgrading process is not ideal long term, sometimes this is unavoidable though.
   
   For example in your projects composer.json file:

   
   	"repositories": [
   	  {
   	     "type": "vcs",
   	     "url": "git://github.com/yourusername/silverstripe-somemodule.git"
   	  },
   
   

   Then in your require section simply refer to the branch or version of your fork that you want to be installed. Then run a composer update to grab that new code.
   
   
   

3. In cases where one module requires another that also causes version conflicts. Repeat step 1 and/or 2 above for that module then you can (again temporarily) use a handy composer feature called Aliasing. This helps composer to see one version of a module as another in order to bring your power-ups into line. For example, if you wanted to use the code from the master branch of a module not yet tagged as a new version, and composer is expecting to install version 1.1.0 as described in some other module you have installed, you can add this to your composer.json file:

   
   	require: {
   		"vendor/module-name": "dev-master as 1.1.0"
   	},
   
   

   Composer will now treat that modules master branch code as if it were the mythical version 1.1.0. Yield this sorcery with caution of course and aim to remove this as soon as the new version is tagged.  

Many module maintainers are now tagging versioned releases of modules. This is great to see, I would highly recommend at least tagging a 0.1.0 version on your master branch if you have currently not got any tags. You'll be helping out yourself and others going through an upgrade process at some point in the future.

Which brings to me the third and final takeaway: tests and trials.

3. Tests of character

Ok so you've battled your way through lands far and wide and you're up to the final big boss before leveling up your site, the 'Go Live behemoth' and its minions of bugs. They can curtail even the most well meaning quest. Like any RPG, if you haven't made use of the plentiful save points throughout the game, being defeated at this late stage can see you hurtled back, doomed to run through your lists of tests and trials before trying again. Go live doesn't have to be fearful though, just follow a few simply rules of thumb we use for silverstripe.org and you'll be celebrating at the tavern in no time.

Golden rule: Avoid upgrading directly on your live server! We are lucky in that silverstripe.org runs on the SilverStripe Platform (the commercial Platform as a Service product SilverStripe Ltd has created for running SilverStripe CMS websites) and gives us an identical test server alongside our live server which we can deploy our website code to anytime to test against. At very least you should smoke test your upgrade on you local development environment or you could look at a virtual machine (we talked about a few options for these at a previous meetup: DigitalOcean and Bitnami are useful options).

Ok, so you have your site running on a test server and your code upgraded, do all the most important features of your site continue to work as expected?

On silverstripe.org we've started to automate the testing processes. We have unit tests on many of our PHP classes to make sure they return values or perform as expected. We also recently added Behat, an implementation of behavioural testing in PHP that mimics what users do on your website, telling you when things don't act as you expect. We've written tests for many of the key features of the site (and you can never have too many tests). This sets up silverstripe.org for future upgrades. We can simply install the new version, run our suite of tests and these will tell us if anything has stopped working, allowing us to focus on fixing problem areas rather than picking through the entire website manually hunting for bugs.

After that epic campaign, we leveled up silverstripe.org to the latest stable version 3.2.0. We're now able to take on any future upgrades with ease thanks to the handy upgrade guides, our side-kick composer and our automated tests. One thing is for certain: SilverStripe CMS will keep releasing those expansion packs and we'll keep playing! Ready for another adventure?

Got any further upgrading force multipliers to share? Post in the Upgrading SilverStripe forum.