TYPO3 distinguishes between major releases and minor releases. Major releases are represented by the first, name-giving number of a version. For example, TYPO3 12 LTS actually stands for version 12.4, while TYPO3 11 is version 11.5. Major releases contain significant changes compared to the previous major version. The second number in the version number indicates the secondary version. Until the stable LTS version is released, a new major version goes through several stages in which new functions are added and existing errors are corrected. The LTS version represents the first stable secondary version and contains all new functions and improvements. The minor versions prior to the LTS version should therefore be disregarded when updating or upgrading. An upgrade is only worthwhile once the LTS version has been fully developed.
After the release of the LTS version, only minor versions follow, which are in third place in the version number and mainly contain bug fixes and security updates. The current TYPO3 is version 12.4.10 (as of January 2023), which means that TYPO3 12 LTS has already received several patches. It is generally advisable to wait a few months after the release of an LTS version before updating your instance, as many patches are released during this time.
The transition from one minor version to the next is called an update, while an upgrade is the change between major versions. An upgrade with several major versions in between is also referred to as a version jump, for example when upgrading from TYPO3 9 to TYPO3 12. A version jump is usually more complicated than an upgrade to the next version, as several upgrades to the next version are carried out. The process of a TYPO3 v12 upgrade is described in more detail below, whereby the basic steps for an upgrade are always similar, regardless of the TYPO3 version.
Preparations
If you have already dealt with upgrades, you will probably have read and heard that upgrades should never be carried out on a live instance. There is a reason for this: any upgrade or update can go wrong, and not all complications that arise are foreseeable. To be on the safe side, first create a copy of the existing instance on which the upgrade can be performed. It is also advisable to have a backup ready in case structures are damaged during the upgrade and need to be restored. Creating a copy or backup of a TYPO3 instance requires copying all files (via FTP, SCP, rsync or another method) and exporting the database to an SQL file. A content freeze should also be maintained during the entire upgrade process so that content does not have to be entered twice (before and after the upgrade). All other steps described can also be found on the official TYPO3 Website.
System requirements
Before the actual upgrade begins, you must also check whether the system requirements for the new version are met. It is advisable to use a PHP version that is as up-to-date as possible and compatible with the desired TYPO3 version. For TYPO3 12, PHP 8.1 is a minimum requirement.
Update extensions
Before working with the copy, you should check whether the copy works in the same way as the live instance. In the course of this, the extensions should also be checked for deprecations using the deprecation log in the Install Tool. This 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 required do not need to be updated and can be deleted directly to reduce the effort involved. This is because updating extensions is often the more time-consuming part of an upgrade compared to the actual TYPO3 core update.
It can happen that extensions are compatible with the desired TYPO3 version, but not with the PHP version used in the new TYPO3 version. In this case, an older PHP version may have to be used, or the use of such extensions may have to be abandoned as they will become obsolete sooner or later anyway and alternatives will have to be found. Furthermore, there may be extensions that are displayed as incompatible but still work on the new TYPO3 instance. Some testing is required here. Many extensions can simply be updated to the latest version and continue to be used after the instance has been upgraded. However, sometimes the latest version is not available for the old TYPO3 instance. In this case, it may be worth updating the extension to the highest possible version and upgrading to the latest version after the upgrade. Some extensions must be deactivated before the upgrade and will then be updated after the upgrade. Individual extensions may need to be specially adapted to the new version. This could mean the greatest effort, so it may make sense to use other solutions in the future.
Check reference index
The global reference index manages links between content elements and files. This index can be checked and updated in two ways: either via the command line (CLI) or via the DB check module (system modules). As the process can take a lot of time, especially for large websites with many pages and files, and does not need to be carried out regularly, the method via the command line 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 advantageous to prepare an upgrade carefully. Each changelog of a version contains items such as Breaking Changes, Important, Features and Deprecations. It is recommended to at least look at the Breaking Changes and the points under Important. The changelogs can be read in different ways: in the extension scanner of the upgrade module in the system modules or online. On the official TYPO3 website you can also find the changelog for TYPO3 12. The Extension Scanner offers the advantage that you can filter by tags and work through changelogs like a to-do list.
Convert Global Extensions
In previous versions of TYPO3, global extensions were an easy way to share extensions between multiple TYPO3 instances. Nowadays it is recommended to install and maintain extensions via the Composer. Therefore with TYPO3 v12 the support of global extensions has been removed, they have to be converted to local extensions.
To convert a global extension into a local one, you must uninstall the global extension in the Extensions backend module (under Admin Tools). Furthermore, the files of the extension must be deleted from typo3/ext/
, including the directory of the extension itself. The extension must then be reinstalled from the TYPO3 extension repository, whereby it is stored in typo3conf/ext/
.
TYPO3-Core Upgrade
The required TYPO3 sources can be obtained either via Composer or by using wget (or cURL) from the typo3.org website. The command composer info typo3/*
lists all currently used TYPO3 packages in the installation. Each package must be updated during the upgrade. An upgrade command can be easily generated using the Composer Helper Tool. As a rule, dependency errors occur. On typo3.org you can find all information about the TYPO3 core update as well as instructions on how to deal with these errors. Please also note the breaking changes for TYPO3 v12.
Follow-up work
All necessary steps that have to be carried out after the TYPO3 core update can also be found on the official TYPO3 website.
Upgrade Wizard
After the TYPO3 core update, the upgrade wizard should be run. You can access it by opening the installation tool via example-website.de/typo3/install.php
. The Upgrade Wizard guides you through several steps, starting with the creation of missing database tables and fields. All updates can also be carried out in the command line.
Some steps in the Upgrade Wizard contain functions that may not be needed and should not be carried out.
Analyze database
After the upgrade, you should go to the maintenance module and use the option to analyze the database. The results show a list of changes, almost all of which can usually be carried out. Special attention should be paid to tables that are no longer required. You should check whether these can really be removed.
Last steps
The language packs should be updated in the maintenance module. It may be necessary to reset the user settings in the same module. In any case, the cache must be emptied under Maintenance and temporary assets must be removed in the Install Tool using the Clean Up option.
Comments