Setting the Environment Name in Laravel

📁 laravel

One of the most important things for you to consider when planning the deployment of your application into production is how to handle detecting the “environment.”

The environment name is a string identifier that is unique for each deployment environment. Typically, descriptive names such as “production,” “local,” “staging,” and “testing” are used, although you can define these to be what ever is convenient.

In Laravel, we can use the helper App::environment() to return the current environment name. You can see this by echoing out the value of this function using the Artisan tinker command:

$ ./artisan tinker
>echo App::environment();

Defining the Environment Name

So how exactly does Laravel determine which environment the application is currently executing in? This is actually customisable, and there are a couple of different ways of handling environment definition. Which option is best for you will be determined by your deployment method and personal preference.

Defining the Environment name by Hostname

The documented approach for determining the environment involves mapping hostnames to environment names. You can see this approach in the following file:

You can see in the code that we simply need to provide a mapping of ‘environment-name’ => ‘array of hostnames.’

This is a good way to define the environment if you have a small number of servers, and the hostnames of the servers are predictable. Although if you need to test multiple environment settings on the same server (i.e.: you need to change the environment name on a single server) this is not a good approach.

Defining the Environment name via a File

Another way to do this is to use a server-specific config file to define the environment. To do this, we create the file ‘bootstrap/environment.php‘ which simply returns the environment name. We then reference this file in ‘bootstrap/start.php‘ as follows:

Note that this file is typically omitted from the project repository, so it needs to be manually created or created during one of the deploy steps.

The key benefit of this approach is that it forces you to provide an environment setting. If you don’t create the file on the server, the application will fail to load when it tries to open the file. If you don’t have an automated deploy, this is probably a bad way for you to manage the environment.

Defining the Environment name using… the Environment!

Finally, we can also define the environment name using an environment variable.

This is the preferred approach, as it shifts configuration out of the codebase and into the execution environment, which many argue is the correct place for it to reside.


There are a few different approaches for setting the environment name within a Laravel application, and which is best depends on the deployment strategy of the project and personal preference. As a general rule of thumb, the best approach is to set the environment name via an environment variable.