Converting a TYPO3 installation from normal mode into Composer mode

Last updated on 13. April 2022

If you got here, you probably know the difference between a normal installation and a Composer installation of TYPO3. In one phrase one could say, Composer is a package manager for software that is based on the PHP programming language. Composer ist putting software, that belongs together, at the right place and updates all dependencies.

composer update

will do the job, and you are done. Theoretically, and if you are very lucky!

Composer works with a recipe in form of a „composer.json“. The recipe informs composer how to put things together and which software depends on some other one. Sub-packages bring their own recipes and make sure, that they will get what they need.

For a brand new TYPO3 installation this command will install TYPO3 in its basic version, but not with all system extensions, as in the old way:

composer create-project "typo3/cms-base-distribution:^xx.y" my-new-project

(change „xx.y“ to the TYPO3 version you want to install)

What is coming with and what is left behind is shown here:
https://get.typo3.org/misc/composer/helper

The above command will install TYPO3 in the folder „my-new-project“, as a sub-folder of the current folder. So make sure, that you are in the correct folder to start the installation with. Just do the „cd“ command in the terminal/bash connected via SSH to the server. After a few seconds of waiting, you should have a fully working TYPO3 composer installation.

The folder structure (usually inside the „html“ folder) should be:

my-new-project
- config
- composer.json
- composer.lock
- vendor
- var
- public

„composer.json“ holds the recipe for this installation and will be the working ground for the steps ahead. The „public“ folder is the target for the internet-domain-connection. Inside „public“ the server will find the TYPO3 „index.php“ starting point into the system.

But now back to the guide, step by step:

Step 1

Inside the old TYPO3 installation:

Go to „Settings“ and „Configuration Presets“ and switch on the „Debug Mode“.
In your main TypoScript template, write on top to get more debug information („0“ creates more information, „1“ shows the page with an error number at the spot of the error):

config {
ObjectExceptionHandler = 0
}

More information: https://docs.typo3.org/m/typo3/reference-typoscript/master/en-us/Setup/Config/Index.html#setup-config-contentobjectexceptionhandler

Go to „Maintenance“ and flush the Cache
Do „Analyse database“ and do all available changes (if it is green, nothing to do)
Go to „DB Check“ (at the bottom lef of the TYPO3 tools line) and update the reference index
Go to „Upgrade“ and „Upgrade „Wizard“ and check whether some essential updates have to be done (otherwise it is just green)
Go to „Extensions“ and click on the topline word „type“, now you should see all „local“ extensions on top of the list.
Make a screen shot, or old fashioned write down the names and the versions of all local (from you) installed extensions
Go to „https://extensions.typo3.org/“ and write down the versions of each extensions, you can use with which TYPO3 version (if you are two versions behind the target, write down the versions possible for each step)
Now deactivate all local extensions.
After this step it is important to know: Don’t touch the „Analyse database“ system! If you do, TYPO3 will delete all data base columns of the deactivated extensions!
Your normal TYPO3 system should now be nice and clean, so you can update it to the next level. Go just ONE STEP to the next LTS! You can do it through the customer centre of your provider (e.g. Mittwald) or through getting the folders of the next LTS version and updating the sym-links.
After the next level is installed, go back to the backend of TYPO3.
First thing is to update, in the „Extensions“ area, the list of available extensions (button on the top drop-down menu).
Click the word „Type“ on top of the extensions list to see the local extensions on top of the list.
Some of them should now have the „+“ sign to update them. Do the updates for each local extension. Check your list, that you made before, for extensions that will not work on this version of TYPO3, leave these extensions deactivated. You should find replacements for them.
Activate all local extensions, that work with this TYPO3 version.
In „Maintenance“, flush the cache and analyse the data base structure. Now you should execute all necessary changes to the data base. This will also delete all information of deactivated and outdated extensions in the data base!
Check in the TYPO3 „Upgrade“ tool, if some upgrade routines have to be executed.
Go to „DB Check“ (at the bottom left of the TYPO3 tools line) and update the reference index.
Now this TYPO3 LTS version should work. Check the front end, if all is fine.
Sometimes extensions like „news“ (the Austrians are very innovative people, in late 2020 check in the template for detail.html for the <n:xocial.disqus> viewhelper and delete it) or „powermail“ have breaking changes in their templates. You will see error codes at the frontend, or a whole error page, that gives a hint, where to search. Most extensions also provide information about breaking changes in the old TYPO3 way of updating extensions, with the extensions manager. This is lost with composer mode! You have to do your research outside the TYPO3 installation: https://extensions.typo3.org/extension
If you go from TYPO3 9.7 to 10.4 check your conditions in the TypoScript, the expressions that are allowed for conditions (e.g. conditions for special pages) have changed!
If everything works -> go to step 8 and upgrade to the next TYPO3 LTS.
…
You have reached your target version. You should have a working normal TYPO3 installation, that is on the latest version of TYPO3. All local extensions should be on the latest versions too.

Step 2

Collecting information about your normal TYPO3 installation:

Write down the new version numbers of all local extensions.
Check inside the „typo3“ folder and then „sysext“ folder all system extensions. Make a screen shot, or write down all names.

Step 3

Building the new home:

Make a new TYPO3 composer installation in a new folder. (See instructions on top).
Target a subdomain (e.g. test.my-domain.org) into the public folder of your new composer installation.
Now, change the „composer.json“ so it is having all local extensions and system extensions listed. (You can do it by hand or use „composer require“ for it. For help seek inside TYPO3 manual pages or on the composer webpage.)
Run „composer update“, to update and install all extensions that you had in the old TYPO3 installation.
Check inside the „public/typo3/sysext“ folder whether it has the exact same sys-extensions as your normal TYPO3 updated installation.
Check inside „typo3conf/ext“ whether you have exact the same local extensions listed here.
If things are matching, create your „FIRST_INSTALL“ file inside the „public“ folder and install TYPO3 and the data base connection.
You should have now a nice empty TYPO3 composer installation that matches your normal installation structure and all local extensions (not the content yet).
If you go into the „Extensions“ menu all your local extensions should be installed. In composer mode installation of extensions is in the hands of composer and no more in the hand of TYPO3. (You will find a hint on the top of the „Extensions“ menu.) But you can still activate and deactivate Extensions here. Now all of your local Extensions should be activated, as it has been in the old version.

Step 4

Moving into the new home:

Copy „fileadmin“ and „uploads“ into the new composer installation („public“ folder).
Copy all files like favicons, robots.txt, sitemap.xml and other stuff to the new home.
Use phpMyAdmin to delete all tables in the new composer installation.
Use phpMyAdmin to export all tables of the old installation with a data base dump file
Import the data base file from your old installation into the data base of your new composer installation.
You have moved!

Step 5

Not done yet:

You may still get a error page at the front end or other funny things.
Clear the cache with the „Maintenance“ tool.
Do „Analyse database“ and do all available changes (if it is green, nothing to do). Composer mode seems to produce some special tables that are missing now, since you replaced the composer data base with your old data base.
Don’t forget to clear the cache of your browser. Most browsers are a nightmare and even Firefox starts to do some hard core caching lately. Don’t use Google Chrome, they are evil thieves of personal data!
At this point you are done!

What is ahead of you with composer mode TYPO3?

You should study the specs for the „composer.json“ and how to leave updates in the range of a main version for your local extensions (e.g. „t3/dce“: „^2“ here it’s the „^“ symbol, that says, don’t go to version 3, stay in version 2, but do all 2 updates 2.1 until 2.99. Each extension will come with its own „composer.json“ and should name the dependencies inside it. So you should not run into situations where PHP versions or TYPO3 versions will not match with the local extension version that you want to install via „composer update“. But the nice list that used to pop-up in the normal old TYPO3 installation that gave you hints for breaking changes inside extensions has been sacrificed for the central dependencies management of composer and of course to stay on the height of the development with the php world and the modern concepts out there. If you want to install a new local extension, you must check the name and the „vendor name“ (part before the slash) at https://packagist.org/.

To update a single extension run, for example for the dce extension from Armin Vieweg:

composer update t3/dce

For the whole lot, TYPO3 and all extensions:

composer update

If you get error codes from composer, update composer with composer:

composer self-update

If you are lost:

composer list

Or more information is here: https://getcomposer.org/doc/

What is next?

IT never ends and there is allways something that changes. Did we not use telephones for a 100 years just in the same way? I cannot remember, that a normal telephone, that we rented from the German „Post“ in the 80s, ever didn’t work. And nowadays, do these computers ever work for a decent space of time? No! You get them brand new, already broken and you are never done with a web page, never good enough, never fast enough, never in the latest fashion of coding.

Next step: TYPO3 sitepackage with composer mode and git versioning. But that is on another day.

Author: Thomas Hezel, zazu.berlin 2020