But first a few terms: TYPO3 distinguishes between major releases and minor releases. Major releases are the first, name-giving number of a version. So TYPO3 11 LTS is actually version 11.5, TYPO3 10 is version 10.4. A major version contains significant changes compared to the previous major version.
The second number indicates the subversion. Until the stable LTS version is released, the new major version goes through several stages, in which new functionalities are added and existing errors in the innovations are corrected. The LTS version is the first stable minor version and contains all new functions and innovations. Therefore, the minor versions are to be neglected in an update/upgrade. Because as long as the LTS version has not yet been released, an upgrade is not worthwhile, since the version has not yet been fully developed.
After the release of the LTS version, only minor versions follow. They are in third place of the version number and contain bug fixes and security updates. The current TYPO3 is version 11.5.18 (as of November 2022). This means that TYPO3 11 LTS has already received 18 patches. It is therefore generally advised to wait several months after the release of an LTS version before updating your instance, because a particularly large number of patches are released during this time. When upgrading from one minor version to another, it is often referred to as an update. Switching to another major version, on the other hand, is called an upgrade. An upgrade with one or more major versions in between is also called a version jump, e.g. an upgrade from TYPO3 8 LTS to TYPO3 11 LTS. – We would like to take a look at the upgrade process. Depending on the TYPO3 version, there are different things to consider. However, the basic steps of an upgrade are always similar.
Preparations
If you've dealt with upgrades before, you'll probably have read and heard that upgrades should never be performed on a live instance. Not without reason: any upgrade/update can go wrong and not all complications that occur are predictable. In a pinch, you can continue to use your old instance should something not work. Therefore, the existing instance should be copied first to be able to perform the upgrade on this copy. Furthermore, it is recommended to have a backup ready in case structures break during the upgrade that need to be restored. For the backup or copy of a TYPO3 instance you have to do two things: copy all files and copy the database. During the whole upgrade process there should also be a content freeze, so that content does not have to be entered twice (before and after the upgrade). All the steps described below can also be found on the official TYPO3 website.
System requirements
Before the actual upgrade begins, it is also necessary to check whether the system requirements for the new version are met. Thus, it is advisable to use a PHP version that is as up-to-date as possible and compatible with the desired TYPO3 version. In the case of TYPO3 11 this is PHP 8.1.
Extensions
Before you start working with the copy, you should check if the copy works the same way as the live instance. In the course of this, the extensions should also be checked for deprecations by the deprecation log in the install tool, which should run for a few days. Alternatively or additionally the extension scan should be used. The deprecations should be resolved before the upgrade.
Extensions that are no longer needed do not need to be updated and can be deleted directly, so that the effort can be reduced at this point. After all, updating extensions is often the more time-consuming part of an upgrade, in contrast to the actual TYPO3 core update.
It is possible that extensions are compatible with the desired TYPO3 version, but not with the used PHP version of the new TYPO3 version. Then an older PHP version must be used or you have to abandon such extensions, because in many cases they will be dropped sooner or later anyway and you have to look for alternatives. Furthermore there can be extensions, which are shown as not compatible, but still work on the new TYPO3 instance, here you have to test a little bit. Many extensions are easy to update to the latest version and can be used after the upgrade of the instance. But sometimes the latest version is not available for the TYPO3 instance, here it can be worthwhile to update the extension to the highest possible version and bring it to the latest version after the upgrade. Some extensions have to be deactivated before the upgrade, they will be updated afterwards. Then there are custom extensions that may need to be specially adapted to the new version. This would probably require the most effort, so the best case scenario for the future is to rely on other solutions.
Update reference index
The global reference index manages links between content items and files. Checking and updating the global reference index can happen in two different ways: either via the command line (CLI) or via the DB Check module (in the Admin Modules). Since the process can take a long time, especially for large websites with many pages and files and if it is not done regularly, the method via CLI is recommended. The DB check is an alternative especially for small websites with few subpages and files.
Check changelog
This step is optional, but it is advisable to prepare an upgrade well, also by informing yourself thoroughly. Each changelog of a version contains the items 'Breaking Changes', 'Important', 'Features', and 'Deprecations'. It is recommended to look at least at the 'Breaking Changes' and the topics under 'Important'. There are different ways to read the changelogs: in the extension scanner, in the backend in the upgrade module in the system modules or online. On the official TYPO3 website you can also find the changelog for TYPO3 11. The upgrade module has the advantage that you can filter by tags and check off changelogs like a to-do list.
TYPO3 Core Upgrade
The necessary TYPO3 sources can be fetched via composer or wget (or cURL) from the typo3.org website. With the command composer info typo3/*
all currently used TYPO3 packages are listed in the installation. Each package has to be updated during the upgrade. With the Composer Helper Tool you can easily generate an upgrade command. Typically dependency errors occur in the course of this. On typo3.org you can find all information about the TYPO3 core update and a description how to deal with these errors.
Follow-up
All steps that have to be done after the TYPO3 core update, you can also read on the official TYPO3 page.
Upgrade Wizard
After that, the Upgrade Wizards must be run. This is located in the installation tool, which can be opened via example-website.com/typo3/install.php
. In the Upgrade Wizard you will find several steps that you should perform one after the other. It starts creating missing database tables and fields. However, you can also perform all the upgrades in the command line.
Some steps in the Upgrade Wizards include functions you may not need, be careful not to execute them.
Analyze database
After that, go to the Maintenance module and use the option to analyze database. The result will show a list of changes, almost all of which can be executed. Be careful when deleting tables that are supposedly no longer needed, make sure that they can actually be deleted before executing the change.
Last steps
You should also update the language packs in the maintenance module. You may want to reset the user settings in the same module. In any case, also clear the cache in Maintenance and remove temporary assets with 'Clean Up' in the install tool.
Comments