composer.json

-- required in Composer-based installations

Introduction

Composer is a tool for dependency management in PHP. It allows you to declare the libraries your extension depends on and it will manage (install/update) them for you.

Packagist is the main Composer repository. It aggregates public PHP packages installable with Composer. Composer packages can be published by the package maintainers on Packagist to be installable in an easy way via the composer require command.

About the composer.json file

Including a composer.json is strongly recommended for a number of reasons:

  1. The file composer.json is required for documentation that should appear on docs.typo3.org.

    See Register for docs.typo3.org for more information on the necessary changes for rendering of extension documentation.

  2. Working with Composer in general is strongly recommended for TYPO3.

    If you are not using Composer for your projects yet, see Migrate a TYPO3 project to composer in the "Upgrade Guide".

Minimal composer.json

This is a minimal composer.json for a TYPO3 extension:

  • The vendor name is MyVendor.
  • The extension key is my_extension.

Subsequently:

  • The PHP namespace will be MyVendor\MyExtension
  • The Composer package name will be my-vendor/my-extension
EXT:my_extension/composer.json
{
    "name": "my-vendor/my-extension",
    "type": "typo3-cms-extension",
    "description": "An example extension",
    "license": "GPL-2.0-or-later",
    "require": {
        "typo3/cms-core": "^10.4 || ^11.5"
    },
    "autoload": {
        "psr-4": {
            "MyVendor\\MyExtension\\": "Classes/"
        }
    },
    "extra": {
        "typo3/cms": {
            "extension-key": "my_extension"
        }
    }
}
Copied!

Changed in version 11.4

The ordering of installed extensions and their dependencies are loaded from the composer.json file, instead of ext_emconf.php in Composer-based installations.

Extended composer.json

EXT:my_extension/composer.json
{
    "name": "my-vendor/my-extension",
    "type": "typo3-cms-extension",
    "description": "An example extension",
    "license": "GPL-2.0-or-later",
    "require": {
        "php": "^7.2",
        "typo3/cms-backend": "^10.4 || ^11.5",
        "typo3/cms-core": "^10.4 || ^11.5"
    },
    "require-dev": {
        "typo3/coding-standards": "^0.7.1"
    },
    "authors": [
        {
            "name": "John Doe",
            "role": "Developer",
            "email": "john.doe@example.org",
            "homepage": "https://johndoe.example.org/"
        }
    ],
    "keywords": [
        "typo3",
        "blog"
    ],
    "support": {
        "issues": "https://example.org/my-issues-tracker"
    },
    "funding": [
        {
            "type": "other",
            "url:": "https://example.org/funding/my-vendor"
        }
    ],
    "autoload": {
        "psr-4": {
            "MyVendor\\MyExtension\\": "Classes/"
        }
    },
    "extra": {
        "typo3/cms": {
            "extension-key": "my_extension"
        }
    }
}
Copied!

Properties

name

(required)

The name has the format: <my-vendor>/<dashed extension key>. "Dashed extension key" means that every underscore (_) has been changed to a dash (-). You must be owner of the vendor name and should register it on Packagist. Typically, the name will correspond to your namespaces used in the Classes/ folder, but with different uppercase / lowercase spelling, for example: The PHP namespace JohnDoe\SomeExtension may be johndoe/some-extension in composer.json.

description

(required)

Description of your extension (1 line).

type

(required)

Use typo3-cms-extension for third-party extensions. This results in the extension to be installed in {web-dir}/typo3conf/ext/ instead of vendor/{vendor}/{package}.

Additionally, typo3-cms-framework is available for system extensions. They will be installed in web-dir/typo3/sysext/.

See typo3/cms-composer-installers (required by typo3/cms-core).

license

(recommended)

Has to be GPL-2.0-only or GPL-2.0-or-later. See: https://typo3.org/project/licenses/.

require

(required)

At least, you will need to require typo3/cms-core in the according version(s). You should add other system extensions and third-party extensions, if your extension depends on them.

In Composer-based installations the loading order of extensions and their dependencies is derived from require and suggest.

suggest

You should add other system extensions and third-party extensions, if your extension has an optional dependency on them.

In Composer-based installations the loading order of extensions and their dependencies is derived from require and suggest.

autoload

(required)

The autoload section defines the namespace/path mapping for PSR-4 autoloading <https://www.php-fig.org/psr/psr-4/>. In TYPO3 we follow the convention that all classes (except test classes) are in the directory Classes/.

extra.typo3/cms.extension-key

(required)

Not providing this property will emit a deprecation notice and will fail in future versions.

Example for extension key my_extension:

Excerpt of EXT:my_extension/composer.json
{
    "extra": {
        "typo3/cms": {
            "extension-key": "my_extension"
        }
    }
}
Copied!

Properties no longer used

replace with typo3-ter vendor name

Excerpt of EXT:my_extension/composer.json
{
    "replace": {
        "typo3-ter/my-extension": "self.version"
    }
}
Copied!

This was used previously as long as the TER Composer Repository was relevant. Since the TER Composer Repository is deprecated, the typo3-ter/* entry within replace is not required.

replace with "ext_key": "self.version"

Excerpt of EXT:my_extension/composer.json
{
    "replace": {
        "ext_key": "self.version"
    }
}
Copied!

This was used previously, but is not compatible with latest Composer versions and will result in a warning using composer validate or result in an error with Composer version 2.0+:

Deprecation warning: replace.ext_key is invalid, it should have a vendor name, a forward slash, and a package name.
The vendor and package name can be words separated by -, . or _. The complete name should match
"^[a-z0-9]([_.-]?[a-z0-9]+)*/[a-z0-9](([_.]?|-{0,2})[a-z0-9]+)*$".
Make sure you fix this as Composer 2.0 will error.
Copied!

See comment on helhum/composer.json and revisions on helhum/composer.json.

More Information

Not TYPO3-specific:

TYPO3-specific:

  • The section on testing (in this manual) contains further information about adding additional properties to composer.json that are relevant for testing.
  • The Composer plugin (not extension) typo3/cms-composer-installers is responsible for TYPO3-specific Composer installation. Reading the README file and source code can be helpful to understand how it works.