General

This manual will show you, how to work with the new Composer structure. It will explain whats the best way, if you are working on extensions, how you can create a patch for a Composer extension and what's the steps of adding a new extension.

What is Composer

Composer is an application-level package manager that provides a standard format for managing dependencies of PHP software and required libraries. Composer runs through the command line. It also allows users to install PHP applications that are available on a package server which contains available packages. It also provides autoload capabilities for libraries that specify autoload information to ease usage of third-party code.

Why Composer

The big advantages of Composer in relation to TYPO3 are, that the performance is much better, because it doesn't need to generate the autoload files for each extension. The next big thing is, that using Composer provides a big flexibility regarding maintenance of the project. For example you can easily add, remove and control the updates of extensions.

Glossary

  • Root (composer.json / directory / Git) - That means always the first level of the website base. On the same level are the directory web, vendor, typo3_src, ...
  • Extension Manager - This means the extension manager of TYPO3. It's not relevant for Composer.
  • TER - This is short for TYPO3 Extension Repository.

Working with extensions.

This will explain, what's the best way to work on extension with the new structure.

Working on a Composer extension (e.g. project_base)

  1. Make sure you are in the Git branch, you want to work with. That's important, because Composer could change it.
  2. Do your changes to this extension.
  3. Raise the version in the extension's ext_emconf.php and composer.json. You can read in the next section, how you could do it.
  4. Push it into the the Git repository of this extension.

You need to do the next steps only, if you pushed the changes into the master branch, or if your feature branch will be merged into the master branch.


  1. Create a new tag with the given version number.
  2. Adapt the root composer.json and adapt the extension version to the new one.

Here you need to adapt the version:

"sgalinski/project-base": "^2.0",

Working on a local extension (e.g. project_theme)

  1. Do your changes to this extension.
  2. Push them into the root repository. (i.e. Git of the website-base)

Version numbers. How should I raise them?

A good tutorial for that is on this website.

Note: The example is for the version number 2.1.12.

 

2   -> It's a breaking change, or a new big feature             -> 3
1   -> It's a small feature or task                             -> 2
12  -> It's a bug fix or a small cleanup, like code formatting  -> 13

Patching

This will explain, how you can create and apply patches for Composer extensions. (e.g. project_base)

Create a patch

The first step is to do your changes in the extension. Afterwards you need to execute the following command:

git diff > whatDoesThisPatch.diff

This will create a patch file with the changes you have done. Now you should move them into the root's patches directory. Now you could add a README file with the information, what exactly the patch does, because you probably won't remember this in a year anymore. This will allow a better maintenance.

Apply the patch

To apply a patch, you just need to add the following lines to the root composer.json. This will apply the patch on the next "composer install" or "composer update". The extension, which the patch modifies, will be reinstalled.

Note: The extension "cweagans/composer-patches" allows the patching, so it won't work without it.

"require": {
    "cweagans/composer-patches": "~1.0",
    "sgalinski/project-base": "^2.0",
},
"extra": {
    "patches": {
        "sgalinski/project-base": {
            "Some description what the patch does": "patches/project_base/whatDoesThisPatch.diff"
        },
    },
},

Adding extensions

This will show you how to add a Composer extension to the project.

Note:

  • Each way requires the execution of the command "composer install" or "composer update" on the root directory, after you added the json code.
  • Don't forget to check the TYPO3 extension manager after each installation, if the extension is activated.
  • A good tutorial for requiring the correct extension version number in the root's composer.json can be found on this site.

Installation of project_theme extensions

How to add an extension for the project_theme (e.g. _project_themeamp or _project_thememegamenu):

  • Add dependency to the project_theme's (local/project_theme) composer.json:
{
  "require": {
      "sgalinski/project-theme-megamenu": "^1.8"
  }
}
  • Delete the project_theme symlink under web/typo3conf/ext/project_theme_.

  • Run the following command from the root directory:

composer require sgalinski/project-theme:@dev

An extension, which isn't using composer

First you need to copy the extension into the "web/typo3conf/ext/". Afterwards you just need to add some lines into the root composer.json. Don't forget to exclude the extension from your projects .gitignore file!

"autoload": {
    // The extension contains namespaced classes:
    "psr-4": {
        "Vendor\\ExtensionKey\\": "web/typo3conf/ext/extension_key/Classes/"
    },
    // It is a legacy extension, without namespaces.
    "classmap": [
        "web/typo3conf/ext/extension_key/"
    ]
}

A TER extension

If you want to add a TER extension, you just need to get version number (e.g. 1.4.2) and the extension key. (e.g. tinymce4_rte) Now the following lines need to be added to the root's composer.json:

"repositories": [
    // Make sure, that this is added in the repositories section.
    {
        "type": "composer",
        "url": "https://composer.typo3.org/"
    }
],
"require": {
    // You need to replace the extension key's underscores to hyphens.
    "typo3-ter/tinymce4-rte": "the.version.number"
},

A Github extension

The first step is to check, if the extension contains a composer.json. If not, you can't add the extension through Composer. If you found the file, you need to copy the value of the key "name" out of this file.

"name": "vendor/extension-key", <-- Copy this value
"type": "typo3-cms-extension",
"description": "Extension documentation",
...

Now you need to add the following line to the root's composer.json:

"require": {
    "vendor/extension-key": "the.version.number"
},

You don't need to add a repository for Github, because Composer adds Github by default.