With the release of Craft 5 this past March, it was time to upgrade our agency site to the latest and greatest release. Overall, the process went very smoothly, with the update of Craft core itself having no issues. There were a few plugins we replaced, and a few more we were able to remove.
Getting to Squeaky Clean Craft 4
The first step mentioned in the official upgrade guide is to update Craft 4 to its latest release along with any plugins. In our case, we had a few plugins to address.
Redactor
We were still using the Redactor plugin as our rich text editor, along with a custom Redactor plugin that allowed us to add aria labels to links. Fortunately, the transition from Redactor to CKEditor is straightforward and can be accomplished by either by manually changing a field's type in the control panel or by using the conversion command Craft provides. We opted to manually change field settings so we could customize their configuration to suit our needs.
We changed a few CKEditor config defaults such as limiting the number of bulleted and numbered list styles.
The "htmlSupport" property shown here ensures that any aria labels or button classes we added in the past are preserved and not stripped from the html when a CKEditor field is saved in the future.
Typed Link Field
Since the Typed Link Field Plugin is no longer maintained, we decided to migrate our link fields to Hyper. We have used Hyper on several sites and found it to be a very flexible link-to-anything solution. We first installed Hyper and deployed it to our production Craft 4 site. Then we ran Hyper's migration commands to change the fields to become Hyper fields and migrate their content from Typed Link.
Note: After deploying the project config changes created by the "typed-link-field" command, we ran the "typed-link-content" command in production to migrate the content. If you don't allow admin changes in production, you can temporarily allow them by adding "CRAFT_ALLOW_ADMIN_CHANGES=1" as an environment override.
Freeform
Freeform 5.0 is a major update with some breaking changes. In our case, we were doing very little to customize the default output other than adding our own CSS, so it didn't require much effort. But be sure to check out their upgrade guide, especially if you are integrating Freeform with other apps.
Captcha, Honeypot, and Javascript Test spam prevention will need to be re-created when you upgrade to Freeform 5.
Super Table
We proceeded with the upgrade without removing Super Table yet, more on that in a moment.
Neo
Neo has been our go-to solution for nesting content blocks and creating a modular page builder experience for our clients. It is still supported in Craft 5 and will be around for the foreseeable future. Because we had several years worth of content to consider, we chose to simply upgrade to the latest Craft 5 compatible version of Neo rather than writing a migration.
If we were starting a project from scratch on Craft 5, we would use Craft's native matrix-in-matrix content modeling so the Neo plugin would not be required.
Updating PHP
Craft 5 requires PHP 8.2. Fortrabbit lets us switch PHP versions in a few clicks.
Upgrading Craft to Version 5
Once all the preparation was done, the upgrade process shown here took only a few minutes.
- Backup the database
- Rebuild Project Config
- Set DB Charset and Collation config variables
- Update composer.json to require the 5.0 version of Craft and plugins
- Run "composer update"
- Run "craft up"
- Remove DB Charset and Collation config variables and run the "db/convert-charset command"
If some of your plugins are still in beta you will need to set "minimum-stability" and "prefer-stable" on the root of composer.json.
Final Steps
Template Changes
A few entry type handles changed during the upgrade to be prefixed by their section handle, for example, "genericPage" became "pages_genericPage." We searched the template directory for those handles and updated them where needed.
Removing Super Table
After updating to Craft 5, we ran the command provided by the Super Table Plugin to switch its field to native matrix fields with no data loss.
Then we uninstalled the plugin entirely (giving it a knowing head-nod and final salute for its service — thank you Super Table, your work here is done).
Manual Testing
After any major upgrade we test our contact forms to make sure they are submitting properly and showing errors when invalid. Then with a final scan for any broken links or errors, we can call it a day.
What's next? We'd like to take advantage of some of Craft 5's new features, such as simplified Eager Loading.