Code Smart: Configuration

Configuration is an important part of any application. We won't always want our application to have the same settings in every environment. If we decide to give our application to other users, they may wish to configure it for themselves. What if they are using a different database server to us?

Let's take a look at how Laravel will allow us to specify our configuration values.

Configuration Files

We'll start by taking a look at the config directory at the root of our project.


You'll find a bunch of PHP files. Many of them are named after the framework's components. These are the default configuration files that ship with a fresh installation of Laravel. Now pick a file. Any file. Pick your favourite, and open it in your editor.

What's inside? Why just normal PHP arrays! You see, Laravel uses PHP arrays for its configuration. The array keys represent the configuration name, and the values are, of course, our setting values. With Laravel, we can access these settings using the configuration facade or config() helper. Here's an example.

// Using a facade.
$debug = Config::get('app.debug', false);

// Using a helper function.
$debug = config('app.debug', false);

The signature to both techniques is identical. The first parameter is the name of the config key that we wish to retrieve. The configuration key is made up of the filename of the configuration file that we would like to check, followed by a period character, and then the array key of the setting using 'dot' notation. Here we're requesting the 'debug' array key from the 'app.php' file.

Don't forget to add use Config; to the top of your class if it's namespaced. You haven't forgotten the namespacing chapter already, have you?

The second parameter to both functions is the default value. Should a configuration value be missing, then we'll receive the default value instead.

T> In a later chapter, we will learn how to inject the configuration component into our classes to prevent having to rely on global functions or facades.

If you'd like to create your own configuration files, then simply drop them in the config directory. Laravel will load them automatically and will allow to you use them in the same way as its own configuration files. When writing applications for others, be sure to add as much configuration as possible. It's great when you can get an application to work your way.

Environmental Variables

While rooting around in the configuration files, you might have discovered a little function called env(). The env() function is the new way of making different configuration possible in different environments. For example, you won't want your development application to be using the same database as the live website!

Since the launch of version 5, Laravel no longer uses environment-based subfolders for configuration. Instead, it makes use of the 'DotEnv' library, to allow for configuration values to be loaded from environmental variables. Setting environmental variables in your shell can be a little cumbersome. For example, we wouldn't want to be doing this all the time.

export DB_HOST=""

Trust me; it's even uglier on windows. Environmental variables are the method of configuration that is preferred by system administrators since it's easy to script into newly provisioned web servers. However, if we are working with configuration values on a day to day basis, then we probably don't want to be exporting them each time.

Instead, we have access to a .env file in the root of our project. Let's take a look at that file.






The .env file is very simple. Keys on the left (usually in capitals) and values on the right. Here we see a bunch of default values that are provided by the framework. You can see our database, mail, and cache server settings. If we want our configuration values to be based on our environment, then it's best to add them to this file.

The env() function can be used in our PHP configuration files to retrieve values from our .env file. This makes our configuration layer a two-step process, but will allow us to use a different .env in multiple environments. The env() function will accept the same parameters as the config() function. Here's an example.

$host = env('DB_HOST', '')

Here we are requesting the host database setting, but providing a default value of localhost for when it isn't present in our .env file or environmental variables. It's worth noting that environmental variables will always take priority over values placed in the .env file.

People don't usually store their .env file under version control. Instead, they prefer that users provide their own configuration values. Still, it's useful to know what .env values are available, isn't it? To solve this problem, many application developers will version a file called .env.dist with their application, which will contain all of the available .env keys, and some universal configuration values. Anyone working on your application can then copy .env.dist to .env to start working on the project. Pretty handy, right?

So why not just use env() everywhere instead of config()?

Great question, and it shows that you're listening intently! If you wanted to, you could certainly stick to env(), however, this way you won't be able to make use of the caching functionality of Laravel's configuration layer. You see, Laravel can cache your configuration files to make the framework more performant. However, it can't cache values from environmental variables, so if you choose to use env() outside of the PHP configuration files then you might end up getting yourself in a caching mess. We don't want that, do we?

I guess not!

Great! Then the rule of thumb to use is that env() should only be seen in the config directory. That's not too difficult, is it?

T> If a third party package comes with its own configuration files, simply use php artisan vendor:publish to copy them into your configuration directory.

Configuration Caching

As mentioned in a previous section, Laravel can cache our configuration values to allow it to load much more quickly. This is a feature that's best used in a production environment.

To cache our configuration, first, we need to head to the root of our project (this is /vagrant in the homestead box) and run an Artisan CLI command.

php artisan config:cache

Our configuration will be cached, and the configuration files themselves will be bypassed. If we've added some new configuration and would like to clear our cache, we need only run the config:clear command.

php artisan config:clear

You're probably not going to need this functionality for your local development, and not while learning the framework, but it's good to know that it's there if we need it, isn't it?

In the next chapter, we'll start writing some code. Are you excited? Then flip the page to learn about routing!

My books are available online for free to encourage learning. However, if you'd like for me to keep writing, then please consider buying a digital copy over at

It's available in PDF, ePub, and Kindle format, and contains a bunch of extras that you won't find on the site. I have a full-time job, and I write my books in my spare time. Please consider buying a copy so that I can continue to write new and exciting books!