diff --git a/configuration.md b/configuration.md deleted file mode 100644 index 482b15cb9a3..00000000000 --- a/configuration.md +++ /dev/null @@ -1,150 +0,0 @@ -# Configuration - -- [Introduction](#introduction) -- [After Installation](#after-installation) -- [Accessing Configuration Values](#accessing-configuration-values) -- [Environment Configuration](#environment-configuration) -- [Configuration Caching](#configuration-caching) -- [Maintenance Mode](#maintenance-mode) -- [Pretty URLs](#pretty-urls) - - -## Introduction - -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. - - -## After Installation - -### Naming Your Application - -After installing Laravel, you may wish to "name" your application. By default, the `app` directory is namespaced under `App`, and autoloaded by Composer using the [PSR-4 autoloading standard](http://www.php-fig.org/psr/psr-4/). However, you may 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 could run the following command from the root of your installation: - - php artisan app:name Horsefly - -Renaming your application is entirely optional, and you are free to keep the `App` namespace if you wish. - -### Other Configuration - -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. - -You may also want to configure a few additional components of Laravel, such as: - -- [Cache](/docs/{{version}}/cache#configuration) -- [Database](/docs/{{version}}/database#configuration) -- [Session](/docs/{{version}}/session#configuration) - -Once Laravel is installed, you should also [configure your local environment](/docs/{{version}}/configuration#environment-configuration). - -> **Note:** You should never have the `app.debug` configuration option set to `true` for a production application. - - -### Permissions - -Laravel may require some permissions to be configured: folders within `storage` and the `bootstrap/cache` directory require write access by the web server. - - -## Accessing Configuration Values - -You may easily access your configuration values using the `Config` facade: - - $value = Config::get('app.timezone'); - - Config::set('app.timezone', 'America/Chicago'); - -You may also use the `config` helper function from anywhere in your application: - - $value = config('app.timezone'); - - -## 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 locally than you do on your production server. It's easy using environment based configuration. - -To make this a cinch, Laravel utilizes the [DotEnv](https://github.com/vlucas/phpdotenv) PHP library by Vance Lucas. In a fresh Laravel installation, the root directory of your application will contain a `.env.example` file. If you install Laravel via Composer, this file will automatically be renamed to `.env`. Otherwise, you should rename the file manually. - -All of the variables listed in this file will be loaded into the `$_ENV` PHP super-global when your application receives a request. You may use the `env` helper to retrieve values from these variables. In fact, if you review the Laravel configuration files, you will notice several of the options already using this helper! - -Feel free to modify your environment variables as needed for your own local server, as well as your production environment. However, your `.env` file should not be committed to your application's source control, since each developer / server using your application could require a different environment configuration. - -If you are developing with a team, you may wish to continue including a `.env.example` file with your application. By putting place-holder values in the example configuration file, other developers on your team can clearly see which environment variables are needed to run your application. - -#### Accessing The Current Application Environment - -You may access the current application environment via the `environment` method on the `App` facade: - - $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... - } - -An application instance may also be accessed via the `app` helper method: - - $environment = app()->environment(); - - -## Configuration Caching - -To give your application a speed boost, you should cache all of your configuration files into a single file using the `config:cache` Artisan command. This will combine all of the configuration options for your application into a single file which can be loaded quickly by the framework. - -You should typically run the `config:cache` command as part of your deployment routine. - - -## Maintenance Mode - -When your application is in maintenance mode, a custom view will be displayed for all requests 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 middleware stack for your application. If the application is in maintenance mode, an `HttpException` will be thrown with a status code of 503. - -To enable maintenance mode, simply execute the `down` Artisan command: - - php artisan down - -To disable maintenance mode, use the `up` command: - - php artisan up - -### Maintenance Mode Response Template - -The default template for maintenance mode responses is located in `resources/views/errors/503.blade.php`. - -### Maintenance Mode & Queues - -While your application is in maintenance mode, no [queued jobs](/docs/{{version}}/queues) will be handled. The jobs will continue to be handled as normal once the application is out of maintenance mode. - - -## Pretty URLs - -### Apache - -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] - -If your web host doesn't allow the `FollowSymlinks` option, try replacing it with `Options +SymLinksIfOwnerMatch`. - -### Nginx - -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](/docs/{{version}}/homestead), pretty URLs will be configured automatically. diff --git a/database.md b/database.md index 8d1c13d785a..1f0e9671796 100644 --- a/database.md +++ b/database.md @@ -21,7 +21,7 @@ Laravel makes connecting with databases and running queries extremely simple acr Laravel makes connecting with databases and running queries extremely simple. The database configuration for your application is located at `config/database.php`. In this file you may define all of your database connections, as well as specify which connection should be used by default. Examples for all of the supported database systems are provided in this file. -By default, Laravel's sample [environment configuration](/docs/{{version}}/configuration#environment-configuration) is ready to use with [Laravel Homestead](/docs/{{version}}/homestead), which is a convenient virtual machine for doing Laravel development on your local machine. Of course, you are free to modify this configuration as needed for your local database. +By default, Laravel's sample [environment configuration](/docs/{{version}}/installation#environment-configuration) is ready to use with [Laravel Homestead](/docs/{{version}}/homestead), which is a convenient virtual machine for doing Laravel development on your local machine. Of course, you are free to modify this configuration as needed for your local database. #### Read / Write Connections diff --git a/documentation.md b/documentation.md index da0da09ac1b..cb78d92b215 100644 --- a/documentation.md +++ b/documentation.md @@ -4,7 +4,6 @@ - [Contribution Guide](/docs/{{version}}/contributions) - Setup - [Installation](/docs/{{version}}/installation) - - [Configuration](/docs/{{version}}/configuration) - [Homestead](/docs/{{version}}/homestead) - The Basics - [Quickstart](/docs/{{version}}/quickstart) diff --git a/installation.md b/installation.md index 01224e3020a..3e5c312e30d 100644 --- a/installation.md +++ b/installation.md @@ -2,7 +2,11 @@ - [Installation](#installation) - [Configuration](#configuration) - - [Pretty URLs](#pretty-urls) + - [Naming Your Application](#naming-your-application) + - [Environment Configuration](#environment-configuration) + - [Configuration Caching](#configuration-caching) + - [Accessing Configuration Values](#accessing-configuration-values) +- [Maintenance Mode](#maintenance-mode) ## Installation @@ -45,10 +49,18 @@ You may also install Laravel by issuing the Composer `create-project` command in ## Configuration -After installing Laravel, you may need to configure some permissions. Folders within the `storage` and the `bootstrap/cache` directories should be writable by your web server. If you are using the [Homestead](/docs/{{version}}/homestead) virtual machine, these permissions should already be set. +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. + +#### Directory Permissions + +After installing Laravel, you may need to configure some permissions. Directories within the `storage` and the `bootstrap/cache` directories should be writable by your web server. If you are using the [Homestead](/docs/{{version}}/homestead) virtual machine, these permissions should already be set. + +#### Application Key The next thing you should do after installing Laravel is set your application key to a random string. If you installed Laravel via Composer or the Laravel installer, this key has already been set for you by the `key:generate` command. Typically, this string should be 32 characters long. The key can be set in the `.env` environment file. If you have not renamed the `.env.example` file to `.env`, you should do that now. **If the application key is not set, your user sessions and other encrypted data will not be secure!** +#### Additional Configuration + Laravel needs almost no other 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 application. You may also want to configure a few additional components of Laravel, such as: @@ -57,12 +69,12 @@ You may also want to configure a few additional components of Laravel, such as: - [Database](/docs/{{version}}/database#configuration) - [Session](/docs/{{version}}/session#configuration) -Once Laravel is installed, you should also [configure your local environment](/docs/{{version}}/configuration#environment-configuration). +Once Laravel is installed, you should also [configure your local environment](/docs/{{version}}/installation#environment-configuration). -### Pretty URLs +#### Pretty URLs -#### Apache +**Apache** 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. @@ -75,7 +87,7 @@ If the `.htaccess` file that ships with Laravel does not work with your Apache i RewriteCond %{REQUEST_FILENAME} !-f RewriteRule ^ index.php [L] -#### Nginx +**Nginx** On Nginx, the following directive in your site configuration will allow "pretty" URLs: @@ -84,3 +96,86 @@ On Nginx, the following directive in your site configuration will allow "pretty" } Of course, when using [Homestead](/docs/{{version}}/homestead), pretty URLs will be configured automatically. + + +### Naming Your Application + +After installing Laravel, you may wish to "name" your application. By default, the `app` directory is namespaced under `App`, and autoloaded by Composer using the [PSR-4 autoloading standard](http://www.php-fig.org/psr/psr-4/). However, you may 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 could run the following command from the root of your installation: + + php artisan app:name Horsefly + +Renaming your application is entirely optional, and you are free to keep the `App` namespace if you wish. + + +### 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 locally than you do on your production server. It's easy using environment based configuration. + +To make this a cinch, Laravel utilizes the [DotEnv](https://github.com/vlucas/phpdotenv) PHP library by Vance Lucas. In a fresh Laravel installation, the root directory of your application will contain a `.env.example` file. If you install Laravel via Composer, this file will automatically be renamed to `.env`. Otherwise, you should rename the file manually. + +All of the variables listed in this file will be loaded into the `$_ENV` PHP super-global when your application receives a request. You may use the `env` helper to retrieve values from these variables. In fact, if you review the Laravel configuration files, you will notice several of the options already using this helper! + +Feel free to modify your environment variables as needed for your own local server, as well as your production environment. However, your `.env` file should not be committed to your application's source control, since each developer / server using your application could require a different environment configuration. + +If you are developing with a team, you may wish to continue including a `.env.example` file with your application. By putting place-holder values in the example configuration file, other developers on your team can clearly see which environment variables are needed to run your application. + +#### Accessing The Current Application Environment + +You may access the current application environment via the `environment` method on the `App` facade: + + $environment = App::environment(); + +You may also pass arguments to the `environment` method to check if the environment matches a given value. You may even pass multiple values if necessary: + + if (App::environment('local')) { + // The environment is local + } + + if (App::environment('local', 'staging')) { + // The environment is either local OR staging... + } + +An application instance may also be accessed via the `app` helper method: + + $environment = app()->environment(); + + +### Configuration Caching + +To give your application a speed boost, you should cache all of your configuration files into a single file using the `config:cache` Artisan command. This will combine all of the configuration options for your application into a single file which can be loaded quickly by the framework. + +You should typically run the `config:cache` command as part of your deployment routine. + + +### Accessing Configuration Values + +You may easily access your configuration values using the global `config` helper function. The configuratino values may be accessed using "dot" syntax, which includes the name of the file and option you with to access. A default value may also be specified and will be returned if the configuration option does not exist: + + $value = config('app.timezone'); + +To set configuration values at runtime, pass an array to the `config` helper: + + config(['app.timezone' => 'America/Chicago']); + + +## Maintenance Mode + +When your application is in maintenance mode, a custom view will be displayed for all requests 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 middleware stack for your application. If the application is in maintenance mode, an `HttpException` will be thrown with a status code of 503. + +To enable maintenance mode, simply execute the `down` Artisan command: + + php artisan down + +To disable maintenance mode, use the `up` command: + + php artisan up + +### Maintenance Mode Response Template + +The default template for maintenance mode responses is located in `resources/views/errors/503.blade.php`. + +### Maintenance Mode & Queues + +While your application is in maintenance mode, no [queued jobs](/docs/{{version}}/queues) will be handled. The jobs will continue to be handled as normal once the application is out of maintenance mode. diff --git a/lifecycle.md b/lifecycle.md index 52410883f20..a4adf21b4c5 100644 --- a/lifecycle.md +++ b/lifecycle.md @@ -26,7 +26,7 @@ The `index.php` file loads the Composer generated autoloader definition, and the Next, the incoming request is sent to either the HTTP kernel or the console kernel, depending on the type of request that is entering the application. These two kernels serve as the central location that all requests flow through. For now, let's just focus on the HTTP kernel, which is located in `app/Http/Kernel.php`. -The HTTP kernel extends the `Illuminate\Foundation\Http\Kernel` class, which defines an array of `bootstrappers` that will be run before the request is executed. These bootstrappers configure error handling, configure logging, [detect the application environment](/docs/{{version}}/configuration#environment-configuration), and perform other tasks that need to be done before the request is actually handled. +The HTTP kernel extends the `Illuminate\Foundation\Http\Kernel` class, which defines an array of `bootstrappers` that will be run before the request is executed. These bootstrappers configure error handling, configure logging, [detect the application environment](/docs/{{version}}/installation#environment-configuration), and perform other tasks that need to be done before the request is actually handled. The HTTP kernel also defines a list of HTTP [middleware](/docs/{{version}}/middleware) that all requests must pass through before being handled by the application. These middleware handle reading and writing the [HTTP session](/docs/{{version}}/session), determine if the application is in maintenance mode, [verifying the CSRF token](/docs/{{version}}/routing#csrf-protection), and more. diff --git a/mail.md b/mail.md index 7187940bb32..0b179f58534 100644 --- a/mail.md +++ b/mail.md @@ -211,6 +211,6 @@ If you wish to specify a specific queue on which to push the message, you may do When developing an application that sends e-mail, you probably don't want to actually send e-mails to live e-mail addresses. Laravel provides several ways to "disable" the actual sending of e-mail messages. -One solution is to use the `log` mail driver during local development. This driver will write all e-mail messages to your log files for inspection. For more information on configuring your application per environment, check out the [configuration documentation](/docs/{{version}}/configuration#environment-configuration). +One solution is to use the `log` mail driver during local development. This driver will write all e-mail messages to your log files for inspection. For more information on configuring your application per environment, check out the [configuration documentation](/docs/{{version}}/installation#environment-configuration). Alternatively, you may use a service like [Mailtrap](https://mailtrap.io) and the `smtp` driver to send your e-mail messages to a "dummy" mailbox where you may view them in a true e-mail client. This approach has the benefit of allowing you to actually inspect the final e-mails in Mailtrap's message viewer. diff --git a/releases.md b/releases.md index d0683c4f45c..aa5228c5e33 100644 --- a/releases.md +++ b/releases.md @@ -154,7 +154,7 @@ The `php artisan tinker` command now utilizes [Psysh](https://github.com/bobthec ### DotEnv -Instead of a variety of confusing, nested environment configuration directories, Laravel 5 now utilizes [DotEnv](https://github.com/vlucas/phpdotenv) by Vance Lucas. This library provides a super simple way to manage your environment configuration, and makes environment detection in Laravel 5 a breeze. For more details, check out the full [configuration documentation](/docs/{{version}}/configuration#environment-configuration). +Instead of a variety of confusing, nested environment configuration directories, Laravel 5 now utilizes [DotEnv](https://github.com/vlucas/phpdotenv) by Vance Lucas. This library provides a super simple way to manage your environment configuration, and makes environment detection in Laravel 5 a breeze. For more details, check out the full [configuration documentation](/docs/{{version}}/installation#environment-configuration). ### Laravel Elixir diff --git a/upgrade.md b/upgrade.md index bbc9010a621..6c518092dc2 100644 --- a/upgrade.md +++ b/upgrade.md @@ -115,7 +115,7 @@ Copy the new `.env.example` file to `.env`, which is the `5.0` equivalent of the Additionally, copy any custom values you had in your old `.env.php` file and place them in both `.env` (the real value for your local environment) and `.env.example` (a sample instructional value for other team members). -For more information on environment configuration, view the [full documentation](/docs/{{version}}/configuration#environment-configuration). +For more information on environment configuration, view the [full documentation](/docs/{{version}}/installation#environment-configuration). > **Note:** You will need to place the appropriate `.env` file and values on your production server before deploying your Laravel 5 application.