Improve the environment configuration documentation

- Moves two general-topic paragraphs from "Retrieving Environment Configuration" sub-section into the main "Environment Configuration" section
- Adds a security note about committing .env files
- Adds a general note to clarify that .env files variables can be overridden by external environment variables
- Makes the "Retrieving Environment Configuration" sub-section linkable
- Adds a tip to the "Determining The Current Environment" sub-section to mention that the APP_ENV variable could be overridden at server-level configuration

Author: paulofreitas

configuration.md

@@ -2,6 +2,7 @@
 
 - [Introduction](#introduction)
 - [Environment Configuration](#environment-configuration)
+    - [Retrieving Environment Configuration](#retrieving-environment-configuration)
     - [Determining The Current Environment](#determining-the-current-environment)
 - [Accessing Configuration Values](#accessing-configuration-values)
 - [Configuration Caching](#configuration-caching)
@@ -19,20 +20,23 @@ It is often helpful to have different configuration values based on the environm
 
 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.
 
+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. Conversely, this would be a security risk in the event an intruder gain access to your source control repository, since any sensitive credentials would get exposed.
+
+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.
+
 > {tip} You may also create a `.env.testing` file. This file will override values from the `.env` file when running PHPUnit tests or executing Artisan commands with the `--env=testing` option.
 
-#### Retrieving Environment Configuration
+> {note} Note that any variable from your `.env` file can be overriden by external environment variables such as server-level or system-level environment variables.
+
+<a name="retrieving-environment-configuration"></a>
+### Retrieving Environment Configuration
 
 All of the variables listed in this file will be loaded into the `$_ENV` PHP super-global when your application receives a request. However, you may use the `env` helper to retrieve values from these variables in your configuration files. In fact, if you review the Laravel configuration files, you will notice several of the options already using this helper:
 
     'debug' => env('APP_DEBUG', false),
 
 The second value passed to the `env` function is the "default value". This value will be used if no environment variable exists for the given key.
 
-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.
-
 <a name="determining-the-current-environment"></a>
 ### Determining The Current Environment
 
@@ -50,6 +54,8 @@ You may also pass arguments to the `environment` method to check if the environm
         // The environment is either local OR staging...
     }
 
+> {tip} The current application environment detection can be overriden by a server-level `APP_ENV` environment variable. This can be useful when you need to share the same application for different environment configurations, so you can set up a given host to match a given environment in your server's configurations.
+
 <a name="accessing-configuration-values"></a>
 ## Accessing Configuration Values