Laravel 4: Setting Up and Utilizing Environments and Environment Configuration

Have you ever developed your application locally, then taken it live on your production server and had to manually change your app configuration (say, your database credentials) to match the production server? If you have, then continue reading and learn how configuring environments in Laravel can save you from this headache.

Environments

Software projects are typically deployed in various environments. You likely develop your application locally in a development environment. You then have your live server where your site resides, known as the production environment. Many applications will have a staging environment, essentially a duplicate of your production environment, where apps are deployed and tested before being pushed to production. Larger applications may have other environments in between.

Each of these environments may require different configuration, and luckily we can easily handle that in Laravel.

Default Environment and Configuration

The default environment in Laravel is production; in other words, without making any of the aforementioned changes your app will be considered in ‘production’. Any files within the root of the app/config  folder will be considered the configuration for the production environment; that includes app/config/cache.php , app/config/app.php , app/config/database.php  and others.

Setting Environments

We can set different environments in Laravel and subsequently use different configuration. Open up the bootstrap/start.php  file in your Laravel application. Here you will see the following block of code:

This is where we define our environments within the application. Each key in this array is the name of an environment and the corresponding value is an array of URLs that will match this environment. Below is an example of an environment configuration I might use in an application:

In the example above, when I view my application on my localhost the environment will be set to local. When I deploy my application to my staging server set at staging.example.com, my application environment will be staging. These can be named whatever you like. For instance, I could use the following:

to name my development environment dev rather than local.

Loading Config Based on Environment

The real power of environments comes from being able to load different configuration based on the environment, and Laravel makes this dead simple.

For instance, say you have different database credentials for your local development environment. All you need to do is copy the app/config/database.php  config file to app/config/local/database.php . If your staging environment has a different set of database credentials from your local or production environments it can have it’s own configuration stored in app/config/staging/database.php .

The idea is that you use the environment key you defined in  bootstrap/start.php as the folder name, and then copy any configuration files you need to override into this folder and change the values accordingly.

In fact, you don’t even need to copy the entire configuration file, you can copy only the array keys within the configuration file that you need to override and these will be merged with the default values in the production configuration files!

Environments and Artisan

By default Artisan commands are run with the default production configuration; however, if you are developing locally and need to migrate a database this doesn’t help. What you can do is pass a flag with the Artisan command that will utilize the configuration for the environment you specify. For example, if you wanted to migrate your database in your production environment it might look like this:

If you wanted to seed your database in your staging environment if might look like:

Conclusion

Environments in Laravel are extremely powerful and allow you to configure your application for various stages of development and deployment. I hope you found this article helpful and if you have any comments, questions, or additions please include them in the comments below!

  • http://www.modomediagroup.com Chris Gmyr

    This is how I set up my Laravel apps, it’s very handy. I just wish there was a shortcut for –env=local in artisan. I guess it could be worse though.

    One thing – The “testing” environment is reserved for unit tests only, so you might want to update your post to not use it. See the “note” half way down on http://laravel.com/docs/configuration

    • simon davies

      You could create an alias for the shortening of the –env call

  • http://www.moderncognition.com crhayes

    @modomg:disqus Thank you for pointing that out! I’ll update the article accordingly.

  • Tournas Dimitrios

    And of course , don’t forget to block files with sensitive information from being transferred to your publicly accessible repository (gitHub , bitbucket) . It’s just one record into the “.gitignore” file .

  • vladoa

    Can I have a different .htaccess file based on the current environment?
    If yes, how can I do that? Create a folder app/local/public/.htaccess ?

    • Nathan

      You can create different .htaccess files and then add them to .gitignore so they don’t get modified.

  • Riz

    Great little article, put my mind right about environment setup with L4, nice one!

    • http://www.moderncognition.com crhayes

      Thank you Riz!

  • Micheal Mand

    I don’t know if this was a fluke or something undocumented, so further testing may be required.

    I was able to get around having to specify the environment used by Artisan by adding my machine’s name to the environement’s array. For example my local environment:

    ‘local’ => array(‘localhost’, ‘dev-machine’),

    • http://www.moderncognition.com crhayes

      Thanks for the tip. This works excellently.

  • Steve Robillard

    Just wanted to point out one restriction when naming environments. You can’t use “testing” as that is predefined and used by Laravel itself.

  • Wazio Dionel

    I’m trying to change the path of $app = require_once __DIR__.’/../bootstrap/start.php’; at public/index.php

    Is there a way to change the path based on the environment ?

    • http://www.moderncognition.com crhayes

      Laravel does not provide a way to achieve this. The environment is detected in bootstrap/start.php (lines 27-31).

      What are you trying to achieve?

  • anD

    thank you

  • StageCoachDriver

    Yes!

    The only problem I have with Laravel is: So many options, so little documented and explained.

    • http://www.moderncognition.com crhayes

      In general I’ve found the documentation describes the simplest/most straightforward use cases. I would suggest digging through the source code as you continue to learn the framework, as it’s really the best way to learn how to bend Laravel to your will.

  • StageCoachDriver

    Just a hint if you’re on a PC, run something like “print_r(gethostname());” at the beginning of artisan.php to discover the true name of your server. Using localhost or 127.0.0.1 on a PC doesn’t usually produce the desired results.

  • Simon Franz

    Take care, if you’re staging and development machine are the same you have to do a trick. a Nice one is here to find: http://crynobone.com/posts/5/alternative-environment-detection-for-laravel-4
    just add a file on the environment and add it to the ignore list

  • Kuldip

    Use this method – http://stevegrunwell.com/blog/laravel-application-environment/

    It works fantastic

    –Kuldip

  • pc-shooter

    Thx for explaining it so well.

  • Max Joe

    Nice post ,above post help me lot to set environments for my application. I have also taken help from
    http://www.tutsway.com/how-to-set-up-environment-configuration-in-laravel.php