Create a copy of the project
To perform an upgrade on your website, you should always create a copy of the project beforehand and perform the upgrade on the copy. In the meantime, the original website can remain accessible under the official domain. However, before the copy is created, you must check how much storage space the relevant account has so that the storage space is not completely taken up when the copy is created. If necessary, the storage space can be temporarily extended.
These instructions assume that you have SSH access to the website and are familiar with the basics of working on the command line.
The following steps are required to copy the project:
- Create a copy of the database
- Create a copy of the project directory and connect it to the copied database
- Create a development domain and point it to the copied directory
Create a copy of the database
On the cloud server:
- In the Plesk customer menu, select the menu item "Databases", then search for the database used in the list and click on the "Copy" button there.
- Give the database a name.
- For cloud hosting, a database user must then be created.
- Make a note of the database name, user name, password and host.
Please note: the database user name in Plesk must not be longer than 16 characters in total. Plesk already specifies 6 characters.
On the Classic Server:
Here you cannot copy databases directly, you must create a new, empty database and then import a dump of the live database.
In the customer menu, switch to the "MySQL databases" menu item and then click on the "New database" button at the bottom left. Create a new database and make a note of the database name, user name, password and host.
Now you need to create a dump of the live database (which your project is currently using) and import it into the newly created database. The easiest way to do this is via the command line. Log in to the server via SSH, change to the typo3cms/system/backup/databases directory and display the contents. Unzip the latest dump of the required database with the command
gzip -d <filename>If no current dump is available, create one with the command
mysqldump --opt --no-tablespaces -h <host> -u <username> -p <database-name> > my-database-dump.sqland then import it with
mysql -h <host> -u <username> -p <database-name> < my-database-dump.sqland then enter the password in the newly created database.
From TYPO3 11 the database should be changed to MariaDB, at least MariaDB 10.4.
How do I find out which database I am using?
In the TYPO3 backend, select the Admin Tools > Environment module and click on "Show System Information" in the "Environment Overview" box. You will then see information about the database connection and the PHP version used.
Create a copy of the project directory
Log in to the server via SSH and change to the typo3cms/ directory where your project directory is located. Then execute the command
cp -r <directory name> <project directory copy>to copy the project directory. Now go to the directory typo3cms/<project-directory-copy>/typo3conf in your copy and open the file LocalConfiguration.php, or from TYPO3 version 12 system/settings.php to edit it. Customize the database information by entering the access data of your database copy.
Create a development domain
On the cloud server:
Click on the "Add subdomain" button in the customer menu of Plesk and create a subdomain from your live domain, for example from the domain "my-website.com" the subdomain "v12.my-website.com" (if the target version should be TYPO3 v12). In the "Document root" field, enter the file path to your copied project directory, starting with the"httpdocs/" directory, for example"httpdocs/typo3cms/project-directory-copy". Once the domain has been created, switch to the "Hosting and DNS" tab and click on the "Hosting" menu item. There you can (if necessary) set the correct PHP version for the TYPO3 version that your copy currently has and also adjust it later after the upgrade steps. You can also change the directory path here at a later date. Once you have closed the "Hosting" dialog again, you can issue an SSL certificate for the newly created subdomain under the "Dashboard" tab.
On the Classic Server:
Here you should find out in advance which PHP version is required by the TYPO3 version you want to upgrade to. On the Classic Server, subdomains inherit the PHP version of the parent domain, you cannot assign them your own. So if you do not have a domain in your package that you can set to the PHP version that your TYPO3 target version requires, you will have to order a new domain for the upgrade period. However, if you have a suitable domain, you can proceed as follows:
Click on the menu item "Domain management" and then on the gear icon to the right of the domain you want to use for the upgrade. In the menu that opens, select "Add subdomain" (if the domain is not currently required, you can also use it directly as a development domain and do not need to create a subdomain). Then create a subdomain in the format "v12.my-website.com" and enter the file path to your copied project directory as the path, starting with the directory"/typo3cms/", for example"/typo3cms/project-directory-copy".
You can also adjust the PHP version for a higher-level domain by clicking on the cogwheel symbol on the right, clicking on the "Open" menu item and then on the "Settings" tab.
You should now be able to call up the newly created domain in the browser and log in with "/typo3" appended to the domain.
Make sure that you are really on the copy and not on the live installation before you make any changes. For example, make a small text change on a page and make sure that this change ONLY appears under the domain of the copy and not on the live site.
Then check the URL entered in the backend, depending on the TYPO3 version, under the "Site Management">"Sites" module or in TypoScript under "config.baseURL" and adapt it to your development domain. Also check the root page(s) for possible domain data records that need to be changed or deactivated.
Switch on debugging
Strange errors can occur at any time and, if things go badly, make the backend inaccessible right from the start. In order to get at least some information on troubleshooting, it is better to switch on debugging first:
Go to the "Admin Tools">"Settings" module and select "Configuration Presets". Under "Debug Settings" you can change the configuration from "Live" to "Debug".
Customize the robots.txt
To prevent the copy of the website from being scanned by robots during the upgrade and appearing in search engine results, a corresponding instruction should be stored. You can do this either via TypoScript
page.meta.robots = noindex, nofollow
page.meta.robots.replace = 1or, if a "robots.txt" file already exists, enter the following there:
User-agent: *
Disallow: /Prepare extension list
Go to the "Extensions" backend module and select "Get Extensions" from the menu at the top left. Then click on the "Update now" button on the right. An updated list of all extensions available in the TYPO3 Extension Repository (TER) will now be loaded. (If the scheduler task "Update extension list (extensionmanager)" is active on your website, this update process will be carried out automatically at the defined interval).
If you now switch back to "Installed Extensions" in the top left-hand menu, you will see an update icon to the left of each installed extension, provided a more up-to-date version exists. Update each extension to the highest possible version that is offered.
If an error message suddenly appears after updating an extension and access to the extension list is no longer possible, you can also deactivate the offending extension via the command line. To do this, go to the typo3conf directory, open the "PackageStates.php" file for editing and remove the section that belongs to the extension in question. Then delete the cache by deleting the typo3temp/var directory. The backend or the extension list should now be accessible again. The deactivated extension can also remain in this state for the time being; you may be able to reactivate it without problems after a version step.
If there are extensions in the list that are not compatible with the next major version of TYPO3, deactivate them. Also deactivate all individual extensions and site packages that are not available in the TER, as they will most likely have to be revised after the next major version step.
Check upgrade wizard
After extensions have been updated, there may be new upgrade wizards that now need to be run. Therefore, go to the backend module "Admin Tools" > "Upgrade" and click on "Run Upgrade Wizard". Wizards that are still open are now listed with a short description. Execute all wizards. If you are asked whether you really want to run this wizard and you are unsure, select "no, do not execute" beforehand and then click on "Perform updates!". The wizard will then not be executed, but marked as "completed".
Clean up tables and update database index
After the upgrade wizards have been executed: In the "Admin Tools">"Maintenance" backend module under "Analyze Database Structure", all tables and database fields should be up to date and those that are no longer required should be deleted.
The index should be updated in the "System">"DB Check" backend module under "Manage Reference Index".
Carry out the upgrade
Once you have completed all of the above steps, the actual upgrade can begin.
Always carry out the upgrade from major version to major version, for example from version 9.x.xx to 10.x.xx to 11.x.xx to 12.x.xx and so on, as otherwise problems with the database will occur very soon.
As a result of this procedure, you will have to carry out the "Upgrade to an intermediate version or the target version" section more frequently (if there is more than one version step). However, as the procedure is always the same, we have only listed it once.
- Upgrade to an intermediate version or the target version
- Customize the site package
Upgrade to an intermediate version or the target version
To upgrade, you must log in to the server again via the command line. Look in the typo3cms directory to see if there is already a directory or a .tar.gz file with the TYPO3 version you need. The name should be: typo3_src-x.x.xx, or typo3_src-x.x.xx.tar.gz.
If the version is not yet available, you can download it into the directory with
wget --content-disposition https://get.typo3.org/x.x.xYou must then unpack the downloaded file with
tar -zxvf typo3_src-x.x.xx.tar.gzNow change to your project directory and adapt the existing typo3_src symlink there, or delete it and create a new one with the same name and the new typo3_src-x.x.xx directory as the target:
rm typo3_src
ln -s ../typo3_src-x.x.xx typo3_srcThen delete the cache by deleting the typo3temp/var directory.
Then log directly into the install tool with the URL v12.meine-website.de/typo3/install.php and go through the following points in this order:
- Execute the upgrade wizards.
- Delete TYPO3 and PHP cache (under backend module "Maintanance" > "Flush TYPO3 and PHP Cache").
- Execute Analyze Database Structure. Make sure that you add and change all new tables and fields, but do not delete any tables or fields! Remember that you have temporarily deactivated extensions that may need these tables again later when they are activated.
- Now log into the backend and check whether there are any error messages, e.g. when the extension list is called up.
- Update the extensions (including the deactivated ones) to the highest possible version for this TYPO3 version. Always keep in mind up to which TYPO3 version the respective extension is still compatible. If there is no longer a functioning version of this extension for the TYPO3 version to which you want to upgrade in the next step, then deactivate it.
- Check whether new upgrade wizards have been added after updating extensions.
- Don't be put off if plugins or content elements cannot be found due to deactivated extensions or site packages or if an error message appears in the frontend. You can take care of this once the target version has been reached.
Repeat the step "Upgrade to an intermediate version or the target version" until you have reached the target version. At each step, make sure that the TYPO3 version you have just reached still works with the PHP version of your domain and adjust it if necessary.
Customize the site package
This is where it becomes very individual, as it depends on what the start and target version of TYPO3 is and where your site package is currently located or whether there is one at all. So here are just some basic information and tips on how to proceed:
- If the site package or design template is located in a directory below fileadmin, you should move it to the typo3conf/ext directory from TYPO3 version 11 at the latest. You can find out how to create a site package for TYPO3 in this directory and then install it like an extension in the extension list at https://docs.typo3.org/m/typo3/tutorial-sitepackage/main/en-us/
- To adapt an existing site package to the new TYPO3 version, also follow the tutorial mentioned above and check the files
- composer.json
- ext_emconf.php
- ext_localconf.php
- ext_tables.php
- Configuration/TCA/Overrides/sys_template.php
- Configuration/TCA/Overrides/pages.php
- Configuration/TCA/Overrides/tt_content.php
- and other PHP files
- Check whether the TypoScript conditions used still work. As of TYPO3 9.4, the condition syntax is based on the Symfony Expression Language, which is why the old syntax has to be rewritten in the new syntax in many places. Problems with conditions can be recognized by a corresponding entry in the log file ( typo3temp/var/log directory).
- ViewHelpers used in the Site Package also often have to be adapted or replaced after an upgrade because they no longer exist in the new version. You can recognize this by a corresponding error message in the frontend.
If you have completely adapted the site package (or other individual extensions) to the new TYPO3 version, you can reactivate it, check whether everything works and make further adjustments if necessary.
Extensions from the TER that were deactivated during the upgrade process can now also be reactivated.
Both the backend and the frontend should now run smoothly again.
Typical errors after an upgrade
If error messages appear in the backend or frontend, take a close look at them. Even if they seem cryptic at first glance, you may still be able to find clues to the cause of the problem. For example, are paths given to a file in the site package or to an extension used? If so, you may be able to rectify the error in this file or deactivate the extension in question. Does the message look like an SQL statement? Then you may need to run Analyze Database Structure again.
Error messages are also written in great detail in files in the typo3temp/var/log directory or listed under the "Log" backend module.
After each version step, there may be typical error messages or problems related to the changes specifically in this TYPO3 version or the extensions used. Here you can see a list of the most common problems and how to solve them.
Images appear too dark after the upgrade
In the LocalConfiguration.php or settings.php file or in the InstallTool under "GFX", adjust the value for 'processor_colorspace' as follows:
'processor_colorspace' => 'sRGB'Then in the InstallTool under "Maintanance > Remove Temporary Assets" empty the directories from which the dark images come.
TYPO3 v11
- Change PHP version to >= 7.4
- Adapt the .htaccess file, e.g. use the example file from TYPO3 11 Core: typo3/sysext/install/Resources/Private/FolderStructureTemplateFiles/root-htaccess
- Rename the extension of the Typoscript and TSConfig files from .txt to .typoscript and .tsconfig respectively
- replace the variable $_EXTKEY in PHP files with the directory name of the site package (except in the file "ext_emconf.php")
TYPO3 v9
Migration from css_styled_content to fluid_styled_content
The change from css_styled_content to fluid_styled_content is supported by TYPO3 as well as possible. The following steps must be carried out:
- Deactivation of the extension css_styled_content
- Activation of fluid_styled_content
- Add the static templates "Content Elements (fluid_styled_content)" and "Content Elements CSS (optional)(fluid_styled_content)"
- Check in the install tool whether an upgrade wizard is to be executed.
Please note: fluid_styled_content uses other CSS classes. The CSS of the frontend may need to be adapted here.
In addition, some options from css_styled_content are no longer supported. For example, the "image effects" are no longer available. The names of some database fields have also changed. Where did the database field "section_frame" -> "frame_class". This must be taken into account if, for example, adjustments have been made via TSConfig.
SEO and readable URLs
With TYPO3 9 LTS, some features have been integrated into the TYPO3 core that previously had to be retrofitted via additional extensions.
SEO features via the new "seo" system extension
Since TYPO3 9, meta tags such as "description", "keywords", "author" etc. are automatically generated in the HTML source code if the new system extension "seo" is activated. Previously, this had to be done manually using TypoScript or additional extensions such as cs_seo. The creation of an optimized browser title and the control of search engine spiders (meta tag "robots") is now also possible directly.
Readable URLs
By default, TYPO3 generates URLs such as domain.de/index.php?id=1234. These are neither readable by humans nor do they contain keywords that are important for search engine optimization.
Up to and including TYPO3 8, readable URLs had to be created using additional extensions such as realurl or cooluri. These are no longer required since TYPO3 9. TYPO3 can automatically generate readable URLs for pages, e.g. in the form domain.com/products/product-x/
However, manual reworking is required for extensions such as "news". Here the site configuration file must be edited. However, some extensions already provide configuration examples in their documentation.
In TYPO3 version 9, the previously used RTE editor HTMLArea has been removed and replaced by the modern CKEditor. The CKEditor offers a better user interface, can be configured more flexibly and is based on current web standards. The changeover is uncomplicated in many cases, especially with standard configurations. However, if individual adjustments have been made to HTMLArea - e.g. custom format classes, buttons or RTE presets - the migration may require additional effort.
TYPO3 v7
TYPO3 7.6 introduced new content elements with fluid_styled_content, which are based on fluid templates. While css_styled_content is still optionally available in TYPO3 8, it will be permanently removed in TYPO3 10. The changeover means that content is no longer output via static HTML structures with Typoscript templates, but via modern fluid templates, which are more flexible, expandable and easier to maintain. Early migration is worthwhile, as it not only facilitates future upgrades, but also enables the use of new functions such as structured data, responsive layouts or barrier-free markup. The migration must be completed in TYPO3 9 LTS at the latest, as css_styled_content is no longer available in TYPO3 10 LTS.
If you use subparts and/or markers in your templates, these must be converted to Fluid templates. The same applies if you use an outdated extension such as templavoila, rlmp_tmplselector or automaketemplate for templating.
Clean up!
- Update language files (Installtool -> Maintenance -> Language Packs)
- From PHP 7.4: Change Password Hashings to Argon2id in the Installtool under Presets
- Delete all tables and fields no longer required under Analyze Database Structure
- Remove extensions no longer required from the extension list
- Set presets from Debug back to Live
Place online
Once the upgrade has been successfully completed and everything is working as desired, you can go to your live domain in the domain administration, point the file path to your copied project directory (where the website upgrade is located) and don't forget to adjust the PHP version of the live domain for the new TYPO3 version. Then log into the backend of the upgraded website and enter the live domain in the "Entry point" field under the "Site Management">"Sites" module. Then switch to the "Static routes" tab and adjust the robots.txt so that the website can be found by search engines.