.. include:: /Includes.rst.txt .. _composer-json: ===================== composer.json ===================== *-- required* .. note:: While the file :file:`composer.json` is currently not strictly required for an extension to function properly, it is considered bad practice not to add one. That is why we classify it as "required". Including a :file:`composer.json` is strongly recommended for a number of reasons: #. The file :file:`composer.json` is required for documentation rendering since May 29, 2019. See :ref:`h2document:migrate` 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 :ref:`t3install:migrate-to-composer` in the "Installation & Upgrade Guide". Minimal composer.json ===================== This is a minimal composer.json for a TYPO3 extension: * The vendor name is *Vendorname* * The extension key is *my_extension* Subsequently: * The namespace will be *Vendorname\\MyExtension* * The package name will be *vendorname/my-extension* .. code-block:: json :linenos: { "name": "vendorname/my-extension", "type": "typo3-cms-extension", "description": "An example extension", "license": "GPL-2.0-or-later", "require": { "typo3/cms-core": "^9.5 || ^10.1" }, "extra": { "typo3/cms": { "extension-key": "my_extension" } }, "autoload": { "psr-4": { "Vendorname\\MyExtension\\": "Classes/" } } } .. _ext-composer-json-properties: Properties ========== name ---- (*required*) `/` "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 :file:`Classes` folder, but with different uppercase / lowercase spelling, e.g. `GeorgRinger\News` namespace and `georgringer/news` name in :file:`composer.json`. description ----------- (*required*) Description of your extension (1 line) 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 can add other system extensions and third party extensions, if your extension depends on them. 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 :file:`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**: .. code-block:: json { "extra": { "typo3/cms": { "extension-key": "bootstrap_package" } } } replace ------- (*usually not required*) `replace `__ in a :file:`composer.json` file specifies which other packages can be replaced by this package. This means that packages with different vendor name or package name will be treated as the same package by Composer. Example for extension key **bootstrap_package**: .. code-block:: json { "replace": { "typo3-ter/bootstrap-package": "self.version" } } As all extensions available in the TER can be installed with `composer require typo3-ter/ext-key`, this makes sure that there will be no conflicts with packages installed or required via Packagist or from another source. Since the TER Composer repository is deprecated and not all extensions must be available in TER, this property is usually not required. Properties no longer used ========================= version ------- (*not recommended*) Was used in earlier TYPO3 versions. For versions 7.6 and above you should not use the version property. The version for the extension is set in the file :ref:`ext_emconf.php `. More Information ================ Not TYPO3 specific: * `About Packagist `__ * `composer.json schema `__ * `Composer Getting Started `__ TYPO3 specific: * The :ref:`section on testing ` (in this manual) contains further information about adding additional properties to :file:`composer.json` that are relevant for testing. * `Helmut Hummel: composer.json specification for TYPO3 extensions `__ * `Helmut Hummel: minimal composer.json `__ * `Helmut Hummel: TYPO3 Extension dependencies revisited `__