Preparations for Craft 4

Craft version update

An update to Craft 4 is only possible if at least Craft 3.7.11 is installed. So if you were hoping that you could switch directly from your old Craft 2 project to Craft 4, you would be disappointed.

Update to the latest version of Craft CMS 3

So the first step is to update to the latest Craft 3 version. This update can be done via the control panel or the terminal.

Updating via the Control Panel

When an update is available, users with the proper permission will see a notice in the Control Panel next to the Utilities menu. Click on Utilities and then on Updates.

This area displays updates for Craft CMS and the installed plug-ins. The updates can be selected individually or all at once.

Updating via the terminal

The `update` command can be used to update Craft and plug-ins. To get all available updates of a Craft project displayed, enter the following command in the command line of the terminal:

  php craft update

To run all available updates at once, enter this command:

  php craft update all

If you want to update individual packages, you should replace `all` with the corresponding name. So `craft` for the CMS or just the handle for the respective plug-in. For example, if the plug-in SEOmatic is to be updated, the command is:

  php craft update seomatic

By default, Craft updates to the latest available version. If you want to update to a specific version, `:<version>` should be appended to the handle:

  php craft update seomatic:3.4.23

Craft also provides an `update/composer-install` command which behaves like the `composer-install` but does not require Composer to be installed.

Upgrade instructions

Sometimes there are significant changes that need to be considered before an upgrade. In this case, the upgrade guides for each version or edition should be read:

• Upgrading to Craft 3.7
• Upgrading to Craft 3.6
• Upgrading to Craft 3.5
• Upgrading to Craft Pro

Updating PHP and MySQL

Craft 4 requires at least PHP 8 and MySQL 5.7.8 or MariaDB 10.2.7.

It is best to open `composer.json` and edit the platform entry there:

  {
	"config": {
		"platform": {
			"php": "8.0.2"
		}
	}
}

After that, just run `composer update` with dry-run option:

  composer update --dry-run

Dry-run simulates the update command without actually updating the dependencies. So it looks like an update is happening, while only visual hints are given about which package would be updated to which version, without actually updating the dependencies.

To do this, start the Composer update without a dry run:

  composer update

Fixing deprecation warnings

The first thing to do is to enable the debug toolbar. In the Craft Control Panel, click on My Account, then Preferences, and finally click on "Show the debug toolbar on the front end". After that, browse the website in the browser and fix the reported deprecation warnings. Additionally, there is a complete list of all recent warnings in the Control Panel under Utilities → Deprecation Warnings.

What to look for?

Several Twig tags, functions, and date formatting have changed. Also, there are deprecated element query params in Twig templates. In addition, anything with GraphQL and custom PHP modules or plug-ins should be investigated.

Use of environment variables

With Craft 4, the support of `siteName` and `siteUrl` is removed. So remove `siteName` from `config/general.php` and set an environment variable in the right place in the control panel. It is essential to know that the `{siteUrl}}` tag does not need to be removed from the templates; only the associated configuration setting is no longer supported.

The environment variable is defined in the `.env` file, for example:

BASE_URL="http://craftentries.test" 

This makes sense because a different URL is needed for the local development environment than for the live server. In the example, the local .env file would have the URL just mentioned, while the live server .env file would have the value:

 `BASE_URL="https://craftentries.io" 

You can set environment variables for various settings in Craft:

General Settings:

• System Name
• System Status
• Time Zone

Sites:

• Name
• Base URL
  

Sections:

• Preview Target URIs

Asset Volumes:

• Base URL
• File System Path (Local)

Email:

• System Email Address
• Sender Name
• HTML Email Template
• Username (Gmail and SMTP)
• Password (Gmail and SMTP)
• Hostname (SMTP)
• Port (SMTP)
• Use authentication (SMTP)
• Encryption Method (SMTP)

After the variables are created in the `.env` file, they can be selected in the appropriate settings options in the control panel — type `$` in the field and then the variable's name. While typing, Auto-Complete is enabled, and this will display a list of available variables.

It is important to know that only the variable name is stored in the database or Project Config. Thus the value of the variable can be different for each environment, and sensitive information can also be stored.

Making the templates compatible with Twig 3

Craft 4 relies on Twig 3 and no longer Twig 2, which may require adjusting templates.

The `{% spaceless %}` tag is no longer supported, as it will be handled as a filter in the future. However, you can still use spaceless via the `apply` tag, as long as you follow this syntax:

  {% apply spacepless %}
	{# ... #}
{% endapply %}

The `{% filter %}` tag has been removed, `{% apply %}` should be used instead.

If parameters no longer work in the `{% for %}` tag, `| filter` should be used instead:

  {% for item in items | filter(item => item is not null) %}
{% ... %}
{% endfor %}

Changes in GraphQL

The GraphQL APIs have changed, so `enabledForSite` is no longer supported, and `status` should be used instead. However, the changes are more profound as `enabledForSite` only accepted a boolean while `status` accepts an array.

From:

  {
	entries(enabbledForsite: true) {
	title
	}
}

To:

  {
	entries(status: ["enabled"]) {
	title
	}
}

Conclusion:

All the changes presented here can be done before Craft 4, so transitioning to the latest version in a few weeks will be less stressful.

It is essential to know how the PHP version is updated and that it is impossible to switch from Craft 2 directly to Craft 4. In that case, it is mandatory to update to Craft 3.7 before and from there to Craft 4.0.