Update from Contao 4.13 to Contao 5.3

You want to update your Contao website to the latest LTS version 5.3, but don't know where to start? Don't worry, in this blog post you will learn step by step how to successfully carry out the update!

It would be great if trakked could perform the update for you with a single click, but unfortunately this is not technically feasible. A major release from Contao version 4 to 5 requires numerous manual adjustments that cannot be carried out automatically by trakked. However, trakked will be happy to support you in keeping your 5.3 LTS version up to date.

Requirements for the Contao 5.3 update

In principle, the update is relatively easy. You start the Contao Manager and change the version condition from 4.13.* to 5.3.*.

Sounds too good to be true, right? Exactly. Be careful, this seemingly simple step requires careful planning. With thorough preparation, you can avoid potential problems in advance and save yourself a lot of frustration. I therefore strongly recommend that you read the entire article carefully and through to the end before you start the update.

It is important to emphasise that sufficient knowledge of Contao is required for a successful update. If you are unsure or lack the necessary expertise, you should definitely consider having the update carried out by an experienced Contao specialist.

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".

Be sure to read the upgrade instructions from the extension creator. It may well be that the new version requires extensive reworking, features have been removed or you have to completely reconfigure them.

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:

Fulfilled all requirements?

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

Prepare update

If nothing stands in the way of the update to Contao 5.3, we can start right away.

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".

The path change must also be made in the domain configuration in the hosting.
Example: example.com points to the directory /www/example/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.

Perform Contao 5.3 update

Once all the preparations have been completed, we are ready and you can start updating the packages.

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".

You don't have to do without the advantages of Easy Themes in Contao 5. Use the "star (save favorite)": By clicking on this link, you can save the current URL as a favorite entry in the back end. Existing favorite links are listed in the navigation area.

Carry out rework

Once the packages have been successfully updated, your back end and front end should be accessible again. However, due to the numerous new features of Contao 5, the rework is relatively extensive. If you haven't already done so, take a look at Contao's UPGRADE.md on GitHub.

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.

Modules such as News, FAQ or Events do not yet use Twig.

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:

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

Customise CSS (Twig)

If you have opted for the Twig variant, the CSS classes of the content elements will change.

Here is an overview:

Content elements

  • code (ce_codecontent-code)
  • headline (ce_headlinecontent-headline)
  • html (ce_htmlcontent-html)
  • list (ce_listcontent-list)
  • text (ce_textcontent-text)
  • table (ce_tablecontent-table)
  • hyperlink (ce_hyperlinkcontent-hyperlink)
  • toplink (ce_toplinkcontent-toplink)
  • image (ce_imagecontent-image)
  • gallery (ce_gallerycontent-gallery)
  • youtube (ce_youtubecontent-youtube)
  • vimeo (ce_vimeocontent-vimeo)
  • download (ce_downloadcontent-download)
  • downloads (ce_downloadscontent-downloads)
  • markdown (ce_markdowncontent-markdown)
  • player (ce_playercontent-player)
  • teaser (ce_teasercontent-teaser)

Image position

  • float_leftmedia--left
  • float_rightmedia--right
  • float_abovemedia--above
  • float_belowmedia--below
  • captionfigcaption

CSS class image_container

This class has been completely removed. Use the HTML tag <figure> in the CSS.

CSS classes first, last, even and odd removed

The CSS classes first, last, even, odd, row_* and col_* have been removed everywhere. If you have used these CSS classes, you must adapt your CSS accordingly and should replace them with CSS selectors (first-child, last-child, nth-child).

CSS classes in the gallery

Numerous CSS classes have been removed here. It is therefore essential that you check the correct display of your galleries in the front end.

CSS classes for ce_list and ce_table elements

The elements in the ce_list and ce_table templates no longer consist of an associative array that contains the CSS class and the content of the element. Instead, it only contains the content.

Old:

<?php foreach ($this->items as $item): ?>
  <li<?php if ($item['class']): ?> class="<?= $item['class'] ?>"<?php endif; ?>><?= $item['content'] ?></li>
<?php endforeach; ?>

New:

<?php foreach ($this->items as $item): ?>
  <li><?= $item ?></li>
<?php endforeach; ?>

Search your CSS for the above-mentioned CSS classes. A "search/replace" is often sufficient. Then take a look at your layout and correct the remaining errors.

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.

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. You can find more information on GitHub.

MetaModels [metamodels/core und weitere]

MetaModels is working on version 2.4 for Contao 5.3. As soon as a first version is available, it 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.

With version 2, terminal42 has also released a Pro version. Among other things, you can use it to log all your sent messages and resend them if necessary. Of course, you also support the development of the Notification Center itself. You can find more information in their extension store.

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 &shy;), 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.

Add a comment

Please calculate 1 plus 2.