How to migrate a TYPO3 project to Composer mode

This tutorial is just a documentation of the steps I use to migrate a TYPO3 project to composer mode so that I can just follow it whenever I want to do this task again.

The official TYPO3 docs is the basis of this tutorial. I just noted some additional stuffs that worked well for me so that I do not forget them.

This tutorial was tested for TYPO3 8.7 and TYPO3 9.

Prerequisites

Composer: Go here to get composer or just get ddev which comes with a complete PHP development evironment and composer and is very easy to use and configure.
A TYPO3 project in Classic or Non Composer Mode.

Your project structure should look something like below.

Procedure

I will be using the directory structure in the screenshot above just for illustration. Yours can have a different name.

Delete Files

You have to delete some files since they will be created by composer.

First, create a copy of your project as backup and also for use as a reference later.
Delete demov8/html/index.php, demov8/html/typo3_src, demov8/html/typo3 and demov8/typo3_src.
Delete extensions in the demov8/html/typo3conf/ext folder which you downloaded from the TER (TYPO3 Extension Repository).
Note: Delete your own or custom extensions if and only if they each have an own Git repository you can install them from.

Setup Composer

In the Project Root, create a composer.json file. So in our example, it will be directly in the demov8 directory. That is demov8/composer.json.

The contents of the file should look like below.

{
    "repositories": [
        {
            "type": "composer",
            "url": "https://composer.typo3.org/"
        }
    ],
    "extra": {
        "typo3/cms": {
            "cms-package-dir": "{$vendor-dir}/typo3/cms",
            "web-dir": "html"
        }
    }
}

The web-dir option is the web/document root folder. In our case, it is html. What ever name yours is called, put the name of the folder here.

Install the TYPO3 Core

TYPO3 v8

composer require typo3/cms:~8.7.0

If using ddev, then ddev composer require typo3/cms:~8.7.0.

In TYPO3 v9, you cannot install the core with all the system extensions like in TYPO3 8. You have to explicitly state the extensions you want to install in the composer require command.

For me, rather having to name the extensions I need I just use the command below to install a minimal set of required TYPO3 extensions.

composer require typo3/minimal:^9.5

~8.7.0 tells composer to add the newest package of version 8.7.*(for example 8.7.1, 8.7.30 etc) with at least 8.7.0, but not version 8.8.
^9.5 tells composer to add the newest package of version 9.*(for example 9.6.0, 9.5.0 etc) with at least 9.5.0, but not version 10.
You can use any depending on what you want.

Install TER Extensions

Next is to install all the extensions you deleted which were downloaded from the TER.

Go to the typo3conf/ext folder of the document root of the project backup you created earlier to see all the extensions you need to install.
For each extension in that folder, get the extension key from the folder name and search on the TER(TYPO3 Extension Repository).
From the search result, choose the right extension. The right one is the one having same extension key as the extension key you searched for.

After selecting the extension, on the next page you may find the composer command to install the extension.

No Composer command on Extension’s Page?

If no composer command on the extension’s page like shown above, then you have to look for the package name. You can use packagist to look for your extension.

Sometimes, I didn’t find my extensions on this when searching using the extension’s key. Sometimes too, the search results are too many and I will have to filter using tags to find what I am looking for.

For me, what worked well was to search for an extension from the TER using the extension’s key and then manually getting the package name.

This way also helps me to easily see which versions of the extension is compatible with the TYPO3 version of my installation. To do get the package name,

Click the “Code Insights” button on the Extension’s detail page

Open composer.json file.
Copy package name

Check compatible extension version

After having gotten the unique package name, next is to check the extension’s version compatible with your TYPO3 version.

Scroll down to Version history section of the page to view the versions of the extension and which TYPO3 version they are compatible with.

Now, run the full composer req command specifying the version of the extension compatible with the TYPO3 version you are running.
For example: composer req mehrwert/phpmyadmin:^5.6

Package not found error ?

In some cases you can get composer error like below. In this case then install the package from the composer repository for TER extensions(composer.typo3.org).

Use the following naming conventions for the unique package name.

Vendor name: typo3-ter.
Package name: Extension key with _ replaced with -.

For example for an extension with extension key cf_beskin, the full unique package name will be typo3-ter/cf-beskin.

Hence composer req typo3-ter/cf-beskin:^1.2. Depending on the version you want.

Repeat all above steps for each third party extension to be installed.

Using a single “composer req” command

Writing the composer req command for each extension to be installed is kind of difficult and also repetition. A better approach will be to use a single composer req command to install all your extensions.

What I usually do is by following the extension installation steps above, I build my composer req command in a text file and then run the final command in the terminal.

Using a text file makes it easier to edit my composer command in case of a composer error as compared to trying to edit the command in the terminal.

For example, my final sample composer req command which I run in the terminal can look like below.

composer req fluidtypo3/fluidpages:~4.1 teaminmedias-pluswerk/ke_search:~2.8 fluidtypo3/vhs:^5.2 fluidtypo3/flux:^8.2 fluidtypo3/fluidcontent

Adding own extensions

Now you have to add your own extensions so they can be autoloaded. These are the extensions you did not delete. To do this, you just have to register the PHP class name of your extensions in the project’s composer.json file.

For extensions using namespaces, add an autoload section to the project’s composer.json file which looks like below.

"autoload": {
    "psr-4": {
      "VendorName\\CustomExtension\\": "html/typo3conf/ext/extension_folder_name/Classes/",
"VendorNameTwo\\CustomExtensionTwo\\": "html/typo3conf/ext/extension_two_folder_name/Classes/"
    }
  }

NB: Remember to follow your project’s directory structure. In my case, my project root folder is html. Yours may be different.

The part “VendorName\\CustomExtension\\ can be gotten from the extension’s composer.json file.

The part highlighted in the screenshot above is what we are looking for. You can just copy and use it exactly as it is.

No composer.json file??

If for some reason, your extension doesn’t have a composer.json file, you can also check in the extension’s ext_localconf.php file. In the \TYPO3\CMS\Extbase\Utility\ExtensionUtility::configurePlugin() function used to register an extension’s plugin.

See screenshot below for more details

For those working with Flux and having only a provider extension, look in the extension’s ext_localconf.php file and in the \FluidTYPO3\Flux\Core::registerProviderExtensionKey() function.

There, you will see the Vendor name and Extension’s name to use in the project’s composer.json file.

Extensions without namespaces

For older extension versions which do not use namespaces. That is Pi-Based extensions, the autoload section will look something like below

"autoload": {
        "classmap": [
            "html/typo3conf/ext/custom_extension/pi1/",
            "html/typo3conf/ext/custom_extension_two/pi1/"
        ]
    },

Where custom_extension is the folder name of the extension or extension key.

So a sample complete autoload section of your project’s composer.json having both types of extensions will look like below.

"autoload": {
        "psr-4": {
      "VendorName\\CustomExtension\\": "html/typo3conf/ext/extension_folder_name/Classes/"
    },
        "classmap": [
            "html/typo3conf/ext/custom_extension/pi1/"
        ]
    }

Next, run composer dumpautoload in the terminal to update the composer autoloader. If not, you will get a Class ‘…….’ not found error when trying to access your website’s frontend.

After having done all the above, just access your project in the browser. If everything has been done correctly, then you should be able to access your project just like how it was before in the Non Composer Mode.

Check and add Backend Modules

Some backend modules may not be present or shown in the backend after a migration or an upgrade.

For TYPO3 8.7, this step is not required since all system extensions were installed along side the TYPO3 core.

For TYPO3 9, only the main required TYPO3 system extensions were installed. We will have to install the ones we are going to need. To do this,

Set up the backup project and login to the backend.
Go to Extension Manager.
If any backend module in the backup project which is needed but not found in the migrated project,
Type in the backend module’s name in Extension Manager’s search bar.
From the search result, you will find the extension’s key under the Key column.
Go here, to use the tool to help you easily select the packages you need.
Select your TYPO3 version.
Using the extension’s key, search on the page(page in link above) for the corresponding package and select the package.
NB: If for example the extension key is rte_ckeditor, what you should be searching for is rte-ckeditor.
Repeat until all the extensions you need have been selected.
Now just scroll towards top of the page under Select the composer packages heading and get the generated composer require command.
You have to Activate the downloaded extensions in Extension Manager for them to show in the backend Module Menu.

Check if project in Composer mode

You may want to check to see if your project is in composer mode. To do that,

Login into the TYPO3 backend.
Go to the Extensions module.

You will see something like the screenshot below telling you your project is in composer mode.

Conclusion

So, there you go. You have just migrated a TYPO3 project to composer mode.

If you encountered any problems while following this tutorial or have any questions, just let me know in the comments so I can try to help.

Until next time.