Craft 6 went into beta on November 10, and Pixel & Tonic are planning the stable release for March. It’s the version that moves Craft from Yii 2 to Laravel, so it’s the biggest change to the platform since Craft 3.
I’m not putting client sites on a beta. But most of the work in a major upgrade is preparation, and nearly all of that can be done on Craft 5 today. This is the list I’m working through on the sites I look after.
Get to the Latest Craft 5
You can only upgrade to Craft 6 from Craft 5. There’s no path from Craft 4 or anything older, and the upgrade guide asks for the latest 5.x release with the latest version of every plugin.
If you’re still on Craft 4, that’s the job in front of you, and it’s a bigger one than this post. I wrote up how I moved four sites from Craft 4 to 5, including the 571 calendar events that went missing on the way.
Clear Every Deprecation Warning
Craft keeps a list of deprecated code your site is still calling, under Utilities, then Deprecation Warnings. Before a major upgrade that list should be empty.
It matters more than usual this time. Craft 6 ships an optional package called the Yii 2 adapter, which translates old API calls so that existing plugins and modules keep working on Laravel. The docs are clear that it expects Craft 5 deprecations to have been dealt with first. Anything on that list today is something the adapter won’t save you from.
Click through the front end as well as the control panel before you check. Warnings are only logged when the deprecated code runs, so a template nobody has visited won’t show up.
Move the Server to PHP 8.5
Craft 6 requires PHP 8.5. Craft 5 already runs on it, so the server can be upgraded months ahead and tested with the site you have now. That takes one variable out of upgrade day.
The database requirements are MySQL 8.0.17, MariaDB 10.4.6 or PostgreSQL 13 as a minimum. If you’re on Craft 5 you already meet them.
Entrify Categories, Tags and Globals
Craft has been steering everything toward entries for a while. In Craft 6, Globals are gone and replaced by single sections, and Categories and Tags are deprecated. The upgrade can convert them for you.
I’d sooner do that on Craft 5, on my own schedule, with the entrify commands.
php craft entrify/categories myCategoryGroup
php craft entrify/tags myTagGroup
php craft entrify/global-set myGlobalSetDone now, it’s a small change you can test properly and ship by itself. Left to the upgrade, it happens in the middle of a much bigger change, and that’s a bad moment to discover a template still calls craft.categories().
Go Through the Plugin List
Plugins decide how long any Craft upgrade takes. For each one, I’m asking three things.
Do I still need it? Craft 6 turns each filesystem into a Laravel disk, so filesystem plugins are no longer needed at all. Other plugins have been overtaken by features in core. Every plugin removed is one less thing to wait for.
Is it being maintained? A plugin whose last release was two years ago is unlikely to get a Craft 6 version. That’s worth knowing while there’s still time to replace it.
Does it need the adapter? According to the beta announcement, the Plugin Store flags plugins that rely on the Yii 2 adapter and installs it alongside them. Most of Pixel & Tonic’s own plugins already support both Craft 5 and 6 that way.
Find Your Own Yii Code
The parts of a site most affected are the ones written for it. Custom modules, event listeners and console commands are all built on Yii, and they change shape in Craft 6. Modules stop being a separate concept. Their code moves into the app’s own namespace, with service providers doing the wiring.
The adapter will keep much of the old code running to begin with. I still want to know how much there is before I quote for an upgrade, so I’m listing it now. A search of the modules folder for Event::on and Craft::$app gives a fair measure.
Templates get off lightly. Twig stays, and the docs say all Twig features remain intact. The one thing to look for is craft.app, which templates can no longer reach in Craft 6.
Know What Will Move
The project layout changes to match a Laravel app. It helps to know this in advance because deploy scripts, server config and .gitignore files all have paths in them.
web/becomespublic/templates/becomesresources/views/translations/becomeslang/- Craft’s config files move into
config/craft/ - The database variables in
.envlose theirCRAFT_prefix
There’s a tool that does the moving, called craft6-revamp. You don’t need to do any of it by hand today. What you can do is write down every place outside the repo that refers to web/, starting with the web server’s document root.
Rehearse It on a Copy
When the stable release lands, the first run should be on a copy of the site, with a database backup taken before and after. The upgrade guide adds one warning I hadn’t seen in earlier versions. Let the queue empty first, because the queue table is rebuilt and any jobs still waiting are lost.
Then check the content, and don’t stop at the pages. On my Craft 4 to 5 upgrades, the automated migration finished without an error and had still emptied every calendar event. A comparison of the content before and after is what caught it.
When I’d Upgrade
I wouldn’t be first. Craft 5 has security support until March 2032 according to the beta announcement, so there’s no deadline pushing anyone onto 6.0. I’d wait for the stable release, then for the plugins each site depends on, and upgrade once both are settled.
The preparation is a different matter. Everything above makes a Craft 5 site tidier today, and it turns the upgrade into a smaller job whenever you choose to do it.
Leave a Reply