TYPO3 extension management with Composer

See also

For a beginner-friendly introduction on extension management with Composer, see:

Getting Started Guide: Working with extensions

Table of contents

Install or require an extension with Composer

Composer distinguishes between requiring and installing an extension. By default you can require any package registered on https://packagist.org/ and compatible with your current requirements.

Composer require

When you use the command composer require or its abbreviated, shortened version composer req the requirement will be added to the file composer.json and Composer installs the latest version that satisfies the version constraints in composer.json, and then writes the resolved version to composer.lock.

For example, to install the extension georgringer/news :

# Install the news extension
composer require georgringer/news

If necessary you can also require the extension by adding a version requirement:

# Install the news extension in version 12.3.0 or any minor level above
composer require georgringer/news:"^12.3"

# Install the news extension from the main branch
composer require georgringer/news:"dev-main"

See also

command "composer require"
"Writing Version Constraints" in the Composer documentation for more version constraint examples.

Composer will then download the extension into the vendor folder and execute any additional installation steps.

You can now commit the files composer.json and composer.lock to Git.

Composer install

If the same project is installed on other systems — such as a co-worker’s computer or the production server (if you are working with Git and Composer deployment) — you do not need to run composer require again. Instead, use composer install to install the exact versions defined in composer.lock:

git update

# Install versions that have been changed
composer install

# Rerun the setup for all extensions
vendor/bin/typo3 extension:setup

See also

command "composer install"

List extensions

Just like in the TYPO3 core, extensions are individual Composer packages. You can list all installed packages, including extensions, using the following command:

composer info

This will display a list of all installed packages along with their names and version numbers.

See also

command "composer info"

Extension setup

Many extensions make TYPO3-specific changes to your system that Composer cannot detect. For example, an extension might define its own database tables in the TCA or require static data to be imported.

You can run the following command to set up specific or all extensions:

# Setup the extension with key "news"
vendor/bin/typo3 extension:setup --extension=news

# Setup all extensions
vendor/bin/typo3 extension:setup

You can also Automate extension setup.

Tip

The Composer package name (for example, georgringer/news) and the TYPO3 extension key (for example news) are not the same.

The extension key is defined in the extension’s composer.json under the key extra.typo3/cms.extension-key.

Automate extension setup

You can run the extension setup command automatically after each require / install / update command by adding it to the script section of your project's composer.json:

composer.json (Excerpt)

{
    "scripts":{
        "typo3-cms-scripts": [
            "vendor/bin/typo3 extension:setup"
        ],
        "post-autoload-dump": [
            "@typo3-cms-scripts"
        ]
    }
}

See also

Composer scripts

Installing a custom extension or site package via Composer

In most projects there will be one special extension per site, called a site package, that contains the theme and configuration for that site.

There could also be custom extensions only for a specific domain in that project.

Both these types of extensions should be placed in the packages folder and required in Composer as local (@dev) versions. This will create a symlink from packages to vendor, allowing the extensions to be used like any other package.

Place the extension into the folder packages so that its composer.json can be found at packages/ext_key/composer.json

Require the extension using Composer and specifying the @dev version:

# Require a custom site package
composer require myvendor/my-site-package:"@dev"

# Require a custom extension
composer require myvendor/my-local-extension:"@dev"

Composer install will work as described in Composer install if the extension is available on the system where you run the composer install command.

You will usually commit the files composer.json, composer.lock and the content of the packages folder to the same Git repository.

See also

Installing extensions from a different source

You can define Composer repositories to install packages (including TYPO3 extensions) from different sources like Git, a local path and Private Packagist.

After adding the repository to your project's composer.json, you can require the extension using the standard composer require command.

composer.json (Excerpt)

{
    "repositories": [
        {
            "type": "vcs",
            "url":  "git@bitbucket.org:vendor/my-private-repo.git"
        },
        {
            "type": "artifact",
            "url": "path/to/directory/with/zips/"
        },
        {
            "type": "path",
            "url": "../../local_packages/my_custom_extension/"
        },
        {
            "type": "path",
            "url": "site_packages/*"
        }
    ]
}

Extension update via Composer

Attention

The command composer update cannot easily be reverted. We recommend using Version control (Git) and committing both files composer.json and composer.lock before running an update command.

If you are not using Git, make a backup of these two files before the update.

The following command updates all installed Composer packages (both TYPO3 extensions and other PHP packages/libraries) to the newest version that the current constraints in your composer.json allow. It will write the new versions to file composer.lock:

# Warning: Make a backup of composer.json and composer.lock before proceeding!
composer update

If you want to do a major Upgrade, for example from georgringer/news Version 11.x to 12.x, you can require that extension with a different version number:

# Attention make a backup of the composer.json and composer.lock first!!
composer require georgringer/news:"^12"

See also

Downgrading an extension

If an extension does not work after upgrade you can downgrade the extension by requiring a specific version:

# Attention make a backup of the composer.json and composer.lock first!!
composer require georgringer/news:"12.0.42"

The extension will remain locked to the specified version and will not be updated until you change the version constraint using the composer require command.

Reverting extension updates

As a last resort you can revert any changes you have made by restoring the files composer.json and composer.lock and running the command composer install:

# restore composer.json and composer.lock
git stash

# Reinstall previously used versions
composer install

See also

command "composer install"

Removing an extension via Composer

You can remove an extension requirement from your project's composer.json by using the command composer remove, but bear in mind that the extension will only be uninstalled if it is no longer required by any of the installed packages.

# Check the extension is not in use first!
# composer remove georgringer/news

Composer will not check if the extension is currently in use. Composer can only check if the extension is listed in the require section of the composer.json file of another extension.

See also

command "composer remove"

Check if the extension is in use

Manually verify whether the extension is still in use before uninstalling it.

Does the extension have Site sets that are required by a site configuration or another extension's site set?
Are you using any plugins or content elements provided by the extension? Tip: Extension fixpunkt/backendtools lists all plugins and content elements that are in use.
Have you included any TypoScript provided by the extension? Or tables defined by its TCA? Does it include Middleware, Console commands (CLI) or any other functionality that your project relies on?

Why an extension cannot be uninstalled

If Composer refuses to remove an extension with composer remove you can run the following command to find out what other packages require the Extension you want to remove:

# Show which package requires the extension
composer why georgringer/news

See also

command "composer why"

In very stubborn cases the following tricks can help:

Ensure you have a backup of the files composer.json and composer.lock or have committed them to Git.

Then delete the vendor folder (it will be restored by Composer), delete composer.lock and run composer install. This will reinstall your requirements from your composer.json. Deleting the Composer cache first might also help.

composer clear-cache
rm -rf vendor/
rm composer.lock
composer install

See also