While working with a team and with different environments like local, staging and production, there are different settings for each machine. For that we have .env and .env example files. How to use them effectively?

First, the theory – what is .env and .env.example?

From the version Laravel 5.0 in your main folder you should have .env file which contains various settings, one row – one KEY=VALUE pair. And then, within your Laravel project code you can get those environment variables with function env(‘KEY’).

The rule is that .env file is not committed to the repository, so it is really convenient, cause then people on your team can change their variables locally without committing them to the repository.

Now, .env.example file, on the contrary, is included in the repository – it is used as an example file for you to know what KEY=VALUE pairs you need for your project. Most often it is used to copy it to .env file and then change the values.

You can also read about it in the official Laravel documentation.


Laravel 5 default .env.example

As it stands now for Laravel 5.3, current .env.example which comes from Laravel project looks like this:

APP_ENV=local
APP_KEY=
APP_DEBUG=true
APP_LOG_LEVEL=debug
APP_URL=http://localhost

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=homestead
DB_USERNAME=homestead
DB_PASSWORD=secret

BROADCAST_DRIVER=log
CACHE_DRIVER=file
SESSION_DRIVER=file
QUEUE_DRIVER=sync

REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379

MAIL_DRIVER=smtp
MAIL_HOST=mailtrap.io
MAIL_PORT=2525
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_ENCRYPTION=null

PUSHER_APP_ID=
PUSHER_KEY=
PUSHER_SECRET=

As you can see, quite a lot of those values are empty. And, to be honest, by default you will actually need to change only a few of them – related to database connection:

DB_HOST=127.0.0.1
DB_DATABASE=homestead
DB_USERNAME=homestead
DB_PASSWORD=secret

Then, in my practice, it’s quite important to have MAIL settings but for that you will quite often use external tool like Mandrill – in that case you will add its own value, something like:

MANDRILL_KEY=xxxxxxxxxxxxxxxxxxxxxx

To be honest, some of those variables in Laravel are quite opinionated – for example, PUSHER – I would dare to say that 95% of Laravel projects won’t need that, so I wouldn’t include it into a default .env.example. But that’s only a personal opinion.


Don’t forget .env.example

Golden rule: if you add some variable into your .env file, it also has to be present in .env.example – copy the key there with empty value. Then other people on your team would pull down that file and will know that they need that variable for project to run.

Latest example of not following this rule was when I was testing some Laravel products for reviews and one of them was Attendize – ticket selling system based on Laravel. After installing it, I’ve got an error:

RuntimeException in DingoServiceProvier.php line 82:
Unable to boot ApiServiceProvider, configure an API domain or prefix

Weird one, I thought. And only after some googling, I’ve found out that I needed to add one line to .env file:

API_PREFIX=api

And that line wasn’t in .env.example file. Although I didn’t even really use the API, without that line the whole app didn’t even load. An expensive mistake.


In short, .env files are a really convenient way to set your environment variables (and in our QuickAdmin we also generate an example .env for you), but don’t forget to use .env.example – especially when working in a team.