Laravel configuration allows you to define per-environment configuration with the excellent vlucas/phpdotenv package.
If you are new to Laravel, you might not yet know how you can create your configuration files in your projects and a few other helpful things that will help you master configuration. As always, the official documentation provides great information, and there are a few things we’ll cover here that I think will help people new to the Laravel framework.
How Does Configuration Work?
At a high level, configuration files are located in the
config/ folder of a Laravel project. The framework ships with various configuration files that make it easy for you to do things like pick which database driver you want to use and define external services.
For example, here is a partial view of the
config/services.php config file:return [
// ...
'mailgun' => [
'domain' => env('MAILGUN_DOMAIN'),
'secret' => env('MAILGUN_SECRET'),
],
// ...
Note the
env() calls that you can use to change values per-environment with the .env file or on the host system directly.
When you define an environment configuration on your machine, it takes precedence over the
.env file.
The
env() helper also allows you to specify a default value when the environment variable is missing on the system or the .env file. For example, the default connection in config/database.php is mysql when the DB_CONNECTIONenvironment variable is not defined:<?php
return [
'default' => env('DB_CONNECTION', 'mysql'),
// ...
];
All environment values from the
phpdotenv package come back as strings, but the env() helper in Laravel does extra work with environment variables. For example, the Laravel helper converts “false” the string to Boolean false, the keyword “empty” to an empty string, and “null” to a null value. You can check out the source of the Illuminate support helpers.php file for more details.Accessing the Configuration Service
The most common ways to access configuration in Laravel is through the Configuration service or the
config() helper.
Here’s how you use the config service:
$ php artisan tinker
>>> app('config')->get('services');
=> [
"mailgun" => [
"domain" => null,
"secret" => null,
],
"ses" => [
"key" => null,
"secret" => null,
"region" => "us-east-1",
],
"sparkpost" => [
"secret" => null,
],
"stripe" => [
"model" => "App\User",
"key" => null,
"secret" => null,
],
]
The
config() helper provides convenience, and you can still access the configuration repository service if you don’t pass any arguments:$ php artisan tinker
>>> config()
=> Illuminate\Config\Repository {#37}
>>> config()->get('services')
...
>>> config('services')
Working with Configuration
Configuration is defined in PHP arrays, and you can access those array values with a dot notation. The first part of the configuration key matches the name of the file. For example, the following is the
config/services.php file:$ php artisan tinker
>>> config('services.mailgun');
=> [
"domain" => "mg.example.com",
"secret" => "secret",
]
>>> config('services.mailgun.domain');
=> mg.example.com
Just like the
env() helper, the config helper allows you to specify a default value if the configuration key isn’t defined:$ php artisan tinker
>>> config('my.invalid.key', 'mg.example.com');
=> mg.example.com
You can also change/set configuration at runtime by passing the configuration helper an array:
>>> config(['example' => 'Hello World']);
=> null
>>> config('example');
=> "Hello World"
>>> config([
... 'view.paths' =>
... array_merge(config('view.paths'), ['my/other/path/'])
... ]);
Creating Your Own Configuration
You can create your own configuration files by adding them to the
config/ folder:$ touch config/api.php
You would then access the configuration values by prefixing “api”:
>>> config('api.base_url');
This is just an example, for services like APIs just use the
config/services.php file by adding new keys, for example, let’s say you are adding auth0 to services.php:<?php
return [
'auth0' => [
'secret' => env('AUTH0_CLIENT_SECRET')
],
];
Optimizing Configuration
When you deploy your application to production, you should optimize your configuration by running the following command:
$ php artisan config:cache
There are a couple of important points to make about this command:
- This command is not intended for development environments
- Make sure you are not calling
env()outside of configuration files
When you cache configuration, things like tests will use these cached values. For example, your database credentials will be cached and running tests with database interactions will drop your database tables.
When you cache your configuration, make sure your code is not calling the
env()helper. You should be using config() wherever you need to access configuration. The correct way to provide configuration to your application is using configuration files in tandem with environment variables with sensible default values.
You can clear the configuration cache with the following artisan command:
$ php artisan config:clear
