Episode 10

TYPO3 and Composer — we've come a long way

Benni Mack
Benni Mack more

Composer is the go-to swiss-army-knife dependency manager for PHP. It will tell you if a particular PHP library is working with another library and if it conflicts, it will update them accordingly. It also ships with an optimized autoloader to load PHP files and classes when they are needed. TYPO3 has improved its support for Composer over the years, and now we’re excited to say that preparatory work done in v11 is paving the way for v12 to be a standard Composer project, delivering a much more secure CMS.

Why Composer?

There are a lot of benefits to using TYPO3 in Composer Mode (similar to most other PHP-based applications using Composer):

A Brief History

In the Early Days

Back in the early days (version 4.x), TYPO3 had a lot of "require_once" statements. In TYPO3 6.2.8 we migrated to the Composer Autoloader, bringing a considerable performance gain.

Since TYPO3 v6.2, it’s been possible to set up a CMS project with Composer CLI as a Composer-based project. We then distinguished between "Composer Mode" and "Classic Mode." Composer fetched all the packages needed, and TYPO3 still behaves in most places as if it was a simple PHP application like in 2003.

The Composer Journey

TYPO3 has improved its support for Composer over the years:

Stopgap Solution

When using Composer Mode, TYPO3's Core Extensions and Third-Party Extensions still had to reside in public/typo3/sysext/ and public/typo3conf/ext/ respectively. A Composer plugin called "typo3/cms-composer-installers" took care of this change during a "composer install" command.

People from the TYPO3 community built this plugin back in 2014 so that we could have Composer Support without having to rewrite TYPO3 from scratch. It has served us well, but we’re conscious that it was a misuse of Composer's way of dealing with dependencies—which usually reside in your PHP project's "vendor/" directory.

The New Feature

With TYPO3 v11, we've prepared the way for a huge milestone. All Core extensions and third-party extensions are now moved to the vendor/ directory (because they are actual Composer dependencies for your TYPO3-based website). 

We no longer not touch PHP classes needed for your TYPO3 project, and they are in a secure location outside of your public webroot.

We've done a lot of preparation in TYPO3 v11 LTS, and the actual feature is available in the upcoming version 4.0 of the typo3/cms-composer-installers Composer plugin.

Try it out now!

You can give it a try in your TYPO3 v11.5.4+ installation.

Step 1: Preparation

There is a bit of housekeeping you’ll need to do before you jump in: 

  1. Ensure you load all your project-specific extensions via a path repository , and require them properly via Composer. These extensions all need a composer.json file and must be referenced via composer req me/my-extension@dev in your Composer manifest.
  2. Check all your Fluid templates or TypoScript options to see if you still use "typo3conf/ext/". They need to be replaced with Fluid ViewHelpers and TYPO3's internal resource resolver.
  3. Make sure your Frontend Build pipeline is not depending on putting assets into typo3conf/ext/site_mysite/. We ran into this issue quite a bit with our Frontend Stack.
  4. Put the "public/_assets" folder in your .gitignore file.

If you don't want to spend time addressing these issues now, but you do want to continue updating TYPO3 v11 LTS versions, you can pin version 3 of our Composer plugin for TYPO3 v11.

composer req typo3/cms-composer-installers:^3

In the upcoming TYPO3 v12.0, the new plugin version will most likely become a requirement — so be sure to test your sites as soon as possible with TYPO3 v11. 

Step 2: Load the cms-composer-installers plugin

Use the following command:

composer require "typo3/cms-composer-installers:4.0.x@dev"

If your project is already running with Composer, you can remove public/typo3/ and public/typo3conf/ext/ right away and run the command above.

The final 4.0 version will be released some time in 2022, and will then be installed the next time you use "composer update" in your TYPO3 v11 project.

Result

The public folders of our TYPO3 installations now look like this:

*The two leftovers, "LocalConfiguration.php" and "AdditionalConfiguration.php", will hopefully find their way into a non-public location in the upcoming TYPO3 v12.

TYPO3 creates a new folder called public/_assets/, which symlinks all extensions' Resources/Public/ folders into this directory. TYPO3 v11 will resolve all the links for you when using a logo or CSS file from an extension. The names of the subfolders are auto-generated IDs, which should not matter to you when referencing files.

What you gain is a TYPO3 installation closer to a standard Composer project without hacks and—ultimately—a much more secure CMS.

TYPO3 and Composer - A Long Friendship

Thanks to Helmut Hummel. His TYPO3 Console project paved the way for many automation parts. Helmut, with the help of many other contributors,  spent hundreds of hours to get to this point. We've worked together over the past seven years to achieve this milestone for TYPO3.

If you still haven't gotten around to using TYPO3 with Composer, I can only recommend it. Contact us if you need help migrating your TYPO3 installation to Composer.

Let me know via Twitter or GitHub what you think of this change!

More Articles by Benni Mack