How to upgrade to Silverstripe CMS 4

Upgrading to Silverstripe CMS 4 may be a time consuming task; If a remake of the website is planed, combining a remake or refactor with the upgrade to Silverstripe 4 could be a good idea since most of the code has to be looked over anyway.

Depending on how recently the project was created and how little refactoring it requires, following the standard upgrading guide from Silverstripe may be sufficient. Previous upgrades from Kreationsbyrån have involved refactoring and removal of legacy code and therefor benefited from starting with a fresh install of Silverstripe CMS.

It is recommended to also refer to the official documentation when following the instructions bellow.

Migrate files to Silverstripe CMS 4

1. Create a new Silverstripe CMS 4 project.
   composer create-project silverstripe/installer [project-name]
2. Import required dependancies. Alternatives to deprecated modules may be required. Note any changes that will have to be made during content or file migration.
3. Copy files to the new project and make the necessary changes. The required file changes are:
   
   • Import used classes, for example use SilverStripe\CMS\Model\SiteTree;
   • Add fully qualified class names i relations, properties etc. ('Image' to Image::class)
   • Change any references to stylesheets, scripts, fonts, etc. to include the new _resources folder.
   • Change _ss_environment.php to .env.
   • Any syntax changes, please refer to official documentation.
   • Required changes due to replaced dependancies.
   • Move or expose public files (stylesheets, icons, fonts, scripts etc.) to the public directory and change any paths.
   • (Recommended) Define a table name for all models to ensure identical table names and simplify content migration. private static $table_name = [name]
   • (Optional) Namespace files. Keep in mind that namespacing a file or changing a class name may break features that rely on the class name, for example, critical CSS, Page type checks, allowed children and links. The Page and PageController class should not be namespaced.

Migrate content to Silverstripe CMS 4

1. Delete the Silverstripe CMS 4 database and import the database from Silverstripe CMS 3.
2. If Elemental is used, execute the following sql-queries before running dev/build.
   
3. Run dev/build.
4. If Elemental is used, execute the following sql-queries. If ElementVirtual is not used, the corresponding fields will have to be removed from the insert queries and any custom fields will have to be added.
   
5. Move the old assets folder to the new public folder.
6. Run ./vendor/bin/sake dev/tasks/MigrateFileTask
7. If Translatable is replaced with Fluent,
   1. Configure locales in CMS Admin.
   2. Run ./vendor/bin/sake dev/tasks/ConvertTranslatableTask.
   3. Make any necessary corrections to the site tree and locales in CMS Admin.

It is adviced to check the new project using a tool like Wraith or Browser stack and crawl the website to look for unexpected error response codes.