Update from Contao 4.9 to Contao 4.13

Since the update is of a minor release and the version constraint within the Contao Manager or the "composer.json" has to be adjusted, you cannot perform it as usual with the update feature of trakked. Simply put, the update process within the Contao 4 series is always the same and already well documented in the Contao manual. Therefore our instructions specifically include additional notes for Contao 4.13.

To keep it as simple as possible, we are only going to explain the update using the Contao Manager and leave out the the command line instructions. Furthermore, we are still using PHP 7.4 to avoid problems with extensions. More about the change to PHP 8 at the end of the article.

Create a backup

As with any major change, you should always make a backup. Most important are the files "composer.json" and "composer.lock" as well as a complete database backup.

Update Contao 4.9 to the latest version

If you have not updated Contao 4.9 recently, you should first update to the latest version of Contao 4.9. To do this, open the Contao Manager and select "Update packages" and then select "Update all packages" from the dropdown menu.

If you are a using trakked, you can also perform this using our update function.

Also open the install tool and make sure the database is up to date.

Check compatibility of extensions

Not every extension is already compatible with Contao 4.13. We recommend to visit the developer's project website and/or the repository on GitHub. Is there a compatibility notice or news? When was the extension last updated? Are there still open tickets for Contao 4.13? Additionally, you can check the Contao forum for recent posts or ask in the Contao Slack channel.

Are you using a ready-made Contao theme?

If you use a ready-made theme, check with the provider of your theme whether it is compatible with Contao 4.13 or if there is an update available.

Update packages

Log in to the Contao Manager and adjust the Contao version constraint. To do this, click on the gear next to the Contao version and enter 4.13.*.

Then click Apply Changes at the bottom and select Update "All Packages" in the dropdown.

If the update process was successful, you can go directly to the Contao install tool and apply the necessary database changes. If you see any deletions, please check if they are justified. If in doubt, do not perform any deletions at first, you can always do it later.

If the update does not work
If an error occurs during the update, please check the output of the Contao Manager. Can can most likely see in the console what is causing the problem. In our experience, incompatible extensions are usually what prevents an update.

Version adjustments for extensions

This step is not mandatory, but may be necessary if a newer major version of an extension is compatible with Contao 4.13 or PHP 8.

Example: terminal42/contao-easy_themes

To install the latest version 3.x of Easy-Themes, you have to click the gear just like with Contao and adjust the version accordingly.

How can you find out if there is a newer version?
To do so, click on "Details" in the Contao Manager for the respective package. Here you can see if a new major version is available. Before you upgrade, be sure to read the upgrade instructions provided by the developer of the extension. It is possible that the new version requires extensive rework or may need to be completely rebuilt.

Check the log files

Make sure to take a quick look at the log file. You can find it under /var/logs/prod-*.log. Are there any new error messages that need to be fixed?

Adapt template changes

Only few important changes were made to the templates, but a total of 42 files have been changed. To find out whether a change is relevant for you, use the backend comparison function for your customized templates.

Here is a brief overview of the most important changes

• The schema.org markup has been removed from various templates and the central JSON+LD management has been added.
• The function "Patchwork\Utf8::substr" was replaced by the PHP function "mb_substr ".
• In the templates for the reader modules, the "back button" was adjusted
• The insert tag for {{request_token}} was replaced by <?= $this->requestToken ?>.
• Markup for the preview feature was added to the download templates
• The search templates were adjusted
• The template for the password field was changed

CSS classes «first» und «last»

The CSS classes "first" and "last" are no longer automatically added to articles and content elements. If you have used these CSS classes, you need to adjust your CSS accordingly and should replace them with CSS selectors (first-child, last-child, nth-child).

In general, you should completely avoid using the CSS classes "first", "last", "even" and "odd", since Contao 5 removes these classes from all elements.

Switch the routing mode

With Contao 4.10, a new routing mode has been introduced. Since some third-party extensions may have problems with the new routing, it is disabled by default and can be enabled in the app configuration. This requires the following entry in the "config/config.yml":

contao:
  legacy_routing: false

Don't forget to clear the application cache for the new configuration to become active.

Dynamic sitemaps

The sitemap.xml is no longer written to the server as a static file like before. Instead it is generated when the /sitemap.xml route is called, depending on the context, and stored in the HTTP cache.

• Old: your-domain.com/share/your-sitemap.xml
• New: your-domain.com/sitemap.xml

If you use the Google Search Console, you should announce the new path to Google.

No more Google web fonts in page layout

With Contao 4.11, the entry for Google Web Fonts was removed in the page layout. During migration, an corresponding line should have been automatically added to "Additional <head>tags". Make sure this was successful if you used Google fonts. For privacy reasons, it is recommended to remove the entry completely and include the Google Fonts locally.

Adjust permissions

With the update, new fields have also been added to Contao. To allow editors to use these new fields (e.g. the page title for FAQ entries), you need to adjust the user groups accordingly.

Use public folder

This step is not mandatory because Contao and the Contao Manager support both the old and the new path. However, if you would like to have a consistent installation environment, you can rename the existing "web"-folder to "public".

Attention: The path change must also be done in the domain configuration in the hosting.

MySQL strict mode as default

Since Contao 4.13, MySQL strict mode is enabled by default. If you manually added this to your config, you can clean it up in the config/config.yml.

Clean up composer.json

This task is only necessary if you manage Contao from the command line. If you use the Contao Manager, the necessary adjustments will be done automatically.

If your Contao project has been installed for a long time and you have done several version updates, it is possible that some entries in the "composer.json" are outdated and need to be modified. Compare the "composer.json" of a fresh Contao 4.13 installation with your local file.

Take a close look at the following sections:

• config
• extra
• scripts

As said before, this is only relevant if you use "composer" from the command line.

Remove unnecessary extensions

Contao is continuously improved, so certain features of extensions are directly integrated into the Contao core. For example, since Contao 4.11 the metadata for FAQs can be overridden and since Contao 4.13 canonical URLs can be configured.

Summary

The update to Contao 4.13 should in most cases be uncomplicated and feasible without major problems. A bit more difficult might the conversion to PHP 8 be, because of compatibility issues that extensions need to fix. Many developers have already started to adapt their extensions. We expect the switch to PHP 8 will also go smoothly this fall at the latest.