Update from Contao 4.13 to Contao 5.3

Analyse existing installation

Please check the individual points step by step. If a requirement is not met, an update may not be possible at this time.

Check installed extensions

Check for each installed extension whether it is compatible with Contao 5.3. To do this, you can open the details for the package in the Contao Manager and switch to the "Dependencies" tab. Version 5 should be allowed in the version condition for "Contao Core". This can look like this, for example:

Contao Core: ^4.13 || ^5.0

You can find out more about "Contao version constraints" in our blog post "composer.json - Understanding version constraints and dependencies".

If an extension is not released for Contao 5, the next step is to check whether there is a new (major) version of the extension and whether it is released for Contao 5.

To do this, click on "more → package details" in the package details. The Packagist website will open; select the latest available release and check the entry "contao/core-bundle".

If there is no newer version that is compatible with Contao 5, then unfortunately you cannot install this extension under Contao 5.
You now have several options:

• Remove the extension if it is no longer needed
• Develop the necessary adjustments yourself and provide a pull request
• Contact the developer and commission the necessary customisations for a fee
• Find an equivalent replacement for the extension

If none of the above options are a solution for you, it is currently not possible to update to Contao 5. In this case, the only option is to stay with Contao 4.13 for the time being.

Since we also like to use extensions ourselves, we have already summarised the necessary information on some popular extensions in this blog post. You can find them at the end of this blog post.

Check theme (if used)

If you are using a ready-made theme, be sure to check with the vendor whether there is a release for Contao 5.3 and to what extent an update is necessary.

Many vendors have already released their themes for Contao 5. For some themes, however, support ends with Contao 4.13. You can obtain more detailed information on this directly from the respective theme vendor.

You should also check the official documentation from your theme vendor before updating to Contao 5.3. Often there are also theme-specific notes that need to be respected.

Individual adjustments

If individual programming such as hooks have been added to your installation (src directory), adjustments will most likely also be necessary here. If you have not made these adjustments yourself, please ask your developer to take a look beforehand so that the appropriate adjustments can be made.

Check webserver

Do you have all the necessary system requirements for Contao 5? It is particularly important that your server offers at least PHP version 8.1 or higher.

Further requirements can be found in the Contao manual.

Find out about the new features of Contao 5

When updating from Contao 4.13 to 5.3, all changes to versions 5.0, 5.1 and 5.2 are of course also included. This means that you will be faced with numerous new features and customisations after the update. It is therefore highly recommended that you get an overview in advance.

In particular, I would like to refer you to the following sources:

• Contao 5.0 Announcement, Release, Video & Changelog
• Contao 5.1 Announcement, Release, Video & Changelog
• Contao 5.2 Announcement, Release, Video & Changelog
• Contao 5.3 Announcement, Release, Video & Changelog
• Keynote Leo Conference 2023
• What you need to know about Contao 5.3 LTS
• Limit the backend width in Contao 5

Fulfilled all requirements?

If all of the above requirements are met, then we come to the practice.

Create backup

As with every major update, you should always create a backup. The files "composer.json", "composer.lock" and a complete database backup are particularly important. You can find instructions on which directories you should also back up for a complete backup in our blog post "The Contao Backup 101".

Create parallel installation (recommended)

So that you always have an executable installation and can easily check what the website looked like under Contao 4.13 after the update, I recommend that you carry out the update in a parallel installation. Although this is not a mandatory requirement, it will make the process much easier and save you unnecessary stress.

Create a complete copy of the live website under a new subdomain or local and import the backup there.

Prepare Contao 4 for the update

Depending on how regularly and conscientiously you have updated Contao 4, the next steps may take more or less time. Before you update to Contao 5.3, the following tasks need to be completed on Contao 4.

Update to Contao 4.13

First update to the latest available Contao 4.13. This is essential to ensure that the update to Contao 5 runs without errors, as Contao 5 expects the database to be in the state of the latest version 4.13. If you are still using Contao 4.9, you can use the following instructions to help you.

Perform available database migrations

To do this, open the Contao Manager, go to "System maintenance" and click on "Check database". Carry out all open database migrations.

Remove incompatible extensions before the update

If you have identified outdated and incompatible extensions during the analysis phase, remove them now or update to a compatible version.

Export internal CSS and integrate it into the layout as external CSS

The internal CSS editor has been removed in Contao 5. This means you have to export all internal styles and add them to the layout as external CSS.

To do this, go to the Contao back end under "Themes → CSS". To export, click on "Export" for each stylesheet.

You can then add the CSS files back to the layout as external CSS. To do this, first download the CSS files via the file manager into a corresponding folder on your installation and then open each layout and add the corresponding CSS files as external CSS. At the same time, uncheck the internal stylesheets (see screenshot).

Then briefly test whether the design is displayed correctly again. You can make the necessary corrections and fine-tuning after updating to Contao 5.3.

Remove mobile layouts

Just like the internal CSS editor, the mobile layouts have also been removed. If you used this feature, you must implement responsiveness for mobile devices directly in the CSS via corresponding MediaQueries.

Adjust PHP version

Change your webserver to at least PHP version 8.1. However, PHP 8.3 or newer would be better. After the changeover, you should update "All packages" again via the Contao Manager.

Change website root to public

You may have already done this with the update to Contao 4.13 but if this is still a to-do, it is best to take this step now.

Rename the "web" folder on your server to "public".

Then open "composer.json" and remove the entry "public-dir": "web" under "extra".

After this change you have to update all packages in the Contao Manager.

Update packages

Log in to the Contao Manager and adjust the corresponding Contao version. To do this, click on the cogwheel next to the Contao version and enter 5.3.* here.

Then click on "Apply changes" at the bottom and select the "Update all packages" entry in the dropdown.

If the update process was successful, you can perform the corresponding database updates directly via the Contao Manager. (Note: The Contao Install Tool no longer exists in Contao 5). If you see deletions, please check carefully whether they are justified. If in doubt, do not carry out any deletions at first and complete them later.

Help, my update fails!

If an error occurs during the update, check the output of the Contao Manager carefully. It is often possible to recognise here what is causing the problem.

In our experience, incompatible extensions usually prevent the update to Contao 5, which you should have already noticed during the analysis phase. Depending on the solution approach, you may need to remove the extension during the update process or adjust the version condition.

Example: Remove Notification Center 2.0 & Easy Themes

Let's assume you used both extensions under Contao 4.13. In this case, change the Contao version to 5.3.*. However, this alone is not enough. You must also change the Notification Center to ^2.0 and remove Easy Themes, as it is not compatible with Contao 5. Only then do you click on "Update all packages".

Use Twig or HTML templates

With the release of Contao 5, all core content elements have been converted to Twig templates. As a result, the markup has changed and the corresponding CSS classes of the elements have been renamed.

If you do not want to switch to Twig at the moment, you can continue to use the HTML templates (legacy templates). Please note, however, that you will have to make up for this change in one of the upcoming updates, as support for the old templates will not be continued forever.

As a rule of thumb, I recommend making the decision based on the number of customised templates. For a small number, I definitely recommend using Twig, while for a larger number, it makes more sense to use HTML templates due to the effort involved.

Now make your decision - Twig or HTML.

A) Activate legacy templates

If you have decided to do this, you can add the configuration for the desired content elements via contao/config/config.php. As you can see, a mixture of Twig and HTML elements is possible, as you can make the decision per element.

// Restore legacy content elements
$GLOBALS['TL_CTE']['texts']['code'] = \Contao\ContentCode::class;
$GLOBALS['TL_CTE']['texts']['headline'] = \Contao\ContentHeadline::class;
$GLOBALS['TL_CTE']['texts']['html'] = \Contao\ContentHtml::class;
$GLOBALS['TL_CTE']['texts']['list'] = \Contao\ContentList::class;
$GLOBALS['TL_CTE']['texts']['text'] = \Contao\ContentText::class;
$GLOBALS['TL_CTE']['texts']['table'] = \Contao\ContentTable::class;
$GLOBALS['TL_CTE']['links']['hyperlink'] = \Contao\ContentHyperlink::class;
$GLOBALS['TL_CTE']['links']['toplink'] = \Contao\ContentToplink::class;
$GLOBALS['TL_CTE']['media']['image'] = \Contao\ContentImage::class;
$GLOBALS['TL_CTE']['media']['gallery'] = \Contao\ContentGallery::class;
$GLOBALS['TL_CTE']['media']['player'] = \Contao\ContentPlayer::class;
$GLOBALS['TL_CTE']['media']['youtube'] = \Contao\ContentYouTube::class;
$GLOBALS['TL_CTE']['media']['vimeo'] = \Contao\ContentVimeo::class;
$GLOBALS['TL_CTE']['files']['downloads'] = \Contao\ContentDownloads::class;
$GLOBALS['TL_CTE']['files']['download'] = \Contao\ContentDownload::class;
$GLOBALS['TL_CTE']['includes']['teaser'] = \Contao\ContentTeaser::class;

After the change, you have to recreate the application cache once via the Contao Manager. Contao will then continue to use the old HTML templates and you will have to make very few changes to your old CSS instructions. However, a check is still important.

B) Use Twig templates (recommended)

In the long term, it makes much more sense to switch to Twig, as this step is inevitable sooner or later. If you decide to do this, however, you will have to re-customise your existing templates in Twig.

As this topic is very complex, I cannot go into it in this article. If you do not yet have any knowledge of Twig, here are a few sources:

• Contao manual
• Lecture by Maren Lange (YouTube)
• Twig for Template Designers (Symfony)

If you have not yet customised any templates, but only use the core templates, then you only need to adapt your CSS accordingly.

New content elements for slider and accordion

To make the migration and transition to Contao 5 easier, the old sliders and accordion elements are still supported here. You can recognise these in the back end by the addition (legacy). Again, you can decide whether you want to continue using the old elements or switch to the new elements.

If you decide to switch, you must create the elements again and also extend the CSS accordingly.

Check log file

Take a quick look at the log file. You can find it under /var/logs/prod-*.log or in the "Contao Manager" under "Tools and System Log". Are there any new error messages that need to be fixed?

Further reworking

• Replace logout module with logout page
• The "Show only for guests" function has been removed and will be rewritten in the migration script during an update. In future, use the "Protect page" function instead.
• The {{post::}} insert tag has been removed. To access submitted form data on redirect pages, you can use the new {{form_session_data::}} insert tag instead.
• The RSS feed can no longer be found in the news archives, instead there is a separate page of the news feed type (hide it in the menu if necessary)
• The meta fields (date, author and comment) for the news can no longer be configured via the module. In future, the template news_full, news_latest, news_short will always display the info line with date and author. Everything else must be done directly in the template.
• In the frontend module of the login form, you have the option of inserting a link to the password reset page.
• The image margin function is no longer available. If required, margins must be added via the central CSS.

How can trakked support you after the update to Contao 5.3?

We originally developed trakked to free us from the annoying maintenance of Excel lists. Over time, trakked has developed into a powerful toolbox for the maintenance of Contao. Especially with the integrated update function, it is easy to provide your Contao 5.3 installations with bugfix updates and keep them up to date. This reduces the update effort by an estimated two thirds. A complete list of trakked's features can be found here.

For us and many of our customers, trakked is an indispensable tool for managing Contao installations and keeping up with maintenance contracts.

Try it now without obligation!

Try trakked for 30 days without obligation and convince yourself of our tool.

Try trakked

You are unsure whether trakked is worth it for you? Then maybe our calculator will help you.

Update notes for known extensions

In this section we collect reworks that we have identified in our updates in connection with known Contao extensions.

Contao Cookiebar [oveleon/contao-cookiebar]

The Contao Cookiebar is compatible with Contao 5 from version 2.0. You can find the documentation for the extension on GitHub.

Easy Themes [terminal42/contao-easy_themes]

The extension is no longer being developed and is no longer available under Contao 5. However, you do not have to do without the advantages of Easy Themes in Contao 5. Use the built-in "star (save favorite)".

Isotope eCommerce [isotope/isotope-core]

Isotope is currently not compatible with Contao 5. However, there is already an appeal for fundraising and a blog post on Isotope.

MetaModels [metamodels/core und weitere]

MetaModels is compatible with Contao 5.3 from version 2.4. This can be obtained via the «early adopter program».

mmenu - Mobile navigation for Contao [dklemmt/contao_dk_mmenu]

The extension is compatible with Contao 5 as of version 4.1.

Notification Center [terminal42/notification_center]

The Notification Center is compatible with Contao 5 from version 2.0. You must therefore change the version condition here. Since this is a complete rewrite of the extension, certain functions have been adapted and some have been omitted. More about this in the UPGRADE.MD.

RockSolid Custom Elements [madeyourday/contao-rocksolid-custom-elements]

The following adjustments are necessary when configuring the individual elements:

Old:

'image' => array(
    'inputType' => 'fileTree',
    'eval' => array(
        'extensions' => \Config::get('validImageTypes'),
    ),
),

New:

'image' => array(
    'inputType' => 'fileTree',
    'eval' => array(
        'extensions' => '%contao.image.valid_extensions%',
    ),
),

Old:

'imageSize' => array(
    'inputType' => 'imageSize',
    'options' => \System::getImageSizes(),
),

New:

'imageSize' => array(
    'inputType' => 'imageSize',
    'options' => \Contao\System::getContainer()->get('contao.image.sizes')->getAllOptions(),
),

If your customer prefers to use basic entities in a text field (e.g. [ - ] instead of ­), you must activate the field definition in the DCA.

'eval' => array('basicEntities'=>true,)

Testing

As after every major update, you should check the website accordingly. Don't forget to test the dispatch of the forms.

Conclusion

Fortunately, many extensions are already compatible with Contao 5. An update is therefore already possible today for many installations. However, you should not underestimate the update to Contao 5.3 and allow enough time. Especially if you have customised numerous templates and want to switch completely to Twig.

Please let us know your experiences with known extensions and we will add your suggested solutions to our article.