Best practices

Run composer locally

You should not run composer on your live webspace. You always should run composer on your local machine, so you can test if everything worked fine. After running your tests, you can deploy the vendor and public folder to your web server.

To avoid conflicts between your local and your server’s PHP version, you can define your server’s PHP version in your composer.json file (e.g. {"platform": {"php": "7.2"}}), so composer will always check the correct dependencies.

Update packages

After updating any packages, you always should commit your composer.lock to your version control system and your co-workers should run composer install after checking out the updates.

Update all packages

Run composer update without any other attributes, to update all packages. Composer will always try to install the newest packages that match the defined version constraints.


Be careful with that. This command may cause negative effects if you do not have proper version constraints in your composer.json. You always should prefer to update your packages separately.

Update single packages

When you want to update single packages, you can call the update command with the package name. You should always add --with-dependencies attribute to also update the required third party packages.

Update TYPO3 core

Without “subtree split”

composer update typo3/cms --with-dependencies

With “subtree split”

composer update typo3/cms-* --with-dependencies

Update extensions like “news”

composer update georgringer/news --with-dependencies

Use “dev requirements”

Add packages with --dev attribute to add packages only to your local development environment. This is very useful for packages, you do not need or do not want to have on your live server, e.g. PHPUnit or Testing-Frameworks:

composer require typo3/testing-framework:^2.0 --dev

During your deployment routine, you should run composer install with attribute --no-dev. So the dev requirements are not installed.

composer install --no-dev

Remove extensions

You can use the composer command remove to uninstall extensions or other composer packages.

composer remove georgringer/news

Don’t forget to commit your updated composer.lock to your version control system.


Please be sure to disable extensions in TYPO3’s Extension Manager, before removing them with composer. Or ensure to regenerate your typo3conf/PackageStates.php file automatically, after removing the packages. You could use the extension “typo3_console” for that

Check for available updates

Run composer outdated to see a list of available updates.

Completely clear “typo3conf/ext” folder

In the “Migration Steps” chapter, this tutorial explained, how you can keep your individual extension in “typo3conf/ext” and in the “Co-working” section, there was a part about how to add rules to your .gitignore file to exclude typo3conf/ext from, but keep your individual extensions in Git.

If you are searching for a solution to keep your typo3conf/ext folder clean and unify the extension handling even for your project’s individual extension, this chapter might be useful.

Define a local path repository

Create a directory packages in your project root folder and define this folder as a repository of type “path” in your composer.json:

    "repositories": [
            "type": "path",
            "url": "./packages/*"

Include your individual extensions from “packages” folder

In the next step, you move all your individual extensions from public/typo3conf/ext to packages. And for this way to include them, it’s important, that each extension has it’s own correct composer.json file. How this file should look in your extension, can be found on or this blog post from Helmut Hummel.

Assumed, your package key is, foo/bar, you can type the following command to include your extension to your project:

composer require foo/bar:@dev

In this case, it’s the easiest way to not define any composer version number, but tell composer to use the latest dev state.


The autoload information now comes with the extension’s composer.json and can be removed from your project’s composer.json.

Exclude “typo3conf/ext” from version control system

To finish your cleanup of “typo3conf/ext”, you should keep the line /public/typo3conf/ext/* in your .gitignore, but remove all lines, starting with !/public/typo3conf/ext/.

Useful packages and bundles

Simplify “subtree split” installations

Instead of explicitly requiring each core extension, you can require typo3/minimal, which brings the minimal required set of system extensions.

TYPO3 CMS Base Distribution

Primarily, typo3/cms-base-distribution is not meant to be used with composer require, but to really quickly start new composer based TYPO3 projects.

Nevertheless, it’s very good to have heard about it. If you’re interested in more information, you should check the packages README.

Secure Web

helhum/typo3-secure-web follows the very interesting concept to split the traditional web root directory into two parts: the “public” one for all the resources, that must be directly accessible via HTTP (images, styles, etc.) - and the “private” folder, where all the PHP will be located.

This helps to make your TYPO3 installations even more secure!