Created: May 10th 2021
Last updated: May 21st 2021
Categories: IT Development, Laravel
Author: Marcus Fleuti

Laravel: Environment configuration

Tags: app, application, artisan, config, configuration, dotenv, env, environment, framework, Laravel, maintenance, PHP

Donate with

82uymVXLkvVbB4c4JpTd1tYm1yj1cKPKR2wqmw3XF8YXKTmY7JrTriP4pVwp2EJYBnCFdXhLq4zfFA6ic7VAWCFX5wfQbCC

Introduction

All the configuration files for a Laravel application are stored in the config directory. These configuration files allow you to configure stuff like the database connection information, mail server information as well as other core configuration values such as timezone and encryption key.

Environment configuration

Laravel uses the DotEnv PHP library. During the Laravel installation a file called .env is getting generated. The default .env file contains some common configuration values that may differ based on whether your application is running locally or on a LIVE web server. The values set in the .env file are retrieved from the configuration files inside of the config directory by using Laravel's env function.

Retrieving the environment configuration

All variables listed in the .env file will be loaded into the $_ENV PHP super-global variable when your application receives a request. Maybe you sometimes need the env helper to retrieve values from these variables in your configuration files.

Determing the current environment

The current application environment is stored in the APP_ENV variable from your .env file. If you need to access this variable please use the environment method on the App-facade:

You may also pass arguments to the environment method to check if the returned value is matching a given value. The method will return true if the returned value matches the given values:

Accessing configuration values

You can pretty easily access your configuration values using the global config helper function from anywhere in your application. The configuration values may be accessed using "dot" syntax, which includes the name of the file and option you want to access. A default value can also be specified and will be returned if the configuration option does not exist:

To set a configuration value you have to pass an array to the config helper:

Configuration caching

If you want to give your application a speed boost, you should cache all your config files into a single file with the config:cache Artisan command. This is going to combine all configuration options for your application into a single file which can be loaded quickly by Laravel.

Normally you should run php artisan config:cache as part of your production development. The command shouldn't run during local development, as configuration options will need to be changed during development.

Don't use php artisan config:cache in your local development project, only on productive applications!

Debug mode

The debug option is set in your config/app.php file and determines how much information about an error is actually displayed to the user. By default this is set to check the value from the APP_DEBUG environment variable which is stored in the .env file.

Keep in mind:

For local development you should set APP_DEBUG to true.
In productive environments APP_DEBUG should always be false. If the value is set to true, you risk to show errors to the user / customer

Maintenance mode

When the application is in maintenance mode, a custom view will be displayed for all requests. This makes it easy to "disable" your application while it is updating or you are performing maintenance. The maintenance check is included into your default middleware stack for your application. When the application is in maintenance mode, a MaintenanceModeException will be thrown with a status code of 503.

To enable the maintenance mode type the following Artisan command:

php artisan down

You can also provide a retry option which is going to set the Retry-After HTTP header value:

php artisan down --retry=60

Bypassing the maintenance mode

If you need to bypass the maintenance mode you have to use the secret option, to specify a bypass token:

php artisan down --secret="1630542a-246b-4b66-afa1-dd72a4c43515"

After the application was placed into maintenance mode, you can navigate to the application URL matching the token which is set above. Laravel will issue a maintenance mode bypass cookie to your browser. When you are accessing this "hidden" route you are able to browse the application normally.

Pre-render the maintenance mode view

When you are using php artisan down during deployment, your users may still see errors if they access the application while Composer dependencies or other things are getting updated. This happens because a significant part of the Laravel framework must boot in order to determine if the application is in maintenance mode and render the maintenance mode using the template engine.

php artisan down --render="errors::503"

Redirecting maintenance mode requests

When in maintenance mode, the maintenance mode view is going to get displayed on all application URLs. Maybe you wish to redirect all requests to a specific URL: