Blog single

The Ultimate Guide on TYPO3 Upgrade

Being the expert speaker at TYPO3 Developer Days T3DD and TYPO3 Conference T3CONF18, I covered two most crucial and trending topic on “TYPO3 Upgrade/Update”.

Being the expert speaker at TYPO3 Developer Days T3DD and TYPO3 Conference T3CONF18, I covered two most crucial and trending topic on “TYPO3 Upgrade/Update”

I'm glad to receive great applause and appreciation from the TYPO3 lovers! Likewise, from the network's kin requests, here I'll compose a point by point blog about "TYPO3 Upgrade”.

You may refer to Slides/Presentation represented at

TYPO3 Upgrade is one of the most crucial tasks for TYPO3 Agencies and Developers.

In my long journey of TYPO3 (almost 10+ years), I’ve done many websites (Medium to Large-scale) TYPO3 upgrade from old-school version 4.x to modern 8.x and 9.x.

Here, I would like to share my experience which will help for Beginners to Expert level TYPO3 developers & agencies. 

After reading this blog, I’m sure, You will have good enough knowledge to perform the TYPO3 upgrade well, and your client will be more than Happy :)

Website Relaunch vs TYPO3 Upgrade (guide to your customer)

Source: https://typo3.org/cms/roadmap/

Website update can be categorized into major three categories as follows:

Option 1: Minor Updates
The TYPO3 community continuously releases the security checks version with branch eg., TYPO3 8.7.12 You should always update TYPO3’s latest version. 

Check out the detailed report at https://get.typo3.org/release-notes/8.x/TYPO3_CMS_8.7.12 Generally, It only contains security patches & changes, so it’s easy to update in matters of 3/4 hours.

Option 2: Major Updates
It means You need to consider TYPO3 update version from one LTS (Long Term Support) to another LTS. 

Suppose, you have the TYPO3 website with TYPO3 6.x LTS, then you should consider an update to latest TYPO3 9.x LTS. It’s a bit difficult and complicated to update TYPO3, based on the site’s complexity & the number of extensions.

Did you know?
“TYPO3 is the only open source content management system with a vendor-level warranty.”

Option 3: Website Relaunch
Sometimes it's recommended to relaunch the website instead of doing TYPO3 update completely. Relaunch means whole brand new website development. 

There are many factors, where you can guide your customer to make a relaunch as follows:

  • TYPO3 update from 4.x to 8.x with very complex and old-school techniques?
  • Is your TYPO3 website is responsive?
  • Does your website perform well? eg., SEO, Industry standards, etc.,
  • Do you want a modern look website?
  • Are you facing the major issue on speed & performance?
  • Is your existing site have outdated code & techniques?
  • Is estimation efforts of Major update and Relaunch is almost the same?

Highly recommend reading CEO of TYPO3 GmbH’s article at How do you know when it's time to upgrade?

Importance of TYPO3 Upgrade

The software upgrade is very important to keep maintain the health of the website as like follows:

  • Secure Your Website
  • Long-term Software Support
  • Fix Technical Issues
  • Get New Features
  • Improve Speed & Performance

Facts & Figures of Security

1 millionnew malwares releases every day
40,000sites are hacked every day
86%sites contain at least one serious vulnerability
33%shoppers hesitate to shop because of lack of trust in the site
$500 billioncost of cyber-crime to the global community

Speed Matters

I’ve written a detailed blog about the importance of TYPO3 upgrade, Checkout here http://www.nitsan.in/blog/post/why-its-important-to-update-your-typo3-websites-on-a-regular-basis/ 

Business Opportunity

According to research, there are many old TYPO3 versions (like v4, v6, v7) are running in the market, that means there will be many TYPO3 sites which need to upgrade to TYPO3 v8 and/or v9.

Check out some survey report as follows:

By the end of 2018

  • Around 62% of all Internet sites will run an unsupported PHP version.
  • The highly popular PHP 5.x branch will stop receiving security updates.

How to analyze & estimate TYPO3 Upgrade?

Mostly, you will underestimate the TYPO3 upgrade project because there are lots of technical risks.

That’s why you should always take care well of analyzing the existing site to make proper estimation to make happy to your sales team & maintain a healthy relationship with the client.

Prepare TYPO3 Backend Report

Team NITSAN developed one of the great TYPO3 Extension call “ns_ext_compatibility”, You can download it from TER at https://extensions.typo3.org/extension/ns_ext_compatibility/

This extension will very helpful to generate TYPO3 compatibility with features like:

  • Extensions Compatibility Report
  • Automatic email notification for new version update
  • Compatible from TYPO3 4.x to 8.x
  • Export Feature for Customer
  • Extension Statistics  Report
  • Server Compatibility Report
  • System Overview Report

Estimation & Proposal Process
From the above analysis, I’m sure you will able to judge proper estimation of TYPO3 update. Even it’s the technical matter, You may send the detailed proposal to your client as follows:

  • x Hours: TYPO3 Upgrade from 4.x to 6.x to 7.x to 8.x
  • x Hours: Template Engine/Method change from Automaketemplate to Extbase/Fluid
  • x Hours: TYPO3 Extensions Upgrade (Number of non-compatible extensions * ~2 Hour)
  • x Hours: QA Testing + Bug Fixing
  • x Hours: Miscellaneous (design issues, feedback & support, deployment to DEV & LIVE etc., )

It’s always good practice to check the scope & complexity of the website. You may also write to the client about one of the most uncertainty of TYPO3 update as follows:

Notes for Non-compatible Extension
For such extension not compatible, We will do our best to make them compatible. If a particular extension will not work, then we will need to find a new solution & that will consider as extra efforts.

Step by step Guide to Upgrade Your TYPO3 Website

Source: https://typo3.org/

Let’s try to dig in depth at each phase of the TYPO3 upgrade. In general practice, I prefer to execute TYPO3 upgrade as follows:

Step 1: Setup at Local Server
Download & Setup everything from LIVE to your LOCAL server

Step 2: Perform TYPO3 Upgrade
At your LOCAL server, Start to Upgrade TYPO3 core, Upgrade extensions, QA Testing & Bug Fixing.

Step 3: Non-compatible Extensions
You will need to do your best to make compatibilities for all the TYPO3 extension with TYPO3 patches, hooks, new standards etc., You will need to provide you list of "not-feasible" TYPO3 extension with a possible "alternative solution" to your customer.

Step 4: Upload it to DEV Server
Once complete everything at the LOCAL server then upload it to DEV server eg., dev.youdomain.com.

Step 5: Customer’s Approval
Your customer will need to test drive the whole site &  provide an approval that everything is fine.

Step 6: Go-Live
Finally, You can upload everything from DEV to the LIVE server.

Checklist before start TYPO3 Upgrade

Backup & Restore

It’s always good practice to setup proper backup & restores at the server, so it will help in any critical situation.

Setup Versioning System

Versioning system like GIT will help you during the upgrade changes. Eg., You’ve settled few patches and seems does not work well then you can always rollback such code through versioning system.

Check Live Server Compatibility

Source: https://typo3.org/cms/roadmap/

As you know, the latest TYPO3 version will require the latest server software compatibility eg., TYPO3 8.x requires PHP 7.x, so just make sure to cross-verify with your customer and server guys for such all the compatibilities.

As it’s part of our routine, so Team NITSAN smartly developed one PHP script which generates an automatic report of compatibility between your server and TYPO3 version.

Step 1: Download the latest version from https://github.com/nitsan-technologies/ns_typo3_compatibility/archive/master.zip

Step 2: Put “TYPO3_Check_Configuration.php” file at your web root directory.

Step 3: Run this PHP script from your server eg., mydomain.com/TYPO3_Check_Configuration.php 

Step 4: Select target TYPO3 version, and you will get the detailed report as follows.

Disable TYPO3 Backend Access

At the LIVE website, Please make sure no one will do any changes at TYPO3 backend until you launch a new site, otherwise all their last changes may lose.

Notedown Useful TYPO3 extensions from TER

How to quickly upgrade minor/security updates?

TYPO3 provide the best feature is, We can check out minor/security updates directly from TYPO3 backend. 

  • The Install Tool in the section "Important Actions" provides a function to update the TYPO3 Core.
  • For this to work, It only works under Unix and MacOS and your TYPO3 project working with the typo3_src symlink
  • The document root needs to be writable and One path above document root (../) needs to be writable (new directories need to be allowed to be created).
  • One more important thing is The 'tar' command must be available for extracting the Source package.

Manually Upgrade TYPO3

You can install the minor/security updates manually. Just go to TYPO3 official site typo3.org/download/ and download the Source package of the new TYPO3 version then extract the package on your web server and adjust the typo3_src symlink.

Upgrade from TYPO3 4.x to 6.2 LTS
Reference: https://docs.typo3.org/typo3cms/InstallationGuide/6.2/Upgrade/ 

Upgrade from TYPO3 6.x to 7.6 LTS
Reference: https://docs.typo3.org/typo3cms/InstallationGuide/7.6/Upgrade/ 

Upgrade from TYPO3 7.x to 8.7 and 9.x LTS
Reference: https://docs.typo3.org/typo3cms/InstallationGuide/ 

TYPO3 Templating Changes
We recommend to make changes and/or upgrade following TYPO3 templating method:

  • css_styled_content to fluid_styled_content
  • TemplaVoila to Fluid
  • Any out-dated old third party TYPO3 extension to Fluid

TYPO3 Extensions Upgrade

The extension has two types, so let’s we check in brief.

TER Extension
There are mainly two ways to Upgrade the TER Extension in a good way.

Upgrade from EM
Directly upgrade the extension using the Extension Manager. Firstly, We need the scheduler called "Update extension list (extension manager)"

This scheduler compares and give the list of upgrade extension when we switch on Manage Extensions.

After you will click on the upgrade icon you will see the popup the list of versions.

Then just check the version you want to upgrade and click on Upgrade Extension button.
Boom your version has been upgraded.

Upgrade Manually
You will have to manually search your extension from the TYPO3 official website https://extensions.typo3.org/ and download after the checking Dependence.

Custom Extension:

The Custom extension is designed on the functionality of the client requirement so there is not any special way to Upgrade your custom Extension but in the custom extension, we will face the major issue with the deprecation of code so you need to study the Changelog of TYPO3 version.

You can study at TYPO3 officially site https://docs.typo3.org/typo3cms/extensions/core/Changelog-7.html there you will get most of the solution of error and issue.

Recommended TYPO3 Upgrade Techniques

We highly recommend you to check following popular third party solution which is very useful to smoothly and quickly upgrade TYPO3.

Important Code Deprecation and Changes

Here, we would like to write few code which will help to migrate (and make compatible) your particular TYPO3 extension which contains old-school codes.

piBased CodeExtbase Code
$this->cObj->IMG($imageConf)$myImage = $this->cObj->cObjGetSingle('IMAGE', $ImgConf);
\TYPO3\CMS\Extbase\Utility\ExtensionUtility::registerModule(...)\TYPO3\CMS\Extbase\Utility\ExtensionUtility::registerModule(...)
t3lib_extMgm::addStaticFile(...)\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addStaticFile(...)
Tx_Extbase_Utility_Extension::registerModule(...)\TYPO3\CMS\Extbase\Utility\ExtensionUtility::registerModule(...)
t3lib_div::\TYPO3\CMS\Core\Utility\GeneralUtility::
require_once

All lines beginning with "require_once" and including TYPO3 core files are to be removed.

t3lib_div::loadTCA('')

All occurrences of "t3lib_div::loadTCA('')" are to be removed.

t3lib_extMgm::

All occurrences of "t3lib_extMgm::" should be replaced by "\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::".

t3lib_div::

All occurrences of "t3lib_div::" by "\TYPO3\CMS\Core\Utility\GeneralUtility::" are to be replaced.

tslib_pibase

All occurrences of "tslib_pibase" with "\TYPO3\CMS\Frontend\Plugin\AbstractPlugin" are to be replaced.

tslib_cObj

All occurrences of "tslib_cObj" must be replaced by "\TYPO3\CMS\Frontend\ContentObject\ContentObjectRenderer ".

makeInstance()

All occurrences of "makeInstance()" with "\TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance()"" are to be replaced.

$GLOBALS['TCA']['any_table']

TCA definitions must now be moved to "Configuration/TCA/<any_table.php>" . The section " dynamicConfigFile " within the ctrl-section is omitted.

ExtensionManagementUtility::addStaticFile()

TypoScript definitions must be moved to "Configuration/TCA/Overrides/sys_template.php".

ExtensionManagementUtility::addPageTSConfig()

Page TSConfig definitions must be moved to "Configuration/TCA/Overrides/pages.php".

ExtensionManagementUtility::addTCAcolumns()

Must now be done within "Configuration/TCA/Overrides/<any_table>.php".

ExtensionManagementUtility::addToAllTCAtypes()

Must now be done within "Configuration/TCA/Overrides/<any_table>.php".

ExtensionManagementUtility::addPiFlexFormValue()

Must now be done within "Configuration/TCA/Overrides/tt_content.php".

ExtensionUtility::registerPlugin()

Must now be done within "Configuration/TCA/Overrides/tt_content.php".

ExtensionManagementUtility::addPlugin()

Must now be done within "Configuration/TCA/Overrides/tt_content.php".

ExtensionManagementUtility::getFileFieldTCAConfig()

The parameters of this method must be adjusted if you want to enable backend image editor (Cropping) for FAL images.

$_EXTKEY

The variable is omitted and all occurrences are to bereplaced by the extension keywith the exception of "ext_emconf.php".

ext_localconf.php

To our knowledge, only "\TYPO3\CMS\Extbase\Utility\ExtensionUtility::configurePlugin" is left;)

ext_tables.php

Nothing should be written in $TCA or $GLOBALS['TCA'] and the file should be omitted in future TYPO3 versions. Also allowed are "\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::allowTableOn StandardPages()"

Remove duplicate FAL records after TYPO3 6.2 upgrade

CREATE TABLE sys_file_new LIKE sys_file;

INSERT sys_file_new SELECT tx_phpunit_is_dummy_record, MAX(uid) AS uid, pid, tstamp, last_indexed, missing, storage, type, metadata, identifier, identifier_hash, folder_hash, extension, mime_type, name, sha1, size, creation_date, modification_date FROM sys_file GROUP BY BINARY identifier;

SELECT * FROM sys_file_new;

RENAME TABLE sys_file TO sys_file_bak;

RENAME TABLE sys_file_new TO sys_file;
CREATE TABLE sys_file_reference_new LIKE sys_file_reference;

INSERT sys_file_reference_new SELECT tx_phpunit_is_dummy_record, MAX(uid) AS uid, pid, tstamp, crdate, cruser_id, sorting, deleted, hidden, t3ver_oid, t3ver_id, t3ver_wsid, t3ver_label, t3ver_state, t3ver_stage, t3ver_count, t3ver_tstamp, t3ver_move_id, t3_origuid, sys_language_uid, l10n_parent, l10n_diffsource, uid_local, uid_foreign, tablenames, fieldname, sorting_foreign, table_local, title, description, alternative, link, downloadname FROM sys_file_reference WHERE deleted=0 GROUP BY pid,uid_local,uid_foreign,tablenames,fieldname;

SELECT * FROM sys_file_reference_new;

RENAME TABLE sys_file_reference TO sys_file_reference_bak;

RENAME TABLE sys_file_reference_new TO sys_file_reference;
UPDATE sys_file_reference

LEFT OUTER JOIN sys_file ON (sys_file.uid = sys_file_reference.uid_local) SET sys_file_reference.uid_local = sys_file_reference.uid_local + 1 WHERE sys_file.uid IS NULL;

Checklist for QA Testing

Once the TYPO3 upgrade finish, Your QA team should test the backend and frontend of the website as follows:

Testing ScenarioPriority
Check UI/UX DesignMedium
Check Functional Frontend Features (if any)High
Check TYPO3 BackendHigh
Check Cross-Browsers CompatibilityMedium
Check Cross-Devices CompatibilityMedium
Check Speed & Performance Testing (Google insight, Pingdom)Low
Check TYPO3 Backend ReportHigh
Check TYPO3 Error LogsMedium
Check Console ErrorLow
Check Deprecation LogsMedium
Check page to page comparison of before & after upgradeHigh

TYPO3 QA Report

One more thing, keep prepare QA Report to send it to your customer ;) You can download the format of TYPO3 QA Testing Report from here Sample-TYPO3-Upgrade-QA-Report.xlsx

Go-Live: Deployment to Live server

Before deployment checklist

  • Check server compatibility with TYPO3 version
  • Check server access detail

After the deployment checklist

  • Check Report/Install tool module and solve errors if any
  • Testing of speed/performance (Google Page Speed, Pingdom)
  • Check TYPO3 backend error log
  • QA Testing whole Live website

Conclusion

Thanks for reading such a long article, Let me quickly revise all the points ;)

  • Keep communicating with your customer with let them know about the importance of TYPO3 update for minor and major update.
  • Guide to your customer to decide between Relaunch website and Upgrade TYPO3.
  • Always take care in the estimation process with analysing the whole TYPO3 like prepare extension report, an estimate for each milestone, provision for non-compatible extension etc.,
  • Perform step by step TYPO3 upgrade procedure with before & after checklist.
  • Apply exclusive tips and tricks techniques during the update procedure.
  • Finally, Go-live with well QA testing of your TYPO3 website.

I would love to know your experience and tips/tricks to make smooth and successfully complete TYPO3 upgrade projects. Please feel free to write down your any suggestions or queries using below comment box, Thank you!

Have a happy & secure TYPO3 upgrade :)

Contribute to TYPO3 by becoming my Patreon

As I love TYPO3, I would like to furnish TYPO3 people with informative content, tutorials, and experiences by composing regular TYPO3 blogs “as to give back to the community”.
To hold adding to our extraordinary OpenSource TYPO3 projects and network, I'm looking my Patreon www.patreon.com/sanjay_nitsan

Write comment

Name*

URL

Comment*

    No comments

Great things in business are never done by one person.

Get in Touch