- Introduction
- After Installation
- Environment Configuration
- Protecting Sensitive Configuration
- Maintenance Mode
- Pretty URLs
All of the configuration files for the Laravel framework are stored in the config directory. Each option is documented, so feel free to look through the files and get familiar with the options available to you.
The first thing you should do after installing Laravel is name your application. By default, the app directory is namespaced under App, and autoloaded by Composer using the PSR-4 autoloading standard. However, you should change the namespace to match the name of your application, which you can easily do via the app:name Artisan command.
For example, if your application is named "Horsefly", you should run the following command from the root of your installation:
php artisan app:name Horsefly
Laravel needs very little configuration out of the box. You are free to get started developing! However, you may wish to review the config/app.php file and its documentation. It contains several options such as timezone and locale that you may wish to change according to your location.
Once Laravel is installed, you should also configure your local environment. This will allow you to receive detailed error messages when developing on your local machine. By default, detailed error reporting is disabled in your production configuration file.
Note: You should never have
app.debugset totruefor a production application. Never, ever do it.
Folders within storage require write access by the web server.
Several of the framework directory paths are configurable. To change the location of these directories, check out the bootstrap/paths.php file. These paths are primarily used by the Artisan CLI when generating various class files.
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 config/local with the following content:
<?php
return [
'driver' => 'file',
];
Note: Do not use 'testing' as an environment name. This is reserved for the unit testing environment.
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/environment.php file at the root of your installation. In this file you will find an $app->detectEnvironment call. The Closure passed to this method is used to determine the current environment.
<?php
$env = $app->detectEnvironment(function()
{
return getenv('APP_ENV');
});
In this example, the 'APP_ENV' environment variable is the name of the environment. To set the environment variable, you should use a .env file in the root of your application. For more information on the .env file, see the documentation below.
You may access the current application environment via the environment method on the Application instance:
$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...
}
To obtain an instance of the application, resolve the Illuminate\Contracts\Foundation\Application contract via the service container. Of course, if you are within a service provider, the application instance is available via the $this->app instance variable.
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',
))
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.php file within the root of your project, which is usually the same directory that contains your composer.json file. The .env file contains a simple list of environment variables for your application.
APP_ENV=local
DB_USERNAME=homestead
DB_PASSWORD=homestead
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:
'password' => $_ENV['DB_PASSWORD']
Be sure to add the .env.php file to your .gitignore file. This will allow other developers on your team to create their own 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 your local .env.php file, the production .env.php file should never be included in source control.
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 maintenance mode check is included in the default before filter in app/Http/Filters/MaintenanceFilter.php. The response from this check 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
While your application is in maintenance mode, no queued jobs will be handled. The jobs will continue to be handled as normal once the application is out of maintenance mode.
The framework ships with a public/.htaccess file that is used to allow URLs without index.php. If you use Apache to serve your Laravel application, be sure to enable the mod_rewrite module.
If the .htaccess file that ships with Laravel does not work with your Apache installation, try this one:
Options +FollowSymLinks
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^ index.php [L]
On Nginx, the following directive in your site configuration will allow "pretty" URLs:
location / {
try_files $uri $uri/ /index.php?$query_string;
}
Of course, when using Homestead, pretty URLs will be configured automatically.