Skip to main content

How to Install TYPO3 Using Composer (in Less Than 5 Minutes)

During the last TYPO3 User Experience Week (T3UXW) it became apparent that some participants weren't aware of the benefits of a composer-based TYPO3 installation. Today I would like to use the opportunity to demonstrate the setup of a new TYPO3 installation with only a couple of commands, easing the way to TYPO3 as much as possible.

Prerequisites

This guide assumes that you have access to the shell of your system and that you have installed composer.
If you have not installed composer yet, please click here and check how to install composer on your Operating System.

Compose your code

cd /path/to/your/htdocs/directory

Be aware that during the installation a subfolder called "web" will be created. Everything publicly accessible needs to be stored in that folder while confidential files, like configuration, must be stored outside of said "web" folder.
(Hint: If you want to change the name of the "web" folder, this is  very simple. I will get to that at a later point in this article.)

composer init

This starts the composer configuration generator. You will be asked a couple of informations, all of them could be edited later on.

  • Package name: A key to describe your project. E.g. "typo3inc/testcomposersetup".
  • Description: In this case I simply use: "This project is about to show how easy it is to create a composer based TYPO3 installation."
  • Author: The author name goes here.
  • Minimum Stability: Possible values are dev, alpha, beta, RC and stable.
  • Package Type: Project
  • License: Can be any type of string.
  • "Would you like to define your dependencies (require) interactively?": Yes
  • typo3/cms (as version constraint you could either enter "8" to stay on the LTS version or leave the field blank to always get the newest sprint release)
  • "Would you like to define your dev dependencies (require-dev) interactively?": No
  • "Do you confirm generation?": Yes

Now inspect the content of the directory, you'll find a file named composer.json.
Remember, I told you that it is possible to change the web folder name? Here is how it is done.
Add the following part to your composer.json file:

"extra": {
       "typo3/cms": {
           "web-dir": "web/public"
       }
}

The option “web-dir” allows us to define another path/name for the web folder, in this example the web folder name is changed to “web/public”. If you are on a case sensitive system, be sure to stick with upper and lower casing as you define here. 

Now let composer do its magic.

composer install

Depending on your coffee maker and your internet connection you might be able to go grab a quick cup of joe, but be quick about it, because even with cold caches it should not take longer than 2 minutes.
Now open your install tool in the browser and there you are. (Remember, the folder with your installation is the web folder. Configure your web server accordingly.)

More automation

I think we have about two minutes left so let's prepare the database connection.

composer require helhum/dotenv-connector

This composer package provides an easy way to store configuration outside of your web root.
Create a file called ".env" in the parent of your web folder and enter (and complete) the following lines:

TYPO3_INSTALL_DB_DRIVER=<your custom driver>
TYPO3_INSTALL_DB_HOST=<your host e.g. localhost>
TYPO3_INSTALL_DB_USER=<your db user for this project>
TYPO3_INSTALL_DB_PASSWORD=<the users password>
TYPO3_INSTALL_DB_PORT=<your custom port or omit this setting>
TYPO3_INSTALL_DB_DBNAME=<the db of your project>
TYPO3_INSTALL_DB_UNIX_SOCKET=<your custom socket or omit this setting>

When you go back to the install tool, most of the database configuration is already done.

Conclusion

Not only did we prepare a TYPO3 installation in less than 5 minutes, you also should have caught a glimpse of what would happen if you create the composer.json and a customized .env file to provision a hundred TYPO3 installations at once.

You'll find answers to other frequently asked technical questions, instructional clips and all sorts of helpful videos on our TYPO3 YouTube channel. Come along and join us there. If you find this useful, please share the link on your network.

Comments

as for the question of the version to give for 'composer require typo3/cms':

- Leaving the version blank will always give you the latest stable version. At the time of this writing this would be 8.7.6, and would end up in composer.json as ^8.7.

- Providing a major version will give you the latest stable version of this branch, and also make for ^8.7.

- Providing a minimum version like ^8.7 (as Peter mentioned) will of course give you that as well, but it is not necessary.

Conclusion: Providing a major version is completely fine and sufficient for retrieving a dependency. It will also kept to the latest version as long as there will be some released. You must not worry on your own, and also you must not know what the current minor version of your required software is. Composer knows, that should fit the bill just fine.

I removed the spaces around the equal signs in the .env example. You guys are of course right, those must not be in the file.

We apologize for this error.

I just wanted to mention that the example for the .env file still contains spaces around the equal signs.

Thank you very much. I'm just trying the .env file. To make it work I needed to remove the whitspace around the "equals" (=) sign. Otherwise PHP-FPM complained in the Apache2 errorlog: [:error] [pid 9392] [client 10.0.2.2:48153] FastCGI: server "/usr/lib/cgi-bin/php7-fcgi-t3dev8" stderr: PHP message: PHP Fatal error: Uncaught Symfony\\Component\\Dotenv\\Exception\\FormatException: Whitespace are not supported after the variable name in "/home/marble/htdocs/t3dev8/.env" at line 1.

Version constraint should be ^8.7 to stick with the current TYPO3 8.7 LTS release and not 8, correct?

Please add this information also to https://composer.typo3.org

Actually people were aware of the benefits, but not of the drawbacks due to an important missing piece of information. Since I was one of the people, who lost hours of time trying to fix development machines of participants based on composer, and you were one of the people who had to bear my outburst, I would like to say thank you for this article. It is the very first time that the "web" folder is explicitely mentioned, which is created silently under the hood during "composer install".

While this does not change anything with a fresh install into an empty root directory, it is an unexpected and for most of the User Experience Week participants even undetected breaking change, when this folder is created within an existing and working installation just by executing "composer install".

So people should be aware of the fact that this folder adds one path level to the whole "typo3conf" section, which will be changed to "web/typo3conf", while leaving the existing "typo3conf" folder as is. In case you upload changes to that former "typo3conf" directory i.e. via PHPstorm synchronization, nothing will happen. When you find that unexpected "web" folder on your machine later on and remove it, because it looks suspicious to you, the machine will be broken.

So that particular information about the "web" folder and why and how it is created would be one of the essential things to tell people, who got problems with TYPO3 machines in composer mode.

So I would like to see at least links to this article from a more prominent position than this blog.

Thanks again and keep up the good work :-)

Write comment

* These fields are required