In every TYPO3 major version there are backwards incompatible changes, which may (and probably will) effect your extension(s). This hurts hard, especially, if you must upgrade custom extensions, which were written by other developers or agencies. These six information sources and tools, which come with TYPO3, will help you to get over these hurdles.
1) Documentation about necessary changes
First of all, all the breaking changes and new features are documented and available available via the install tool. In version 9 you need to go to “Upgrade” and the click on “Upgrade documentation”. In TYPO3 8LTS this function is located under the menu entry “Upgrade analysis”.
This will open a list of (breaking) changes, which you need to consider while upgrading.
The changes are grouped by sprint release and split into four categories: “Breaking”, “Deprecation”, “Feature” and “Important”. “Breaking” means, what make your extension or website break right now. Under “Deprecation”, you find everything, which will make your extension break in the future.
If you click on a issue, it will be expanded and you can read an explanation of the impact and how to circumvent it.
Additionally this documentation is also available on https://docs.typo3.org/typo3cms/extensions/core/.
2) Deprecation Log
Now, after you have the overview over the changes, you still do not know, which of them will hit you. This is where the deprecation log comes in. If activated, it logs all deprecated functions to a file within the typo3conf directory.
The deprecation log can be activated in the InstallTool by setting the value of $GLOBALS['SYS']['enableDeprecationLog]
to “file” … Or if you want to activate other debug and log possibilites, you can set the “Debug settings” to “Debug” in the section “Configuration presets” of the install tool.
Each call of a deprecated functions creates a new entry in the log file. This also means that the log file will grow constantly and will contain many, many duplicate entries. The extension “deprecationloganalyzer” filters out all the duplicates of the deprecation log file and displays them in the reports module.
This functionality is deprecated for extensions in TYPO3 version 9 and not used by the core any more. Instead the deprecations run through the normal logging process and are logged in the Module “System” => “Log”.
3) TYPO3 Extension Scanner
This is where the brand new TYPO3 Extension Scanner comes in. It is an static code analyzer which checks your extensions and list all the possible issues that may occur.
You find the Extension Scanner in the module “Admin Tools” => “Upgrade” (1). A click on “Scan all” scans all installed extensions. Clicking on an extension name opens a section, which lists all lines that need attention (3).
Each block can be expanded to get more details about the possible issue. It mentions the line of code (4), where the issue occurs and connects it with the changelog documents. (These are the same docs as in the first paragraph).
As it is “only” a static code analyzer based on rules, you need to keep in mind, that there also may be false positives.
4) Check TCA and TCA Migrations
This card in the upgrade sections checks your extensions, whether they still modify TCA values in the file “ext_tables.php”. If this is the case, you must move all these TCA modifications to the folders <extension>/Configuration/TCA/
or <extension>/Configuration/TCA/Overrides
. The second folder is for modifying the TCA of other extensions and tables.
With the “TCA Migrations” you check the extensions TCA for deprecated field definitions. After the test you receive a list with all fields that contain deprecated or removed definitions. Unfortunately there are no hints to the issues on forge, where the changes are described and update instructions are published. You must look them up by yourself.
5) Upgrade to php7
Another hard part can be to upgrade your code to php7, as it is a requirement for TYPO3 8LTS or later. phpStorm is probably the most used IDE in the TYPO3 community and offers the nice feature of inspections. With this feature you can test the code whether is complies to the the rules set.
The inspections are set in the editor configuration of the settings. The used language level depends on the php settings in the section “Languages & Frameworks”.
6) Upgrade your documentation
A quite easy part of upgrading is to move your extension documentation from the deprecated OpenOffice sxw format to ReStructured Text, which is the default format since 2013.
Martin Bless showed in a sneak peek on twitter a feature, which is coming soon the TYPO3 documentation server. You will be able to download a converted version of your sxw and just add it to your extension. In a second step you need to remove the old sxw documents.
https://twitter.com/marantern/status/925356341052534784
I wrote already some articles about TYPO3 documentation and tools:
- SPHINX – Easy Rendering of ReST Documentation
- Guide to TYPO3 Documentation – Part 3: Contribution and ReST Helpers
Conclusion
Keeping extensions up to date with the current core is or at least should be an ongoing effort. If you face an upgrade and are not so much into extension development, these tools and informations will help you, to get an overview over what has to be done and to estimate the effort of the actions to take.
Another legitimate question is, whether it is worth upgrading an extension or better switch to an alternative. Alternatives may be
- using another extension
- using a solution, which is more close to the core, (f.e. for content elements)
- dropping the functionality completely
Credits
I want to thank my supporters via patreon.com, who make this blog post possible:
If you appreciate my blog and want to support me, you can say “Thank You!”. Find out the possiblities here:
I found the blog post image on pixabay . It was published by KTMPHOTOGRAPHY under the CC0 public domain license. It was modified by myself using pablo on buffer.