Introduction
All of the configuration files for the Laravel framework are stored in the app/config
directory. Each option in every file is documented, so feel free to look through the files and get familiar with the options available to you.
Sometimes you may need to access configuration values at run-time. You may do so using the Config
class:
Accessing A Configuration Value
Config::get('app.timezone');
You may also specify a default value to return if the configuration option does not exist:
$timezone = Config::get('app.timezone', 'UTC');
Setting A Configuration Value
Notice that "dot" style syntax may be used to access values in the various files. You may also set configuration values at run-time:
Config::set('database.default', 'sqlite');
Configuration values that are set at run-time are only set for the current request, and will not be carried over to subsequent requests.
Environment Configuration
It is often helpful to have different configuration values based on the environment the application is running in. For example, you may wish to use a different cache driver on your local development machine than on the production server. It is easy to accomplish this using environment based configuration.
Simply create a folder within the config
directory that matches your environment name, such as local
. Next, create the configuration files you wish to override and specify the options for that environment. For example, to override the cache driver for the local environment, you would create a cache.php
file in app/config/local
with the following content:
<?php
return array(
'driver' => 'file',
);
Note: Do not use 'testing' as an environment name. This is reserved for unit testing.
Notice that you do not have to specify every option that is in the base configuration file, but only the options you wish to override. The environment configuration files will "cascade" over the base files.
Next, we need to instruct the framework how to determine which environment it is running in. The default environment is always production
. However, you may setup other environments within the bootstrap/start.php
file at the root of your installation. In this file you will find an $app->detectEnvironment
call. The array passed to this method is used to determine the current environment. You may add other environments and machine names to the array as needed.
<?php
$env = $app->detectEnvironment(array(
'local' => array('your-machine-name'),
));
In this example, 'local' is the name of the environment and 'your-machine-name' is the hostname of your server. On Linux and Mac, you may determine your hostname using the hostname
terminal command.
If you need more flexible environment detection, you may pass a Closure
to the detectEnvironment
method, allowing you to implement environment detection however you wish:
$env = $app->detectEnvironment(function()
{
return $_SERVER['MY_LARAVEL_ENV'];
});
Accessing The Current Application Environment
You may access the current application environment via the environment
method:
$environment = App::environment();
You may also pass arguments to the environment
method to check if the environment matches a given value:
if (App::environment('local'))
{
// The environment is local
}
if (App::environment('local', 'staging'))
{
// The environment is either local OR staging...
}
Provider Configuration
When using environment configuration, you may want to "append" environment service providers to your primary app
configuration file. However, if you try this, you will notice the environment app
providers are overriding the providers in your primary app
configuration file. To force the providers to be appended, use the append_config
helper method in your environment app
configuration file:
'providers' => append_config(array(
'LocalOnlyServiceProvider',
))
Protecting Sensitive Configuration
For "real" applications, it is advisable to keep all of your sensitive configuration out of your configuration files. Things such as database passwords, Stripe API keys, and encryption keys should be kept out of your configuration files whenever possible. So, where should we place them? Thankfully, Laravel provides a very simple solution to protecting these types of configuration items using "dot" files.
First, configure your application to recognize your machine as being in the local
environment. Next, create a .env.local.php
file within the root of your project, which is usually the same directory that contains your composer.json
file. The .env.local.php
should return an array of key-value pairs, much like a typical Laravel configuration file:
<?php
return array(
'TEST_STRIPE_KEY' => 'super-secret-sauce',
);
All of the key-value pairs returned by this file will automatically be available via the $_ENV
and $_SERVER
PHP "superglobals". You may now reference these globals from within your configuration files:
'key' => $_ENV['TEST_STRIPE_KEY']
Be sure to add the .env.local.php
file to your .gitignore
file. This will allow other developers on your team to create their own local environment configuration, as well as hide your sensitive configuration items from source control.
Now, on your production server, create a .env.php
file in your project root that contains the corresponding values for your production environment. Like the .env.local.php
file, the production .env.php
file should never be included in source control.
Note: You may create a file for each environment supported by your application. For example, the
development
environment will load the.env.development.php
file if it exists. However, theproduction
environment always uses the.env.php
file.
Maintenance Mode
When your application is in maintenance mode, a custom view will be displayed for all routes into your application. This makes it easy to "disable" your application while it is updating or when you are performing maintenance. A call to the App::down
method is already present in your app/start/global.php
file. The response from this method will be sent to users when your application is in maintenance mode.
To enable maintenance mode, simply execute the down
Artisan command:
php artisan down
To disable maintenance mode, use the up
command:
php artisan up
To show a custom view when your application is in maintenance mode, you may add something like the following to your application's app/start/global.php
file:
App::down(function()
{
return Response::view('maintenance', array(), 503);
});
If the Closure passed to the down
method returns NULL
, maintenance mode will be ignored for that request.
Maintenance Mode & Queues
While your application is in maintenance mode, no queue jobs will be handled. The jobs will continue to be handled as normal once the application is out of maintenance mode.