With each major version of TYPO3 there has more or less work to be done to upgrade to the next major version. Every next upgrade project brings its own challenges. Following these recommendations, will ease your pains (hopefully).

There are two kinds of challenges: The conceptual and technical ones. Before the technical upgrade it is really necessary to have a clear picture what and how to upgrade. I think, every major TYPO3 upgrade is a chance to rid of “conceptual depth”. Questions to identify conceptual depth are:

Conceptual challenges

Is the functionality really needed?

Over the lifetime of a website it will grow in functionality and (in most cases) in additional extensions. An upgrade is a good chance question these decisions. A good helper is the extension “additional_reports”. It allows to check how often a content element or extension is used in an installation. If it is barely used, just drop it or replace it with a more future proof solution.

Can an existing extension be replaced with a more future proof solution?

There are several extensions around that had quite an impact on the TYPO3 universe, like “templavoila”, “tt_news” or “realurl”. It is possible to stick to these, maybe also with successor extensions like “templavoila_plus” or fork of “realurl” for TYPO3 9LTS. But it is also the time for to ask, what is future proof and which solution is the best for the next years.

The best is to look for solutions that are use solely the core API and functionality. Especially custom content elements using fluid, dataprocessors and the combination of EXT:mask and EXT:mask_export have a great potential to replace many custom solutions.

Updating existing extensions

If the two already suggested alternatives provide no viable solution, the extension must be updated. There are again two possibilities:

• Keep it alive as is and just make all breaking changes work
• Take the chance and rewrite at least partials of it, to take advantage of new technologies, like PSR middlewares

My personal favorite is the second one, but it depends also on what the customer want to spend and how he sees the future in using the features. If he expects, that there is no use for the feature in the future, may be it is time to drop it. (see last first paragraph).

If it is clear, which functionality should be taken to the next version, the next challenge is to master it technically.

Make a plan

This sounds quite obvious, but it really helpful to know what to do when. It must be written down and must contain each an every single step, even the small ones. Having such a written plan makes the customer (and you) trust in the process of the upgrade.

There are at least five phases in an upgrade project. The phases 2 to 4 should be as short as possible.

Phase 1: Preparation

A migration will be well prepared, especially if functionality will be removed or replaced. All editors must help to cleanup structure and content of the website. The goal is to make the migration as easy as possible.

Another task in this phase is to create a section in the pagetree, where every available feature and view is visible. It is also the place where the customer “agrees” that these features are in the website and that these must be available after the upgrade and migration. From a testing perspective it also the only part of the pagetree you must test. If a feature works here, it can be considered to work for the editors too.

The end of this phase it the “content freeze”. The “content freeze” is the point, where a snapshot of the database and the files are taken, which are the base for the upcoming migrations. After this point, no content should be edited any more on the legacy instance. Depending on the time needed for automatic and manual migrations, it might be necessary to open the TYPO3 backend for some or all editors. But it must be clear, that all changed content must be edited twice after the content freeze: on legacy and the new instance.

Phase 2: Automatic migrations

This phase is quite short. It means importing the current live state of the website, let your update scripts run. Depending on the changes this may take just 20 minutes or several hours. After that, test your page tree containing all the functions. Everything should be fine there.

Phase 3: Manual migrations

The next phase is to open up the new instance to the editors and let them do their manual work (if any). Each action, that will be taken in that phase, must be completely documented and communicated to the editors.

This is also the phase, where the changed content from the legacy instance is edited again on the new one.

Phase 4: Going live

This is about changing DNS records or vhost entries and providing the new site to the public.

Phase 5: Party

After each launch there must be also time for the team to party and to be happy about the achieved result. Btw, this is not the time to do a retrospective or review. It is just time to party.

Technical challenges

Automate as much as possible

The automation of the upgrade process helps in many ways:

It is fast: It is faster to run the upgrade wizards per scripts than clicking manually through the install tool, for example.

It is repeatable If there is an error in the migration, edit the script and run the migration again. At the time of the feature freeze, you can just change the db import and run the migration again.

It is less error prone Manual work has always the risk, that errors occur at different places. Automating it, means to make an error once, fix it in the script and you are done with it.

But how to do it? Good that there are two boilerplates, that help to manage automation.

TYPO3 Upgrader by Franz Kugelmann (elementare teilchen)

It is advertised as a boilerplate to ease the upgrade from TYPO3 6.2 to 8.7. But I think the concept behind works also for other upgrades of TYPO3.

The suggested steps are:

• (1) start with a clone of the existing project
• (2) switch directly to the wanted TYPO3 core version
• (3) upgrade all TYPO3 extensions to the new TYPO3 version
• (4) install the EXT:upgrader
• (5) develop the steps necessary to make your installation smoothly with the wanted TYPO3 version
• (6) fix your error and re-run the script

The upgrader is available at https://github.com/ElementareTeilchen/upgrader

I used it already in a projects and I must say, it really helped to re-run the migration and to make it safe and trustable. At step 5 they provide some examples, how to run custom sql commands while upgrading. This will be hard in some (or more) cases, like switching from EXT:tt_news to EXT:news. Another example is, when you want to replace EXT:templavoila with EXT:gridelements and custom content elements.

This is where the “ImporterBoilerplate” of Alex Kellner comes in.

TYPO3 ImporterBoilerplate by Alex Kellner (in2code)

The ImportBoilerplate helps to manage complicated imports and migrations. An import is an actions that maps fields and moves contents of a legacy table to a new one, like from EXT:tt_news to EXT:news. Migrators help to transform existing records in tables. Such a migration can switch a record in the table tt_content using EXT:templavoila to EXT:gridelements.

Each migration or import is encapsulated in a separate class. You need to code each step in one of these classes. The project brings quite extensive examples in the readme of the project.

The boilerplate also allows to run single imports or migrations via command line. It possible to limit it to a single migration / import and to a single record on a table. Furthermore you can do a “dry-run” without any actual changes to the database.

The ImporterBoilerplate is available at https://github.com/einpraegsam/ImporterBoilerplate

Performance: Use two databases

Importing the database of the legacy instance, is probably one of the most time consuming tasks in an upgrade process, because it is necessary after each migration that went wrong.

A solution on that might be to work with two databases: The one with the old structure and data and the new one. With Doctrine DBAL it is possible to define several database connections. The records are read from the old and written to the new instance. With that setup it is possible to re-run a migration without resetting the database.

Conclusion

I hope that these hints will ease the pain in your upcoming and maybe already running upgrade projects.

Credits

I want to thank my supporters via patreon.com, who make this blog post possible. This week, I want to thank Syiblle Peters for her contribution.

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 fxxu under the CC0 public domain license. It was modified by myself using pablo on buffer.