Jump directly to what you need to make your extensions and sites quickly compatible with TYPO3 v12.
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.
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".
In order to understand our approach of streamlining TYPO3 Extensions, it is helpful to see the differences between TYPO3 Extensions and Composer Packages.
| Topic | TYPO3 Extensions | Composer Packages |
|---|---|---|
| Package Name | Extension 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 Packages | TER (TYPO3 Extension Repository) on https://extensions.typo3.org - free | Packagist on https://packagist.org - free |
| Declaration file | ext_emconf.php (special format) | composer.json |
| List of Dependencies of a package | Extension keys defined in the "depends" section | Composer Package Names defined in the "require" section |
| Package Location | typo3conf/ext/[extension-key] - custom extensions can be placed under this folder, and can be managed completely manually | All required packages are placed under the vendor/ folder |
| Available vs. Installed Packages | Active 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.
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.
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.
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:
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.
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.