How to Configure TYPO3 Using .env Files

What is a .env file?

These days, a website typically has several “instances”:

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

The “deployment” cycle looks like this: Development takes place on the development server. Everything is then transferred to the beta server, where it is tested and reviewed by the client. If everything is in order, everything is transferred to the live server and goes online.

However, these different “instances” always require different configurations because they run in different environments—such as different databases, domains, email configurations, etc. If the entire project were copied from one “instance” to the next during the deployment cycle, the different configurations would have to be readjusted to the respective environment each time.

The idea behind the .env file is to offload all configuration settings that vary depending on the environment or “instance” into the .env file. Each “instance” or environment receives its own .env file with the corresponding settings, which is then overwritten during the deployment cycle.

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

Configuring TYPO3 with .env Files

Below you will find step-by-step instructions on how to configure TYPO3 with .env files.

Prerequisite: TYPO3 must have been installed with Composer, since the dotenv connector integrates with “composer autoload initialization time” to ensure that the environment variables are available as early as possible. 

1. Install the helhum/dotenv-connector extension

      composer require helhum/dotenv-connector 

2. Create a .env.example file with the following content. This file serves only 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. Create 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 your preferred text editor and fill in the information for your local development environment. For a TYPO3 DDEV installation, the .env file might look like this, for example:

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/ might 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 test to see if everything works.

8. Create additional .env files following the pattern above for the staging/beta server and the live/production server, and adjust the corresponding values in the .env file to match the respective environment. Then save the corresponding .env file on the respective server in the root directory, where the composer.json file is also located.

If you’re using a deployment system, make sure that the .env file is not overwritten. For example, if you use Deployer, you should save the .env file in the folder /shared/ and define it as “shared” in the deployer.php file:

set(‘shared_files’, [‘.env’]);

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

10. Make sure 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 information about .env here.