Upgrading an existing TYPO3 4.x installation to TYPO3 6.2 LTS can be a challenge due to massive refactoring of the core in 6.2 and especially the new file management layer (File Abstraction Layer – FAL). Besides upgrading the core system, several third-party-extensions need to be migrated or replaced by alternatives. There are some essential ones which will no longer work on 6.2. This little step-by-step guide is just a rudiment documentation of the pitfalls and workarounds in our migration process. It is NOT a complete migration guide, but addresses special issues like DAM to FAL migration in combination with tt_news, replacement of deprecated extensions like css_filelinks and tips for migration of custom extbase extensions built with TYPO3 4.x.
A good introduction (in german) to the general migration steps is provided by jweiland.net
https://jweiland.net/typo3-hosting/service/video-anleitungen/upgrade-auf-typo3-62.html
A very brief documentation of the upgrade process can be found on the official documentation:
http://docs.typo3.org/typo3cms/InstallationGuide/UpgradeLTS/Preparation/Index.html#lts-upgrade-preparation
Prerequisites: You must have terminal (SSH) access to your webserver / webhost and database server for the migration process.
Step 1 | Create a 1:1 copy of your installation for testing the upgrade
You should never run such a huge upgrade directly on a live system. It is highly recommended to create a test instance, which should be an exact clone of the live system. I will not go into detail, just an overview of the necessary steps:
- Clone the mysql database: the best way to this is via “mysqldump” on the command line. We had some problems with the correct econding (UTF-8) in the new database. To resolve this issues, we followed the steps for UTF-8 save cloning provided on this page:
http://makandracards.com/makandra/595-dumping-and-importing-from-to-mysql-in-an-utf-8-safe-way
When the task is finished, assure that all special characters (like german umlauts) are correctly displayed in the new database instance. - Copy the complete root of your TYPO3 project to a new location. On linux systems, the best way to achieve this is via the “tar” command. Quick Example:
> tar cvfz my-typo3-4-2-backup-file.tgz my-existing-website-root/ > tar xzf my-typo3-4-2-backup-file.tgz my-new-website-test-root/
- Map your Test-Domain to the new website root
- Change the MySQL database credentials in typo3conf/localconf.php to the new database
- Test the website
Step 2 | Migrate your Typoscript code
The TS-Objects PHP_SCRIPT and HTML are deprecated in 6.2 and will not work. Search your Typoscript for occurrences – in case of “HTML” simply replace it with “TEXT”.
Step 3 | Clean up your extension list
Uninstall all deactivated and unnecessary extensions. Upgrade all remaining extensions to the latest versions for the current version of TYPO3 and migrate them after the successful core upgrade.
Step 4 | Check & refresh reference index
In the TYPO3 Backend, go to “System” -> “DB Check” and choose “Manage Reference Index” from the drop down menu. You should check and upgrade the reference index to identify and clean up orphaned references. In large installation it could be necessary to run the task via command line because of time and memory limits.
Step 5 | Clean up your database
Use the install tool to clean up the tables for caching and temporary data to reduce the size of the database and get rid of all that stuff which will be recreated on the fly when browsing the new page.
Step 6 | Uninstall extensions “DAM” and “css_filelinks” and other extensions which will no longer work on 6.2
If your project uses extensions for which there is no upgraded version available, you should uninstall them now. DAM and all related extensions (like dam_ttcontent, dam_ttnews,…) are no longer supported in 6.2, the same goes with “css_filelinks” and others. We will address these special issues later in this blog post.
Step 7 | Check your scripts and environment with the extension “smooth_migration”
“smooth_migration” checks your installation for deprecated method calls and usage of old APIs. Especially when using custom extensions, you should check and fix the reported issues – the extensions offers built in functionality to replace invalid calls to old and deprecated functions and methods and gives you detailed reports about incompatible parts of your project.
More Details can be found here: http://docs.typo3.org/typo3cms/InstallationGuide/UpgradeLTS/Preparation/Index.html#lts-upgrade-preparation
Step 8 | Upgrade your PHP & MySQL Version
TYPO3 6.2 LTS requires at least PHP 5.3.7 and MySQL 5.1. Be sure that your server supports these versions. For our projects, we are using PHP 5.5 with Opcode Cache enabled. This gives your site a huge performance boost. Check your php.ini settings as well, as 6.2 LTS recommends at least 256 MB memory limit and a script timeout of at least 240 seconds. 6.2 needs more server resources than earlier versions, so check your server environment.
Step 9 | Upgrade core to TYPO3 6.2 LTS and run the install tool
Download the new sources and update the symlink “typo3_src” to the new source. I recommend deleting the contents of the directory “typo3temp” before accessing the installation tool. Run the migration wizard in the install tool, check for broken extensions (will be deactivated until they are upgraded or removed), and check the system environment for problems
More details:
http://docs.typo3.org/typo3cms/InstallationGuide/UpgradeLTS/UpgradeProcess/Index.html
After running the install tool, clear all caches in “Important actions”.
Step 10 | Upgrade and reactivate extensions
Go to Extension Manager and check for extension upgrades first. After upgrading, reactivate any disabled extension, clear the cache and test your site.
If you are not using DAM, you are done with the essential steps – now you should test your site and especially your site’s layout.
Layout problems and “css_styled_content”
If your design looks not as expected, check the version of the static Typoscript template “css_styled_content”, if in use. Try to replace it with the provided legacy template, for example “css_styled_content (Typo3 4.5)” and check your layout again.
Replace “css_filelinks” with pure Typoscript rendering
The extension “css_filelinks” can easily be replaced by defining the layout of your filelinks with pure TS. Checkt out this example (should be self-explaining):
# replace for obosolete css_filelinks extension
tt_content.uploads {
wrap = |
# Unser neues COA
200 = COA
200 {
10 = FILES
10 {
references {
table = tt_content
fieldName = media
}
renderObj = COA
renderObj {
# wrap = |
100 = TEXT
100 {
data = file:current:size
bytes.labels = Byte | kB | MB | GB
# wrap = |
# data will be inserted on position |
dataWrap = 
{file:current:name}
{file:current:title}, |
}
}
}
}
# clear the old rendering
20 >
}
Migrating “tt_news” to “news”
If you are using “tt_news”, there is a compatible version for TYPO3 6.2 LTS. You may upgrade it without any troubles (when not using “DAM”), but i would recommend to move to the extension “news” from Georg Ringer. This extension offers more features than “tt_news” and is completely written in extbase and fluid with an excellent documentation. It even offers a migration wizard for moving your old “tt_news” records to “news”. The disadvantage of this approach: you have to rewrite the configuration and templates for your news rendering from scratch.
Checkout the Extension: http://typo3.org/extensions/repository/view/news
DAM to FAL Migration
Check out part two of this blog post.
Feel free to add your comments and experiences here.
I will not offer any support and i will be not responsible for any problems or damage on your site caused by the provided information – use it at your own risk!