Update from Contao 5.3 to Contao 5.7

Update Contao 5.3 to the latest version

Before you start the update, make sure your existing installation is up to date with the latest version of Contao 5.3. To do this, open the Contao Manager, select ‘Update packages’ and complete any pending migrations and database changes.

Check the compatibility of the extensions

Many extensions that are compatible with Contao 5.3 also work with Contao 5.7. Nevertheless, it’s worth doing a quick check: Check on Packagist or GitHub to see if your extensions support Contao 5.7. A look at open GitHub issues or the date of the last update will give you a good indication. If in doubt, the only thing to do is try it out.

Are you using a ready-made Contango theme?

If you are using a purchased theme, check with the provider to see if it is compatible with Contao 5.7 and whether an update is already available. It's best to clarify any questions you have with the manufacturer's support team before you start the update.

Check PHP version

For Contao 5.7, you need at least PHP 8.3. Check which PHP version is active in your hosting control panel and change it if necessary. We recommend that you always use the latest PHP version on your hosting account.

Create a backup

Once all the prerequisites have been met, create a full backup. The files composer.json and composer.lock, as well as a complete database backup, are particularly important.

You can find out more about backups in the article: The Contao Backup 101.

Customise the package version and perform the update

In Contao Manager or directly in the composer.json, change the Contao version from 5.3.* to 5.7.*:

"contao/manager-bundle": "5.7.*"

Also check whether individual extensions require a version update. This is the case, for example, if a new major version of an extension is available. Then start the update via the Contao Manager (“Update packages”) or directly via Composer.

If the update fails, check the Contao Manager output carefully. In most cases, incompatible extensions are the cause.

If you would like to understand more about version constraints and dependencies, we recommend reading our article.

Performing database migrations

Once the update has been successfully completed, carry out all database migrations. Be sure to check all suggested deletions carefully before confirming them.

Has the update been successfully completed, and is at least the backend accessible again? If so, we can move on to the follow-up tasks. If so, you can move on to the follow-up tasks.

Twig or HTML5?

Let’s move on to the most exciting and time-consuming part: customising the templates.

The future of Contao is Twig. Contao 5.7 is the last version to support the old HTML5 templates. From Contao 6 onwards, this support will be completely phased out.

It is understandable that you want to save time when updating to 5.7 by sticking with the HTML5 templates for the time being. However, you will have to do this work at the latest when updating to Contao 6.

Our clear recommendation: Migrate to Twig now and use only Twig templates from now on.

In brief:

• Keep HTML5 templates: You are almost finished with the update. Check whether all templates are still working and continue with the section Further follow-up work.
• Migrate to Twig (recommended): Read on for our tips on migrating.

Migration to Twig

Since Contao 5.7, there has been a Twig version for all templates. It is the first version of Contao that works 100% with Twig templates at the core.

The procedure is clear: go through each template individually and create the corresponding Twig variant for it.

Example: You have customised the template news_full.html5. Then replace it with news_full.html.twig and transfer your customisations into Twig syntax.

Where possible, only overwrite individual blocks rather than the entire template. However, the news_full template is one of the older templates that only recognises the info block and therefore often needs to be overwritten in its entirety.

Specific example: You have removed the author and customised the date formatting in news_full.html5. Previously, it looked like this:

<?php $this->extend('news_full'); ?>

  <?php $this->block('info'); ? >
    <p class="info"><time datetime="<?= $this->datetime ?>"><?= \Contao\Date::parse("d. F Y", $this->timestamp); ?></time></p >
  <?php $this->endblock(); ?>

The corresponding Twig template news_full.html.twig then looks like this:

{% extends "@Contao/news_full.html.twig" %}

{% block info %}
    <p class="info"><time datetime="{{ datetime }}">{{ timestamp|date("d. F Y") }}</time></p>
{% endblock %}

Much clearer, and the effort involved is kept to a minimum.

Important: You must delete or rename the old HTML5 template so that the new Twig template is recognised. Work in debug mode during the development phase so that template changes take effect immediately without having to manually clear the cache each time.

Whether you prefer to use Template Studio or your IDE (e.g. PhpStorm or Visual Studio Code) is up to you.

Practical tips for migrating to Twig

There is no one-size-fits-all solution, as the customisations required vary greatly from project to project. Some templates contain custom PHP code that can no longer be used directly in Twig and must be moved into filters or functions. The official documentation will help you with this:

• Custom Code in Twig Templates

AI tools can be a useful aid when converting HTML5 templates to Twig. It is important to note: use them as a tool, not as a fully automated solution. If you do not understand how Contao works with Twig, you will not recognise errors in the generated output. Therefore, familiarise yourself with the basics first before converting templates.

Below you will find the most common adjustments you will encounter during migration.

Insert tags in templates

If you have used insert tags in your templates, you should now use the corresponding Twig functions or filters instead.

• Insert tag as a function: Suitable for content that may also contain HTML tags.
• Insert tag as a filter: Suitable for text where no HTML is expected.

Example function: {{link_url::42}} becomes:

{{ insert_tag('link_url::42') }}

Example filter: {{date::Y}} becomes:

{{ '{{date::Y}}'|insert_tag }}

Formatting dates in news or events

We’ve already covered this in the example above. For the sake of completeness:

PHP:

<?= \Contao\Date::parse("d. F Y", $this->timestamp); ?>

Twig:

{{ timestamp|date("d. F Y") }}

Accessing global variables

The Contao team has also provided a solution for accessing global variables such as $objPage:

• Twig globals: contao

Example: Up until now, you may have accessed a page’s CSS class like this:

global $objPage;
$cssClass = $objPage->cssClass;

if (str_contains($cssClass, 'style1')) {
    // Your code
}

In Twig, this works as follows:

{% set cssClass = contao.page.cssClass|default('') %}

{% if 'style1' in cssClass %}
    {# Your code #}
{% endif %}

Example: You have a multilingual website and want to display the appropriate text directly in the template.

PHP:

<?php if($GLOBALS['TL_LANGUAGE'] == 'en'): ?>
    Here is a text in English.
<?php else: ?>
    Hier ist ein Text auf Deutsch.
<?php endif; ?>

Twig:

{% if app.request.locale == 'en' %}
    Here is a text in English.
{% else %}
    Hier ist ein Text auf Deutsch.
{% endif %}

Customise the TinyMCE template

Contao 5.7 uses TinyMCE 8. If you are using a customised TinyMCE template be_tinyMCE, you will need to replace outdated labels in the toolbar. The most important changes:

formatselect → blocks

styleselect → styles

fontselect → fontfamily

fontsizeselect → fontsize

You can find a complete list in the TinyMCE documentation:
Migration from TinyMCE 4 to 8.

Check the base tag

The <base> tag is no longer output in Contao 6. All paths in templates and CSS must therefore be absolute, i.e. start with a /.

From:

files/layout/css/style.css

Becomes:

/files/layout/css/style.css

Check all your templates and CSS files for relative paths and adjust them accordingly. This will ensure you are well prepared for the switch to Contao 6.

Forms: Check session storage

Until now, Contao has always stored form data temporarily in the session, even if no {{form_session_data::*}} insert tag was used. This created a cookie and disabled the HTTP cache for one minute.

In Contao 5.7, there is a new setting for each form that only activates session storage when it is actually needed. In many cases, this allows you to completely dispense with sessions and cookies in the frontend, which improves caching performance.

For all existing forms, the option is automatically enabled to ensure backwards compatibility. Check your forms and disable the option wherever you do not need access to the form data via the Insert tag.

Check your own programming

If you have made any customisations in the src directory, please check these as well and update the code to Contao 5.7.

Other points

• Adjust permissions: Enable new features for editors in the user group settings.
• Check log files: Check for new error messages in /var/logs/prod-*.log, in Contao Manager under ‘Tools and System Log’ or in trakked.