How to use .env files to configure TYPO3

What is an .env file?

Nowadays, there are usually several "instances" of a website:

1. A development server (usually local) on which development takes place.
2. A staging/beta server on which tests and reviews are carried out.
3. The live/production server, which is then publicly accessible and represents the actual website.

The "deployment" cycle then looks like this: Development takes place on the development server. Then everything is transferred to the beta server, where it is tested and reviewed by the customer. If everything is ok, it will be transferred to the live server and thus goes live.

However, these different "instances" always require a different configuration, as they run in different environments, e.g. different database, domain, mail configuration etc. If the entire configuration would be copied from one "instance" to the next in the deployment cycle, the different environment variables would have to be adapted to the respective environment each time.

The idea behind the .env file is, that all configuration settings, which differ depending on the environment/"instance", are stored in the .env file. Each "instance"/environment receives its own .env file with the associated settings, which is not overwritten in the deployment cycle.

A dotenv connector ensures that the environment variables from the .env file can be loaded into the programme and used as early as possible.

Configure TYPO3 with .env files

In the following you will find a step-by-step guide on how to configure TYPO3 with .env files.

Requirement: TYPO3 must have been installed with Composer, because the dotenv-connector integrates itself at the "composer autoload initialisation time", so that the environment variables are available as early as possible.

1. Install the extension helhum/dotenv-connector

 composer require helhum/dotenv-connector 

2. Create an .env.example file with the following content. This file only serves as a template for the other .env files.

TYPO3_CONTEXT=
INSTANCE=

# Site
SITE_BASE=

# System
TYPO3_TRUSTED_HOST_PATTERN=
TYPO3_DISPLAY_ERRORS=

# Database Credentials
TYPO3__DB__Connections__Default__dbname=
TYPO3__DB__Connections__Default__host=
TYPO3__DB__Connections__Default__password=
TYPO3__DB__Connections__Default__port=
TYPO3__DB__Connections__Default__user=

# Graphics
TYPO3_GFX_PROCESSOR=
TYPO3_GFX_PROCESSOR_PATH=
TYPO3_GFX_PROCESSOR_PATH_LZW=

# Mail
TYPO3_MAIL_TRANSPORT=
TYPO3_MAIL_TRANSPORT_SMTP_SERVER=
TYPO3_MAIL_TRANSPORT_SMTP_USERNAME=
TYPO3_MAIL_TRANSPORT_SMTP_PASSWORD=
TYPO3_MAIL_DEFAULTMAILFROMADDRESS=

3. Make a copy of the .env.example file and rename it to .env . The .env file must be saved in the root directory where the composer.json file is located!

4. Open the .env file in the editor of your choice and fill in the data for your local development environment. For a DDEV installation of TYPO3, the .env file could look like this:

TYPO3_CONTEXT='Development'
INSTANCE='local'

# Site
SITE_BASE='https://myproject.ddev.site/'

# System
TYPO3_TRUSTED_HOST_PATTERN='.*.*'
TYPO3_DISPLAY_ERRORS='1'

# Database Credentials
TYPO3__DB__Connections__Default__dbname='db'
TYPO3__DB__Connections__Default__host='ddev-myproject-db'
TYPO3__DB__Connections__Default__password='db'
TYPO3__DB__Connections__Default__port='3306'
TYPO3__DB__Connections__Default__user='db'

# Graphics
TYPO3_GFX_PROCESSOR='ImageMagick'
TYPO3_GFX_PROCESSOR_PATH='/usr/bin/'
TYPO3_GFX_PROCESSOR_PATH_LZW='/usr/bin/'

# Mail
TYPO3_MAIL_TRANSPORT='smtp'
TYPO3_MAIL_TRANSPORT_SMTP_SERVER='localhost:1025'
TYPO3_MAIL_TRANSPORT_SMTP_USERNAME=''
TYPO3_MAIL_TRANSPORT_SMTP_PASSWORD=''
TYPO3_MAIL_DEFAULTMAILFROMADDRESS='no-reply@myproject.ddev.site'

5. Open the file public/typo3conf/AdditionalConfiguration.php in the editor of your choice and replace all variable values with getenv('.env-Variable'). The result should look something like this:

<?php

$GLOBALS['TYPO3_CONF_VARS'] = array_replace_recursive(
    $GLOBALS['TYPO3_CONF_VARS'],
    [
        'DB' => [
            'Connections' => [
                'Default' => [
                    'dbname' => getenv('TYPO3__DB__Connections__Default__dbname'),
                    'host' => getenv('TYPO3__DB__Connections__Default__host'),
                    'password' => getenv('TYPO3__DB__Connections__Default__password'),
                    'port' => getenv('TYPO3__DB__Connections__Default__port'),
                    'user' => getenv('TYPO3__DB__Connections__Default__user'),
                    'driver' => 'mysqli',
                ],
            ],
        ],
        'GFX' => [
            'processor' => getenv('TYPO3_GFX_PROCESSOR'),
            'processor_path' => getenv('TYPO3_GFX_PROCESSOR_PATH'),
            'processor_path_lzw' => getenv('TYPO3_GFX_PROCESSOR_PATH_LZW'),
        ],
        'MAIL' => [
            'transport' => getenv('TYPO3_MAIL_TRANSPORT'),
            'transport_smtp_server' => getenv('TYPO3_MAIL_TRANSPORT_SMTP_SERVER'),
            'transport_smtp_username' => getenv('TYPO3_MAIL_TRANSPORT_SMTP_USERNAME'),
            'transport_smtp_password' => getenv('TYPO3_MAIL_TRANSPORT_SMTP_PASSWORD'),
            'defaultMailFromAddress' => getenv('TYPO3_MAIL_DEFAULTMAILFROMADDRESS'),
        ],
        'SYS' => [
            'trustedHostsPattern' => getenv('TYPO3_TRUSTED_HOST_PATTERN'),
            'devIPmask' => '*',
            'displayErrors' => getenv('TYPO3_DISPLAY_ERRORS'),
        ],
    ]
);

6. Open the file config/sites/main/config.yaml (/main/ could possibly have a different name if you specified a different name for the "Site Identifier" when creating the site configuration).
Change the value for "base" as follows:

base: '%env(SITE_BASE)%'

7. Restart TYPO3 and check wheter everything works fine.

8. Create another .env file according to the above pattern for the staging/beta server and the live/production server and adjust the corresponding values in the .env file to the respective environment. Then save the corresponding .env file on the respective server in the root directory, where the composer.json can also be found.

If you use a deployment system, make sure that the .env file is not overwritten. If you use Deployer for example, you should save the .env file in the /shared/ speichern und in der deployer.php Datei als "shared" folder and define it as "shared" in the deployer.php file::

set('shared_files', ['.env']);

9. Test whether TYPO3 also runs without errors on the beta and live servers.

10. Make sure that the .env files for the beta and live servers are not stored on GitHub! However, you can add the .env.example file and the .env file for the local development server to the Git repository.

You can find more info about .env here