Zum Inhalt springen

Setting up TYPO3 in composer mode

Last updated on 7. April 2019

Satre said: „Hell is other people“. In IT it’s frameworks and added abstraction layers.

We all got familiar and comfortable with symlinks to folders, where we store our different TYPO3 versions and a nicely layouted backend where you choose your extensions. Lately you even get proper hints on pop-up windows, what an update of an extension is changing and whether it has breaking changes or not.

ALL GONE!
Welcome to composer mode.

Why? Maybe the core team assumes that the world is full of people who have to setup 10 instances of TYPO3 every day and they are just fed up of creating symlinks and loading four to five extensions with each new website.
Here at zazu.berlin we don’t have these kind of problems since we are not captured in a conveyor belt kind of website production. We are dedicated to get the best structure and form for every customers business, so setting up the basic skeleton of a website is also a time span of adjusting the mind of the integrator to the journey that is in front of him. It’s a warming up where things usually go nice and smoothly. It’s like putting your players on the field, before you start the game.

What is composer mode?

Composer uses a setup file in the json-format in which you list the TYPO3 version you want plus all it’s dependencies, including the extensions (normal extensions and the system extension) you intend to use.

In order to get a working TYPO3 setup, the starting composer.json also involves two typo3cms scripts that will create the typical folders and files of a working TYPO3 environment. The idea is, that you can trim your personal TYPO3 setup to the system extensions you really need and skip the rest.

If they are not enabled – in the old setup – system extensions don’t take a lot of space and if a disabled system extension is a real security isssue, I would doubt.

The second idea is, that every extension is bringing it’s own composer.json that will then take care of the dependencies of the respective extension and the depending other extensions will then bring their own composer.json who will then take care of that dependencies … and so on.

composer install

„composer install“ is the magic command that – with a proper composer.json in the respective folder – will bring up the complete TYPO3 system. Later on „FIRST_INSTALL“ is still needed to get a Localconfiguration.php and a database connection. Sounds great, if there would not be the „but“ …

But …

  • since it is your setup composer.json, you yourself has to take care of updates and changes -> more work
  • extensions and their versions change on a almost daily basis, so before every new installation, there is some research to do -> more work
  • The nice backend pop-up windows, that tells you about changes of different extensions (especially breaking changes) are gone. You have to check every extension in the repository or on the version control system – bitbucket or github. -> much more work
  • don’t miss a comma in the composer.json, otherwise it will not work (I usually have one comma to much at the end of a block) -> more hassle
  • composer is executed on a cli (bash), so the php-version for the respective TYPO3 version, that composer is checking, is the version of the cli and not the version of the server. Since with most ISP this are very different php versions, you have a problem to solve -> more hassle
  • you have to learn how to structure a json file and you have to learn a new abstraction process, that will make things more complicated and not intuitive to understand -> higher barrier for newcomers
  • your graphical backend extension area is blocked, if you have changes you have to go through composer (e.g. adding an extension) -> more complicated
  • if you update your extensions there is no warning about breaking changes -> longer debugging time

For me the question is, why should I automate processes that are easily done step by step, when I get such a load of things to take care of, only to have a one click installation and a one click „composer update“. For me it feels like a bad deal. And additionally I have more scripts to debug and possible wrong or outdated parameters. „FIRST_INSTALL“ was managed and adjusted by the core team, the composer.json is my playground for searching misspelled names. And who on earth knows exactly what every system extension is doing and which of them I don’t need to have on the server since this is also a field of change. In the end most of the time people will just go for the whole lot of system extensions, as they did before.

Let’s start with composer – since we have to

Assuming you work on Linux – in my case Debian/Ubuntu – first update the archive so apt-get knows what is there:

apt-get update

And then get and install composer

apt-get install composer

Check if everything worked, by checking the version:

composer -v

You will get a nice output with the commands:

composer linux

Go to your htdocs folder of the server and make a folder for your TYPO3 installation plus change the owner and the rights of the folder:

cd /var/ ... where ever it is on your server
sudo mkdir typo3

sudo chmod 774 typo3
sudo chown yourUserName:yourUserName typo3

Go to your linux home directory and change the ownership of the file „.composer“ that – since we used sudo for apt-get – also has only root rights and root ownership. Composer is using this folder for cache files and needs the right to write in it.

You can also run composer with a „sudo“ in front but then all execution files you create will get root rights. This of course is a security issue!

In your Linux home directory you do:

sudo chmod -R 774 .composer
sudo chown -R yourUserName:yourUserName .composer

Got to the TYPO3.org website and get the recommended command for setting up a new project in the download section. Now move back to your new typo3 folder and start the command

composer require typo3/minimal

In March 2019 you still get a warning about using „mso/idna“. This is fixed in the next TYPO3 update – for now just ignore it. If you get a warning about using composer in root mode or that the folder „.composer“ is not writable, just repair it, as it is described above.

TYPO3 minimal – what is minimal?

Minimal is something that doesn’t work. Surprise, surprise, we don’t want things to be too easy.
You should definitely raise your hourly wages after this!

We got:

composer.json
composer.lock
public
vendor
  • composer.json holds the recipe for composer
  • composer.lock holds a safety backup recipe, with detailed information
  • public is the destination folder for the server and holds also TYPO3!
  • vendor holds additional software like typo3fluid (not the extension), and some other stuff like symphony.

Please note:

No more symlinks!

TYPO3 is just in the destination folder of the web server (here „public“). If you like to join the discussion, why and for what reasons, see link below.

https://github.com/TYPO3/CmsComposerInstallers/issues/75

If you now check the composer.json (our recipe) you will find:

{
    "require": {
        "typo3/minimal": "^9.5"
    }
}

The composer.lock file holds the whole process that was done on your server by composer. At the top of the file you will find a link to more explanations. But for the time being this file is not important.

"This file locks the dependencies of your project to a known state",
        "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#composer-lock-the-lock-file",

What do we miss?

We miss things like:

  • fileadmin
  • typo3conf
  • typo3temp
  • uploads

And if you check inside the typo3/sysext folder you will miss some of the system extensions like:
form, rte_ckeditor, scheduler, seo, felogin, fluid-styled-content …

So this is what it says: minimal.

A word about extensions in the framework of composer

Composers home is https://packagist.org/ everything is expected to be there. This means that all extensions from the TYPO3 repository should move – for the time being as a second home – to packagist with a vendor name (the company/person who made it) and an extension name e.g. helhum/typo3-console or typo3/cms-form.

For the time being there is a workaround for extension which are not on packagist by using the vendor name: „typo3-ter/a-typo3-ter-extension-that-is-not-on-packagist“. You must replace underscores through dashes: „tx_something“ is referred to by „tx-something“.

And you must add the Repository: „https://composer.typo3.org“ to your composer.json, so composer knows where to search for these extensions.

More information is here:
https://docs.typo3.org/typo3cms/InstallationGuide/MigrateToComposer/MigrationSteps.html

Since TYPO3 8.7.10 you can use a concept, called „subtree split“. It will be mandatory for TYPO3 9. The concept means, you will not copy the full TYPO3 core package, including all system extensions, you will never use. But only install what you really want. You will not be able to install typo3/cms:^9, but have to name each system extension.

https://docs.typo3.org/

The new ways

Now, since we miss some files and folders, we could do:

composer create-project typo3/cms-base-distribution CmsBaseDistribution ^9

And we would get a complete installation in a new folder called „CmsBaseDistribution“.

But the recommended way is to setup your own composer.json and travel with it from installation to installation. You only have to make sure, that it is directly in your web directory.

Here we go for our own composer.json: step-by-step

{
    "name": "zazuberlin/start2019",
    "type": "project",
    "description": "This is the general TYPO3 page setup from 2019. It includes zazusitepackage.",
    "authors": [
        {
            "name": "Thomas Hezel",
            "role": "Developer",
            "email": "film@inter.net"
        }
    ],
    "license": "GPL-2.0-or-later",
    "config": {
		"platform": {
			"php": "7.2"
		}
	},
    "repositories": [
        {
            "type": "vcs",
            "url": "https://thomas-hezel@bitbucket.org/thomas-hezel/zazupackage.git"
        },
        {
            "type": "composer",
            "url": "https://composer.typo3.org/"
        }
    ],
    "require": {
        "helhum/typo3-console": "^5.5.5",
        "typo3/minimal": "^9.5",
        "typo3/cms-adminpanel": "^9.5",
        "typo3/cms-belog": "^9.5",
        "typo3/cms-beuser": "^9.5",
        "typo3/cms-felogin": "^9.5",
        "typo3/cms-filemetadata": "^9.5",
        "typo3/cms-fluid-styled-content": "^9.5.5",
        "typo3/cms-form": "^9.5",
        "typo3/cms-impexp": "^9.5",
        "typo3/cms-info": "^9.5",
        "typo3/cms-linkvalidator": "^9.5",
        "typo3/cms-lowlevel": "^9.5",
        "typo3/cms-opendocs": "^9.5",
        "typo3/cms-redirects": "^9.5",
        "typo3/cms-reports": "^9.5",
        "typo3/cms-rte-ckeditor": "^9.5",
        "typo3/cms-scheduler": "^9.5",
        "typo3/cms-seo": "^9.5",
        "typo3/cms-setup": "^9.5",
        "typo3/cms-sys-note": "^9.5",
        "typo3/cms-tstemplate": "^9.5",
		"typo3/cms-t3editor": "^9.5",
        "typo3/cms-recycler": "^9.5",
        "zazuberlin/zazupackage": "dev-master"
    },
    "scripts":{
		"typo3-cms-scripts": [
			"typo3cms install:fixfolderstructure",
			"typo3cms install:generatepackagestates"
		],
		"post-autoload-dump": [
			"@typo3-cms-scripts"
		]
	}
}
  • name: any name for this setup in the syntax „vendor/name“. If it is an extension it would be „vendor/extension-name“ and used to refer to it!
  • type: here it is a „project“ – our TYPO3-Project, if it is the composer.json for an extension then it would be „typo3-cms-extension“
  • description: this is for the pure humans
  • author, role, email: you can do
  • licence: usually GPL
  • config.platform: TYPO3 9.x expects PHP 9.2 at least – this has some tricky background see below
  • repositories: add https://composer.typo3.org to make sure that all extensions are loaded even if they are not on packagist – and you can add your personal extensions e.g. sitepackage
  • require: this is the command „composer require …“ this is where it’s happening – get the stuff you need!
  • scripts: they create the missing files and folders (fileadmin …)

name

The syntax is vendor/name so for an extension this should be consistent. For a project the name is not essential, since this is the starting point and from here you refer downwards to the extensions with their vendor/name marker.

type

Remember every extension has it’s own dependencies and it’s own composer.json file. So from a project type you go downwards.

config.platform

Composer can only use the PHP version that you are executing it with. So if you run it on the command-line, it doesn’t know anything about the PHP version that is in the web context. If you install dependencies using a different PHP version than the one that serves your application, you can tell Composer about that version explicitly using the platform config. But you still need to make sure that the PHP version used to install dependencies is compatible with any scripts that are executed afters (or run install with the --no-scripts option).

notifications@github.com Christian Flothmann

My test showed, that using the platform.config setting it is still creating an error when the command-line php version is lower then the expected php-version of the server. I didn’t test yet, what happens if you skip platform.config.

repositories

"repositories": [
        {
            "type": "vcs",
            "url": "https://thomas-hezel@bitbucket.org/thomas-hezel/zazupackage.git"
        },

This refers to my sitepackage extension on bitbucket – called „zazupackage“ – using the version-control-type „vcs“.
In the require-section you then need to tell composer which level (stable, dev …) you want and witch branch of your version control.
dev-master: take always the newest version of my master branch.

You can also refer to a specific folder on your server, for composer to find your personal extension:

It’s not necessary to move your project’s site package to a dedicated Git repository to re-include it in your project. You can keep the files in your main project (e.g. public/typo3conf/ext/my_sitepackage). There is only one thing to do; Because TYPO3’s autoload feature works differently in Composer based installations, you have to register your PHP class names in Composer. This is very easy when you use PHP namespaces:
„autoload“: { „psr-4“: { „VendorName\\MySitepackage\\“: „public/typo3conf/ext/my_sitepackage/Classes/“, „VendorName\\AnyOtherExtension\\“: „public/typo3conf/ext/any_other_extension/Classes/“ } }

https://docs.typo3.org/typo3cms/InstallationGuide/MigrateToComposer/MigrationSteps.html

require

composer require typo3/cms-adminpanel:^9.5.0

This command will add the corresponding line to your composer.json and you will avoid to make typos. You see above, that we started with typo3/minimal and then added what we need. In my case almost everything what was always there. I didn’t dig into every sysextension yet, so I just take the whole lot (no „subtree split“ yet).

^ = this sign means, stay in the area of 9.x don’t got to 10.0.0.0 but take the highest 9.x. Composer works with 4 version segments x.x.x.x

After the composer install command

There is still no Localconfiguration.php and no established database connection. Calling the public folder with a browser will guide you through the rest of the installation process. You have to create a FIRST_INSTALL and put it in the server root (folder „public“).
You should also check whether all web folders have the rights needed and the respective owners of the server process, otherwise you will get a nice white clean page with nothing on it.

Create a page and a template record. Don’t forget to include the static templates of the extensions, including the sitepackage.

Extensions are now managed by composer.
Autoload has to be reseted by composer.

composer.json for your full TYPO3 extension or just a sitpackage

"name": "zazuberlin/zazupackage",
    "type": "typo3-cms-extension",
    "description": "Sitepackage from zazu.berlin, based on fluid even for menus.",
    "homepage": "http://zazu.berlin",
    "license": "GPL-2.0-or-later",
    "authors": [
        {
            "name": "Thomas Hezel",
            "role": "Developer",
            "email": "film@inter.net"
        }
    ],
    "keywords": [
      "TYPO3 CMS",
      "zazu-berlin",
      "sitepackage",
      "fluid",
      "menu processor"
    ],
    "version": "1.0.0",
    "repositories": [
        {
            "type": "composer",
            "url": "https://composer.typo3.org/"
        }
    ],
    "require": {
        "typo3/minimal": "^9.5",
        "typo3/cms-fluid-styled-content": "^9.5.5",
         "typo3/cms-rte-ckeditor": "^9.5",
         "reelworx/rx-shariff": "^12.0"
    },
    "autoload": {
        "psr-4": {
            "Zazuberlin\\Zazupackage\\": "pubic/typo3conf/ext/zazupackage/Classes/"
        }
    }
}

In my case I rely for my sitepackage extension on „typo3/minimal“ and e.g. „reelworx/rx-shariff“. You see that the rx_shariff version for TYPO3 is already on the packagist repositroy with the vendor name „reelworx“. „autoload.psr-4“ is what we did in old times, when we added an extension in the backend after loading it from the ter.

Bye, bye Backend Extensions Control

In the TYPO3 Backend you will see a warning, that the extension manager is no more the place to manage extensions. Everything has to be done by „composer require typo3/cms-xxxxxxx:^9.5.0“ and „composer update“. Also the „dump-autoload“ command is now in the hands of composer (composer dump-autoload) and no more executed by the admin tools.

TYPO3 6.2 was still delivered with a couple of different autoloaders, that all had different approaches and rules to find a class. This led to the naming conventions in and outside Extbase and the optional ext_autoload.php file to load classes that didn’t follow the conventions. Since TYPO3 7.0 all this is gone and there is only a single autoloader left, the one of composer. No matter if you run TYPO3 in composer mode or not, TYPO3 uses the composer autoloader to resolve all class file locations.

https://docs.typo3.org/typo3cms/CoreApiReference/latest/ApiOverview/Autoloading/Index.html#autoloading-classes-since-typo3-7-x

A final word

I hope this will help me, not to forget and someone out there to find light in the jungle. Most of the time I find other people rather nice but frameworks grabbing control and let me search for bugs for hours. Not to mention the hours spend to understand the whole sh…

Dieser Artikel ist in Englisch, nicht um Ihnen das Leben schwer zu machen, sondern um den Autoren weltweit etwas zurückzugeben, die mir auch tagtäglich mit ihren Artikeln helfen!

zazu.berlin

Author: Thomas Hezel

4 Kommentare

  1. IM IM

    Thx for this very detailed and not so positive roundup about T3 composer install.
    Do you have any info if important security issues in extensions are displayed (in red) in the extension manager at all (like in non-composer mode)?

    • Hello IM,
      this is a good question. I just checked my composer sites: The update drop-down-menu to update the list of all available extensions is gone. You have to do your own research now. You can still deactivate an extension in the extension-manager, this will delete the entry in PackagesStates.php (tried it and it worked). You still see the version and the status (stable etc.). But that’s it. If there are breaking changes e.g. you have to change the templates („powermail“ is changing templates all the time and also Georg Ringer with „news“ likes his breaking changes), is now in your hands to check the respective website of the extension or the manual on bitbucket or github. But to update TYPO3 realy gets easy. But now I ask myself what is now the additional service for special TYPO3-hosters like Mittwald? Thomas

  2. IM IM

    Yes I also checked and intentionally installed an extensionversion with know security issues (vhs (4.3.0) ) via composer by altering the composer.json according, It just installed even that is not available for download on extensions.typo3.org, but on packagist it seems it was not pulled.
    After installing there was no indication in Extensionmanager (red exclamation) of a ‚bad‘ extension installed. So you now really have to do everything on your own, not only speaking of breaking changes but also check every ext for security-updates (yes they send mails, but…).

    https://extensions.typo3.org/extension/vhs/
    https://typo3.org/security/advisory/typo3-psa-2017-001/

    • Basically the composer.json of the respecitve extension should do the job of controlling what is possible and what not. Meaning, let you update/install only under certain conditions which then will work.

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert