Before You Start¶
Before starting the upgrade check your system for compatibility with a newer TYPO3 version.
- Enable the deprecation log and let it run for a while while the website is used to catch all deprecations
- Check installed extensions for versions compatible to the target TYPO3 version
- Try the upgrade on a development system first or create a parallel instance
- Run the extension scanner (see below)
If you notice some API you are using is deprecated, you should look up the corresponding ChangeLog entry and see how to migrate your code corresponding to the documentation.
Since TYPO3 v9 an extension scanner is included, that provides basic scanning of your extensions for deprecated code. While it does not catch everything, it can be used as a base for an upgrade. You can either access the extension scanner via the TYPO3 admin tools (Backend > Module “Upgrade” > “Scan Extension Files”) or as a standalone tool (https://github.com/tuurlijk/typo3scan)
Read where to find deprecation documentation in the chapter about Check the ChangeLog.
TYPO3 aims at providing a reliable backwards compatibility between versions:
- Minor versions are always backwards compatible - unless explicitly stated otherwise (for example in case of security updates)
- Major versions may contain breaking changes - normally these are deprecated one major version in advance
- Most breaking changes usually happen in the first Sprint Release
If PHP classes, methods, constants, functions or parameters are to be removed, they will be marked as deprecated first and not removed until the next major release of TYPO3. For example: a method that gets deprecated in version 9.4.0 will remain fully functional in all 9.x.x releases, but will be removed in version 10.
This strategy gives developers sufficient time to adjust their TYPO3 extensions, assuming many agencies upgrade from one LTS release to the next (usually 1.5 years).
Upgrade Hints for version 9¶
Database Collation and Charset¶
If upgrading instances, admins may change
LocalConfiguration.php to use
and charset for allowing multibyte characters like emojis to be used in TYPO3.
The core does not provide mechanisms to update the collation of existing tables
utf8mb4_unicode_ci for existing instances, though. Admins need
to manage that on their own if needed, the reports module shows an information if the
table schema uses mixed collations. This should be fixed after manually configuring
utf8mb4 to avoid SQL errors when joining tables having different collations.
Note that manually upgrading to
utf8mb4 may lead to index length issues: The maximum key
length on InnoDB tables is often 767 bytes and options to increase that have even been actively
removed, for instance in recent MariaDB versions.
A typical case is an index on a varchar(255) field: The DBMS assumes the worst case for the index
length, which is 3 bytes per character for a utf8 (utf8mb3), but 4 bytes for utf8mb4: With utf8,
the maximum index length is 3*255 + 1 = 766 bytes which fits into 767, but with utf8mb4, this
is 4*255 + 1 = 1021 bytes, which exceeds the maximum length and leads to SQL errors when setting
such an index.
This scenario gets more complex with combined indices and may need manual investigation when
upgrading an existing instance from from
utf8mb4. One solution is to restrict the
index length in ext_tables.sql of the affected extension:
KEY myKey (myField(191)), which
in this case leads to 4*191 + 1 = 764 bytes as maximum used length.
The basic settings to use
'DB' => [ 'Connections' => [ 'Default' => [ 'driver' => 'mysqli', ... 'charset' => 'utf8mb4', 'tableoptions' => [ 'charset' => 'utf8mb4', 'collate' => 'utf8mb4_unicode_ci', ], ], ], ],