No description, website, or topics provided.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
.gitignore
.gitignore.dist
README.md
build.dist.ini
build.xml
composer.json

README.md

Setting up Typo3 using composer

Back in the days, setting up Typo3 was a PITA. Luckily, we now have composer. The Typo3 community worked hard to support the idea of packages and dependency management, so at the moment of writing it is actually very easy to setup Typo3 by just cloning a git repository, adjusting the database credentials and running a build tool like phing.

Step 1 - clone the repository

Well ok, I guess that's actually clear, however I wanted to note it :-)

Step 2 - composer update

Within the project root directory, run

composer update

Typo3 consists of a lot of files. Really, a lot. If composer times out during the install process, try to increase the timeout:

export COMPOSER_PROCESS_TIMEOUT=1200 ; composer update

Step 3 - adjust database credentials

Typo3 requires a MySQL database by default, so we have to put the credentials somewhere. In this example we use an .ini file. This file is not part of the repository, so you have to create it yourself.

I've added an example, so simply run

cp build.dist.ini build.ini

and edit the credentials accordingly.

Please note that the database WILL BE DROPPED during the install process, if it exists. So it doesn't need to exist, but make sure that the configured MySQL user can create it.

Step 4 - bin/phing

I chose phing as build tool. Since it is a PHP application and it's available via packagist.org, we already have it installed now during the "composer update" and are ready to start without any more configuration work.

bin/phing

Lean back. Everything should run automatically now.

Step 5 - enjoy

Let's open the newly created Typo3 instance. In this example, Typo3 will not be installed in the project root (see below for more information), but in the /web folder. So assuming your local host is accessible via localhost, open

http://localhost/project_folder/web

You should see the Typo3 dummy site now. If not, restart with Step 1.

Obviously you can access the backend via

http://localhost/project_folder/web/typo3

The default admin user in this example is

Username: admin
Password: typo3test

Last thoughts

As you can see, the actual repository only consists of some configuration files. All dependencies are downloaded automatically, which makes the handling very easy.

However it can get difficult once you want to add your own extensions. If you are using the composer based setup, you should keep your extensions is separate repositories and track them with the composer.json, otherwise you will end up with a somewhat fragile .gitignore file.

Explaining the configuration files

Of course this example is very simple. Surely you want to configure it, so let me explain the files involved below.

composer.json

{
	"name": "carstenwindler/typo3-composer-setup-example",
	"description" : "Typo3 Composer setup example",
	"repositories": [
		{ "type": "composer", "url": "https://composer.typo3.org/" }
	],
	"license": "GPL-2.0+",
	"require": {
		"typo3/cms": "^7.6",
		"helhum/typo3-console": "dev-master",
		"phing/phing": "*"
	},
	"config": {
		"bin-dir": "bin"
	},
	"extra": {
		"typo3/cms": {
			"cms-package-dir": "{$vendor-dir}/typo3/cms",
			"web-dir": "web"
		},
		"branch-alias": {
			"dev-master": "1.0.x-dev"
		}
	}
}

There are a few things worth pointing out here:

  • composer.typo3.org must be added as repository
  • extra.typo3cms controls where Typo3 gets actually installed. "web-dir" is set to "web", so after installation, your Ready-to-go Typo3 dummy setup will be in "/path/to/project/root/web"
  • "helhum/typo3-console" is a very useful Typo3 extension which provides a neat Typo3 console and, most important for us, allows us to run Typo3 Install Tool via command line
  • "phing/phing" will be our build tool, so just add it right away

build.ini

The parameters itself should be self explanatory. These parameters are required by the Typo3 Install Tool, and since we run it "headless" only on the command line, we have to provide it here. Have a look at the build.dist.ini too!

This is what the build tool actually generates from it:

php /path/to/typo3cms install:setup
	--non-interactive
	--database-user-name=db_user_name
	--database-user-password=db_password
	--database-host-name=db_host
	--database-name=db_name
	--admin-user-name=admin
	--admin-password=your_admin_password
	--site-name=Site name

Note: admin-* and site-name are hard coded in this example. See the build.xml below for more information.

The file "typo3cms" is generated by the typo3_console extension during the composer update. It will make live a bit easier, since the original Typo3 console is a bit clumsy to use.

build.xml

phing is based on ant, a Java build tool by Apache. So the syntax of the build file is very similar, but phing comes with some great PHP specific features and does not require Java.

Running it without any build file specified, phing expects a build.xml in the project root directory. It consists of several so called "targets", which could be translated as "build tasks" or so.

Within the build.xml you can specify a default target which is run when no target is specified. In this example, it is the "build" target. The build target itself actually only displays the "done" message, but it depends on two other targets: "update" and "setup-typo3".

cleanup

Before we start, let's cleanup some created directories. This obviously only makes sense if you run the build at least a second time. Since Typo3 does a lot of caching, it is important to remove the cache files before running the build again. For example, when you don't clear the cache and then remove an extension from the PackageStates.php, Typo3 will throw an error.

It might also be obvious to you, but: if you are not using the file cache but any other cache like Memcache, you have to make sure the cache is cleared BY YOURSELF. This is not covered by this build script.

One more note: we just remove the whole web folder here. If your project gets more complex this if of course not the best strategy. Have a look at the .gitignore section below for more thoughts on that.

composer related instructions

The "update" target takes care of the composer part.

composer.lock - version control or not?

Usually I version control my composer.lock files. In this case I didn't, because the example should use a recent Typo3 7 version. Let's see how that works out in the future.

Btw, I didn't switch to Typo3 8 yet, since it requires PHP7 which - although being a great idea in general - is not so much distributed yet.

Typo3 related instructions

The "setup-typo3" performs the actual setup. But "setup-typo3" depends on another target called "generate-package-states". If you don't know what that is, let me explain that a bit more in detail:

PackageStates.php

Typo3 requires a file called "PackageStates.php" which defines the activated Typo3 extensions. So far, so good. But where is this file coming from? You could actually version control it (and this is probably a good idea in ongoing Typo3 projects), but I decided to use the "typo3_console" to generate it.

But how do we define which extensions are activated? To do this, we need to set a variable on the command line (not sure why they chose this solution, but I'm sure they had a good reason):

TYPO3_ACTIVE_FRAMEWORK_EXTENSIONS='extension1,extension2,...'

Our example just activates some common System extension (those already shipped with Typo3). If you want to add 3rd party extension, be sure to add them in you composer.json too!

But back to the build.xml. So once the PackageStates.php is generated, we want to drop the specified database, since Typo3 Install Tool will create it for us.

Now we are prepared to run the Install Tool on command line. This should pass without problems, if problems occur make sure the file permissions are set to "writable" and the MySQL DB can be created.

Finally we run use the "typo3_console" fixfolderstructure command to check if the folder structure is ok. Usually this generates a couple of directories and files, also adjusts the file permissions. Very useful tool!

.gitignore

Lastly, let's look at the .gitignore. It's not really needed to setup Typo3, however it makes sense to have it if you want to build up your own composer based Typo3 project.

The directories /bin, /vendor and /web will be created by composer, so we don't want them to be part of this repository at the moment. Later on you want to define some exceptions, at least within the /web folder (e.g. /web/fileadmin). Have a look at the .gitignore.dist file for a more detailed gitignore example. Naturally it won't fit all needs, but it might help as starting point.