composer.json
¶
-- required in Composer-based installations
Note
While the file composer.json
is currently not strictly required
for an extension to function properly in legacy non-Composer installations
it is recommended to keep it in any public extension that is published to
TYPO3 Extension Repository (TER).
Including a composer.json
is strongly recommended for a number of reasons:
The file
composer.json
is required for documentation rendering since May 29, 2019.See Register for docs.typo3.org for more information on the necessary changes for extension documentation rendering.
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 "Installation & 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 namespace will be MyVendor\MyExtension
The package name will be my-vendor/my-extension
{
"name": "my-vendor/my-extension",
"type": "typo3-cms-extension",
"description": "An example extension",
"license": "GPL-2.0-or-later",
"require": {
"typo3/cms-core": "^11.5 || ^12.0"
},
"autoload": {
"psr-4": {
"MyVendor\\MyExtension\\": "Classes/"
}
},
"extra": {
"typo3/cms": {
"extension-key": "my_extension"
}
}
}
see composer.json schema for general Composer information
see Properties below for TYPO3 specific hints
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.
Note
Extension authors should ensure that the information in the composer.json
file is in sync with the one in the extensions' ext_emconf.php
file.
This is especially important regarding constraints like depends
, conflicts
and suggests
. Use the equivalent settings in composer.json
require
,
conflict
and suggest
to set dependencies and ensure a specific loading order.
Extended composer.json¶
Note
Please see Extension testing for
further changes to composer.json
for testing extensions.
{
"name": "my-vendor/my-extension",
"type": "typo3-cms-extension",
"description": "An example extension",
"license": "GPL-2.0-or-later",
"require": {
"php" : "^7.4",
"typo3/cms-backend": "^11.5 || ^12.0",
"typo3/cms-core": "^11.5 || ^12.0"
},
"require-dev": {
"typo3/coding-standards": "^0.7.1"
},
"authors": [
{
"name": "John Doe",
"role": "Developer",
"email": "john.doe@example.org",
"homepage": "johndoe.example.org"
}
],
"keywords": [
"typo3",
"blog"
],
"support": {
"issues": "https://github.com/my-vendor/my-extension/issues"
},
"funding": [
{
"type": "other",
"url:" : "myfundpage.org/my-vendor"
}
],
"autoload": {
"psr-4": {
"MyVendor\\MyExtension\\": "Classes/"
}
},
"extra": {
"typo3/cms": {
"extension-key": "my_extension"
}
}
}
see composer.json schema for general Composer information
see Properties below for TYPO3 specific hints
Properties¶
name¶
(required)
<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,
e.g. GeorgRinger\News
namespace and georgringer/news
name in composer.json
.
type¶
(required)
Use typo3-cms-extension
for third party extensions. This will result in
the extension to be installed in {web-dir}/typo3conf/ext
instead
of vendor/{vendor}/{package}
.
Use typo3-cms-framework
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 the least, you will want to require typo3/cms-core
.
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)
Define namespace - path mapping for PSR-4 autoloading.
In TYPO3 we follow the convention that all classes (except test classes)
are in the directory Classes
.
extra¶
(required)
Not providing this property will emit a deprecation notice and will fail in future versions.
Hint
The property "extension-key" means the literal string "extension-key", not your actual extension key. The value on the right side should be your actual extension key.
Example for extension key bootstrap_package:
{
"extra": {
"typo3/cms": {
"extension-key": "bootstrap_package"
}
}
}
Properties no longer used¶
version¶
Was used in earlier TYPO3 versions. For TYPO3 versions 7.6 and above you should not use the version property. The version for the extension is set in the file ext_emconf.php. Composer primarily takes the version information from repository tags, so the releases need to be tagged in the VCS repository with a version number.
replace with typo3-ter
vendor name¶
{
"replace": {
"typo3-ter/bootstrap-package": "self.version"
}
}
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"
¶
{
"replace": {
"ext_key": "self.version"
}
}
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.
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 and source code can be helpful to understand how it works.