composer.json

In Composer, everything is a package, but there are differences between a “project” and a “library” and the best practices that are used within the file composer.json for a project or library.

This page explains the basics for your project (TYPO3 installation) composer.json, while composer.json for libraries (or more specifically for TYPO3 extensions) is handled in TYPO3 Explained composer.json

In a Composer based TYPO3 installation, we typically have a file structure like this:

project-root/
├── composer.json
├── composer.lock
└── public
    ├── fileadmin
    ├── typo3
    ├── typo3conf
    └── ...

You may have used the typo3/cms-base-distribution package (as explained in Install TYPO3 via Composer) which created a composer.json for you or you may want to create a composer.json for your project from scratch.

Example composer.json

{
   "name": "vendor/my-typo3-project",
   "description": "TYPO3 project",
   "license": ["GPL-2.0-or-later"],
   "type": "project",
   "authors": [
      {
         "name": "Author name",
         "email": "nouser@example.com"
      }
   ],
   "require": {
      "php": "^7.4",
      "helhum/typo3-console": "^6.4.0",
      "typo3/cms-backend": "^10.4",
      "typo3/cms-belog": "^10.4",
      "typo3/cms-beuser": "^10.4",
      "typo3/cms-core": "^10.4",
      "typo3/cms-dashboard": "^10.4",
      "typo3/cms-extbase": "^10.4",
      "typo3/cms-extensionmanager": "^10.4",
      "typo3/cms-felogin": "^10.4",
      "typo3/cms-filelist": "^10.4",
      "typo3/cms-fluid": "^10.4",
      "typo3/cms-fluid-styled-content": "^10.4",
      "typo3/cms-form": "^10.4",
      "typo3/cms-frontend": "^10.4",
      "typo3/cms-impexp": "^10.4",
      "typo3/cms-info": "^10.4",
      "typo3/cms-install": "^10.4",
      "typo3/cms-recordlist": "^10.4",
      "typo3/cms-rte-ckeditor": "^10.4",
      "typo3/cms-seo": "^10.4",
      "typo3/cms-setup": "^10.4",
      "typo3/cms-sys-note": "^10.4",
      "typo3/cms-t3editor": "^10.4",
      "typo3/cms-tstemplate": "^10.4",
      "typo3/cms-viewpage": "^10.4"
   },
   "autoload": {
      "psr-4": {},
      "classmap": []
   },
   "config": {
      "sort-packages": true
   },
   "extra": {
      "typo3/cms": {
         "web-dir": "public"
      }
   },
   "scripts": {
      "typo3-cms-scripts": [
         "typo3cms install:generatepackagestates",
         "typo3cms install:fixfolderstructure"
      ],
      "post-autoload-dump": [
         "@typo3-cms-scripts"
      ]
   }
}

You may notice that we include the third party extension helhum/typo3-console here. This is recommended and the section scripts uses it (see below).

Commands for creating composer.json

It is possible to create a composer.json from scratch with composer init. However, in practice, it may be a good idea to have a general composer.json which you reuse for every project and add individual requirements for your projects via command line commands.

In general it is recommended to use the command line to modify composer.json (as in composer require ...). If you modify a composer.json in an existing project directly, you must execute a command like composer install or composer require afterwards to make sure that your composer.lock will be updated.

(Incomplete) example for creating above composer.json (scripts is missing):

composer init --type project
composer config platform.php 7.4.1
composer config sort-packages true
composer config extra.typo3/cms.web-dir public
composer require helhum/typo3-console:^6.4.0 \
   typo3/cms-backend:^10.4 \
   typo3/cms-belog:^10.4 \
   typo3/cms-beuser:^10.4 \
   typo3/cms-core:^10.4 \
   typo3/cms-dashboard:^10.4 \
   typo3/cms-extbase:^10.4 \
   typo3/cms-extensionmanager:^10.4 \
   typo3/cms-felogin:^10.4 \
   typo3/cms-filelist:^10.4 \
   typo3/cms-fluid:^10.4 \
   typo3/cms-fluid-styled-content:^10.4 \
   typo3/cms-form:^10.4 \
   typo3/cms-frontend:^10.4 \
   typo3/cms-impexp:^10.4 \
   typo3/cms-info:^10.4 \
   typo3/cms-install:^10.4 \
   typo3/cms-recordlist:^10.4 \
   typo3/cms-rte-ckeditor:^10.4 \
   typo3/cms-seo:^10.4 \
   typo3/cms-setup:^10.4 \
   typo3/cms-sys-note:^10.4 \
   typo3/cms-t3editor:^10.4 \
   typo3/cms-tstemplate:^10.4 \
   typo3/cms-viewpage:^10.4
composer validate

Reference

config/platform/php

This setting is not TYPO3 specific.

{
   "config": {
      "platform": {
         "php": "add PHP version here"
      }
   }
}

It should correspond to the PHP version on your target system.

config/sort-packages

This setting is not TYPO3 specific.

{
   "config": {
         "sort-packages": true
   }
}

Keeps your composer.json neat by ordering the packages automatically.

repositories

This setting is not TYPO3 specific.

You can add additional repositories, if necessary.

The previously often used repository composer.typo3.org is now deprecated. It is recommended to get your packages from Packagist and only use composer.typo3.org if necessary:

{
   "repositories": [
      {
         "type": "composer",
         "url": "https://composer.typo3.org/"
      }
   ]
}

scripts

{
   "scripts": {
      "typo3-cms-scripts": [
         "typo3cms install:generatepackagestates",
         "typo3cms install:fixfolderstructure"
      ],
      "post-autoload-dump": [
         "@typo3-cms-scripts"
      ]
   }
}

The post-autoload-dump will automatically invoke the scripts after autoloading.

As stated in the Composer documentation:

post-autoload-dump: occurs after the autoloader has been dumped, either during install/update, or via the dump-autoload command.

These commands are supplied by helhum/typo3-console:

install:generatepackagestates:

Generates the typo3conf/PackageStates.php. This will automatically scan the extension folders and add the extensions to PackageStates.php, thus marking them active.

install:fixfolderstructure

This creates the required folder structure needed for TYPO3.

Important

Should be executed after generatepackagestates.