piwik Matomo

Manual TYPO3 update – tutorial

If you're upgrading to a new major release or want to update an older TYPO3 system, a manual TYPO3 update is often a good idea. Here, I'll explain how to do it.

There are various reasons for performing a manual TYPO3 update. For example, if Composer is not available on your hosting server and/or you cannot access your web space via SSH, your only option is to update using the installation tool. If—as is the case with the Privat-Plus plan from allinkl—you cannot even extract a *.tar.gz archive, your only option is to update your TYPO3 system manually.

First of all

Safety

In any case, it is recommended that you back up the files, including the database, before the update and save them to a secure storage medium.

I never perform an update—for example, from version 11/12 or 13 to 14—on the live system; I always do it on a 1:1 copy of the site, often under a subdomain (e.g., dev… or update… instead of www…). That way, the live site can continue to run, and the update doesn’t interfere.

Clean Up

The older the system is, the more likely it is that you’ll find outdated or unnecessary content or extensions. An update is therefore the best opportunity to clean up the system thoroughly. All TYPO3 extensions that are not installed or are not in use should be uninstalled via the Extension Manager and, ideally, deleted right away.

Update Extension

Update all remaining local extensions (located at /typo3conf/ext/<ext_key>/) to the latest version compatible with your TYPO3 version. Then take a look at the “ext_emconf.php” file. Under “constraints/depends/typo3,” you’ll find the TYPO3 versions with which this extension is compatible. For some extensions, you’ll see something like “12.4.0-13.99.99”; in that case, you should be able to update your system from version 12 to 13, for example, without any problems. If it says “only” “12.4.0-12.4.99,” you’ll likely encounter errors after the update.

Update the database

In the backend, under “Administration Tools,” open the “Update” section. The “Upgrade Wizard” checks all database tables for a complete structure and adds any missing fields or tables. In addition, updates from well-programmed extensions may also be performed there.

After that, under “Maintenance,” you should also

  • Update the language files (Manage Language Packs)
  • Clear the temporary database contents (Clear Persistent Database Tables).
    This does not clear the page cache.
    If you also clear the “Backend user sessions” table, you’ll be logged out of the TYPO3 backend. You can log back in, but that’s usually unnecessary.
  • Delete the temporary files (Remove Temporary Assets).
    If you also delete the resized images under `fileadmin/_processed_/` here, the frontend may become very slow at first, because TYPO3 will have to regenerate all resized images.
  • Update the Database Structure (Analyze Database Structure)
    This process checks all tables in the database for consistency and corrects them if necessary. Unlike the update process, tables or table fields that are no longer needed are rigorously deleted and/or reformatted. Therefore, you should always update the database first so that changes can still be made to the extension databases. Sometimes this also involves moving data from old tables to new ones. In this case, the old tables are then removed.
  • Update Reference Index
    The sys_refindex table contains references to all links within individual records. For example, if an image is linked, that link is stored in the sys_refindex table. Under “System → DB Check/Manage Reference Index,” click “Update Reference Index” (Starting with version 14, this can be found under “Maintenance”). 
    For larger systems, this process may take a while. If it aborts with an “Internal Server Error” (500), it may be because your PHP execution time (max_execution_time) is set too short. For reasonably up-to-date TYPO3 versions, this should be set to 240 (sec.). Depending on your server, you can adjust this with
    php_value max_execution_time 240
    in the .htaccess file in the root directory of your TYPO3 installation.

Swap the sources

  1. Download the source files for the target TYPO3 system, unzip the archive, and upload it to the server using an FTP program (e.g., FileZilla).
    I always upload the entire typo3_src-<TYPO3 version> folder right next to the TYPO3 instance that needs to be updated (fileadmin, typo3conf, and typo3temp should also be located there). Then I create an empty directory with the old version number right next to it, and move the “typo3” and “vendor” directories (since version 7.6) as well as all files—except possibly a “favicon.ico” and any “google-verification-files.html” and similar files—into this directory.
  2. Move all files and directories from the new version's source directory into the current directory. It should then look exactly the same as before.
  3. Then place an up-to-date .htaccess file in the root directory. Since version 9.5, this file is no longer located in the source root directory, but under typo3/sysext/install/Resources/Private/FolderStructureTemplateFiles/, where it is named “root-htaccess”. This file should ultimately be located in the root directory of your website under “.htaccess.” Up through TYPO3 13, this file still contains the following section relatively early on:
    #<FilesMatch "\.js\.gzip$">
    #    AddType "text/javascript" .gzip
    #</FilesMatch>
    #<FilesMatch "\.css\.gzip$">
    #    AddType "text/css" .gzip
    #</FilesMatch>
    #AddEncoding gzip .gzip
    Here, you should remove all hash symbols (#) at the beginning of each line. It is likely that compression is enabled in your TYPO3 system, which, for example, stores CSS and JavaScript files in the `typo3temp` directory in compressed form. This section ensures that this compression is properly recognized and correctly decompressed.
  4. Now do something similar with the extensions for which source code is available only for the old or the new TYPO3 version. Here, I usually just delete the old source files in the extension directory (under /typo3conf/ext/<extension_key>—for example, everything under /typo3conf/ext/news/), download the new source files from the repository, unzip them locally, and move the new source files into the same directory.

The Installtool

  1. Delete everything in the typo3temp directory. Starting with version 6.2, the installation tool includes a check and correction feature under “Folder structure”: clicking “Try to fix…” will create all the necessary directories and files.
  2. In that case, it's best to launch the Install Tool (https://Ihre-Domaine.de/typo3/install/ or Ihre-Domaine.de/typo3/install.php). You will now be prompted to create the file ENABLE_INSTALL_TOOL in the /typo3conf directory. Make sure the file has no spaces at the beginning or end and no file extension (such as “.txt” or similar). The file’s contents are irrelevant; it can simply be empty.
    When you launch the Installtool again, TYPO3 should prompt you for the Installtool password. Log in to the Install Tool and first go to “Maintenance” to update the autoload folder (Rebuild PHP Autoload Information) and clear the cache (Flush TYPO3 and PHP Cache). By now, you should see the new TYPO3 version in the top-left corner.
  3. Now go to Upgrade → Upgrade Wizard. You will be guided step by step through the upgrade process. At the end, you should see a message such as “Progress of upgrade wizards: … 100%” or “28 of 28 upgrade wizards executed.”
  4. Now you can go back to “Maintenance” to update the database tables. When reviewing the SQL statements provided, pay attention to the extensions you have installed. These should remain unchanged. If any tables listed here are to be renamed to “zzz_deleted_[table name]” and you can clearly identify them as belonging to an installed extension, then that extension is currently not installed. Therefore, reinstall the TYPO3 extension in the Extension Manager if you know you are using it. Only when you see a message such as “Database schema is up to date. Good job!” should you access the backend (e.g., by clicking the “Switch to Backend” button on the left).

Test the Updated TYPO3 System

  1. Check the Extension Manager to see if there are any extensions that need to be updated.
  2. Test your site (both the backend and frontend). It’s not enough to simply load the pages. You should also test key site functions, such as editing a content element or record—including saving the changes and verifying them in the frontend.
  3. To speed up the cache rebuild, you can download the entire site once using the Linux command “wget -r -Dwww.ihre-domaine.tld www.ihre-domaine.tld”.
  4. If everything is working correctly, you can delete the old TYPO3 version—which you saved under “typo3_src-alt” or something similar—and the now-empty directory for the new version, “typo3_src-<version number>.”

A few things I noticed while updating to TYPO3 13.4:

  • TYPO3 may be complaining about the backend cache settings (Invalid cache backend option “compression” for backend of type “TYPO3\CMS\Core\Cache\Backend\SimpleFileBackend”). For me, deleting everything under SYS => caching in the file typo3conf/system/settings.php solved the problem.
  • For a client, I had set up additional file storage outside the TYPO3 directory. After the update, the directories could not be displayed in the file list (error message: “Error loading navigation”). I found a note on this TYPO3 page stating that you must enter the path under [BE][lockRootPath] in the configuration.

Do you have any questions?

Then please feel free to contact me

Contact form  +49 40 4327 3227  WhatsApp  email