“”

Composer Support for TYPO3 Extensions

Jump directly to what you need to make your extensions and sites quickly compatible with TYPO3 v12.

A Brief History of TYPO3 Extensions

TYPO3 introduced the concept of extensions in 2003. This was long before composer was created. However, composer has since then become the de-facto standard for building PHP-based projects with several components and libraries, while properly resolving all their dependencies.

Since TYPO3 v6.2 it is possible to set up a TYPO3 installation in "Composer Mode" or - just like before - in "Classic Mode". Although, this worked for the time being, some basic concepts of TYPO3 extensions are merged together to reduce complexity and make life easier for extension authors. It's already possible for extension authors and site owners to build bridges to support both Composer Mode and Classic Mode, but it increases complexibility - one extension bundles its own Symfony 4.4 LTS code as it needs a specific feature of Symfony that TYPO3 Core does not include, where as an other extension requires Symfony 5.x features. This can only be resolved by the site owners themselves.

PHP projects nowadays depend on other source code, and extending TYPO3 with more packages than just TYPO3 Extensions will allow TYPO3 to become even more powerful. However, there are a lot of benefits of using Composer Mode with TYPO3 these days, even though we know Composer and the Command-Line-Interface is not for everyone.

Downsides of running TYPO3 in Classic Mode in 2021

  • Extension Authors: If an extension relies on third-party code provided by composer, these are loaded automatically, whereas support of such extensions (such as SolR) require additional bundling techniques via a custom autoloading mechanism. 
  • Site Owners: The whole TYPO3 artifact (tarball / zipfile) contains all available shipped system extensions from TYPO3 Core, even though the end-user is not activating this extension - more code means more risk of security.
  • Site Owners: When installing TYPO3 in Composer Mode, a lot of non-public project files (PHP files, caches, configuration) are moved outside of the web root, which increases security.
  • Site Owners with PHP Knowledge can easily integrate other PHP frameworks in TYPO3, such as a shop system or a library for performance.
  • Site Owners: Deployment and Versioning (via Git) of the configuration files is made much more complicated with Classic Mode.

Did you know? TYPO3 Core itself depends on third-party libraries since over 5 years, which the Core developers integrate internally via composer, and the releases bundle a artifact (tarball / zipfile) for the Classic Mode. Please also keep an eye on the so-called "subtree split".

Key Differences between TYPO3 Extensions and Composer Packages

In order to understand our approach of streamlining TYPO3 Extensions, it is helpful to see the differences between TYPO3 Extensions and Composer Packages.

TopicTYPO3 ExtensionsComposer Packages
Package NameExtension Key with only lowercase and alphanumeric values
(e.g. "powermail" or "fal_securedownloads")
Vendor Name + Package Name divided by a "/"
(e.g. "in2code/powermail" or "beechit/fal-securedownload")
Central Repository of PackagesTER (TYPO3 Extension Repository) on https://extensions.typo3.org  - freePackagist on https://packagist.org - free
Declaration fileext_emconf.php (special format)composer.json
List of Dependencies of a packageExtension keys defined in the "depends" sectionComposer Package Names defined in the "require" section
Package Locationtypo3conf/ext/[extension-key] - custom extensions can be placed under this folder, and can be managed completely manuallyAll required packages are placed under the vendor/ folder
Available vs. Installed PackagesActive Extensions are loaded and tracked via typo3conf/PackageStates.php. TYPO3's Extension Manager is used to activate / deactivate an extension available under typo3conf/ext/All required / downloaded packages are automatically available at any time

There are some fundamental differences between Composer Packages and TYPO3 Extensions and their purposes. Composer is first of all a dependency manager. If your project has a dependency to a PHP library (could be an extension), it is fetched, and all PHP classes made available through Composers' autoloader functionality, as defined in the Packages' composer.json file. TYPO3 Extensions are all about extending TYPO3's Core functionality, may it be via shipped TypoScript, additional configuration settings, or PHP classes.

Package Naming

One major difference is TYPO3's handling of extension keys, something that will stay around for a long time (such as "EXT:my_extension" syntax throughout TYPO3). TYPO3 actually resolves the extension key and checks for the path taken from typo3conf/PackageStates.php. The actual extension does not necessarily know about its name, as it is completely based on the folder name of the extension. typo3conf/ext/my_extension.bak is completely valid, even though it shouldn't be used like this.

An extension key can be registered on TER (TYPO3.org account required) to avoid conflicts if an extension gets published in TER.

In contrast, composer packages contain the vendor and package name. The vendor (or owner / author / publisher) can be reserved on packagist.org by creating a package under a specific vendor (e.g. "typo3", all lowercase). Every package of the vendor "typo3" can have its own naming. it is possible to have a "typo3/shop" and "symfony/shop" and have both available, which isn't possible with TYPO3 extension keys, as the vendor prefix concept does not exist. The concept of the vendor prefix might be familiar to TYPO3 Extension authors by using PHP classes with a namespace, where the vendor name is typically the first part of the PHP namespace.

Bringing Classic Mode and Composer Mode closer together

We have a lot of plans in the pipeline for moving closer to standards, but our plans are always to take a slow and easy way to migrate all existing TYPO3 installations to these new standards. And we're starting with the need for each extension to ship a valid composer.json file, which TYPO3 Core will be using to create a list of all available and active extensions. 

Step 1: Using composer.json instead of ext_emconf.php

TYPO3's mid-term plans are to make the usage of ext_emconf.php files obsolete, and fully depend on the composer.json file shipped with an extension. TYPO3 v12 will require each extension to contain a composer.json file with all needed information, such as the extension key property. The ext_emconf.php file will then not be evaluated anymore. 

For the time being, we have an upgrade phase where both files are evaluated (depending on the existance of composer.json of extensions) in TYPO3 v10 and TYPO3 v11 LTS.

All new versions of an extension on TER now need to provide a valid composer.json file from now on. Our Extension Builder Tools, the Site Package Builder and TYPO3 Core ship with accurate composer.json files. And for all extensions that you use just for your site and you can't share with the world, we already registered a Composer Vendor for you: "typo3-local". So "typo3-local/my-site-extension" is completely valid for your extensions in your own projects.

The good thing is - you can prepare today and make sure you have everything set up for the future with a few clicks. TYPO3 v10.4.16 and TYPO3 v11.2 ship with a new feature in the Extension Manager that scans all your extension folders for valid composer.json files, and if there is a problem, it will report it and tell you how to fix it on your local TYPO3 Installation. And if you don't have a composer.json file in one of your extension, TYPO3's Extension Manager will upload the corresponding ext_emconf.php contents to TER and receives a proposal for a composer.json file of this extension. We never store any of this information, our main goal is to help you make sure your upgrades will run through easily. 

For TYPO3, the most important values are:

  • type should be set to "typo3-cms-extension"
  • name should contain a proper vendor name + package name, all in lower-case
  • the extra section should contain the extension-key, like you've been using it to reference the extension just until today.

For those of you who want to create a composer.json file theirselves in their favorite text editor, here is an example:

{
    "name": "typo3-local/site-benni",
    "description": "Templates and TypoScript for my website.",
    "license": "GPL-2.0-or-later",
    "type": "typo3-cms-extension",
    "authors": [
        {
            "name": "A TYPO3 Site Owner",
            "email": "no-email@given.com"
        }
    ],
    "require": [],
    "suggest": [],
    "conflict": [],
    "extra": {
        "typo3/cms": {
            "extension-key": "site_benni"
        }
    },
    "version": "dev-local",
    "autoload": {
        "classmap": [
            "*"
        ]
    }
}

If you know that you also have PHP files in your extension folder, such as ViewHelpers or custom Extbase plugins, be sure to also define a autoload section.

Our Next Steps

We have a lot of more ideas to bring Classic Mode and Composer Mode closer together, and will update this document and inform you if you need to take any action.