CWP 2.0 major release and upgrading

Update (May 2019): Read our CWP 2.x Upgrading Guide, with information for decision makers, project managers and developers.

On the 30th of May the first major update became available for the Common Web Platform, in the form of a 2.0.0 stable release. The Common Web Platform is an all of government CMS platform which is built on top of and supported by SilverStripe. Much excitement and anticipation has built up around this monumental effort from a huge team of dedicated people — a small summary of which can be read from an earlier blog post announcing the release, covering reasons for upgrading and new features that have been released... but what does this mean, technically?

A quick list of SilverStripe 4 upgrade points:

• Modules are now silverstripe-vendormodule, and all reside within the vendor directory as with other PHP ecosystem requirements.
• Projects are now served from a public folder as the web root (as opposed to the installation base). This is required by CWP 2.
• In order to load assets such as images, CSS, and JavaScript, there is a new expose directive for modules and themes to use. This includes the root project. There's a new requirements syntax to help load these in now too.
• Namespaces. Even when a problem seems like it's not caused by a namespace, there's still a high chance it's caused by a namespace. Even with templates.

Expediting upgrading

In order to help our friends achieve their goals more easily, it's important that we provide easy solutions to work around any obstacles they may encounter. As such, the SilverStripe core team have been spending a great amount of time developing a tool to help teams convert old code bases to the new hotness with minimal fuss in laborious edit tasks.

It will:

• 'recompose' your requirements
• update your environment settings
• help you namespace your code
• help update your code to use new APIs
• alert you to any issues it may identify
• relocate your web root assets
• re-organise your project layout (more relevant with upcoming releases)

While most of these tasks aren't the biggest of issues, any automation is certainly a welcome aid. The one thing it will not do though is update your version of PHP. Although not strictly necessary, upgrading a project provides great timing to also upgrade to PHP 7.1 — all it takes is a request to the Service Desk to get this sorted.

Upgrading tips

The ol' switcheroo

A major release provides an opportunity to break APIs and retire obsolete code, an opportunity most developers are exceedingly elated to embrace. Coinciding with API updates to the SilverStripe core packages and supported modules, the lineup of the modules included in the CWP recipe was also reviewed. Among the most pertinent change for CWP is the selection of the new Fluent module, to replace the old Translatable module. See the full module write up or the "What's new is better" section of the previous post for more info about which modules are retired from the recipe and what the path for upgrading is.

Versioning

It's a story that writes itself; Versioning data in the new version of CWP has upgraded to a new... approach. The new API provided by the core is much more flexible and so much more powerful than before,making it worth investing some time in understanding how this all works, and how it relates to the new campaigns feature.

There is a cautionary tale in liberally applying the versioned extension when it comes to many to many relationship types. It seems intuitive to version objects in a relationship definition, however without also versioning the many_many relationship itself things quickly get out of sync. Enter the Many Many Through relationship type. To have a many to many relationship to a versioned object, the intermediary object must also be versioned. There is an example of this with the corresponding update to CWPs 'Related Pages' feature.

Always keep learning

Things move at such a rapid pace in the technology sector, continuous improvement must be a way of life. To that end there are many places to find more information about the new depths to be explored with this new edition of CWP.

There is a more exhaustive list of upgrade caveats available on the CWP 2.0.0 release notes which should be able to introduce any developer to the newer concepts accompanying this release, along with SilverStripe 4 being heavily detailed by the SilverStripe core development team via their release documentation for the major release of 4.0.0. And of course the general outline of any CWP upgrade is documented online for the CWP community to use. The composer tool's documentation on using forks will also greatly help teams in upgrading custom project code to be SilverStripe 4 compatible.

There is also a series of talks being delivered at regional meetups in New Zealand (and Melbourne!) giving a high level overview of what's involved with upgrading to SilverStripe 4 — both from a process point of view, but also to what concepts have been introduced that developers will need to deal with issues issues encountered with the newer features.

Keeping these points in mind is sure to give any developer a head start in this brave new world. But of course there is also the community Slack channel or forums for people looking for readily available help with a more personal touch.

Check out the CWP Upgrade Guide