Fixes and improvements

javiereguiluz · javiereguiluz · commit ba206a24e06b · 2019-06-11T17:20:18.000+02:00
diff --git a/configuration.rst b/configuration.rst
@@ -20,11 +20,11 @@ directory, which has this default structure:
 The ``routes.yaml`` file defines the :doc:`routing configuration </routing>`;
 the ``services.yaml`` file configures the services of the
 :doc:`service container </service_container>`; the ``bundles.php`` file enables/
-disables packages in your application and it's managed automatically by
+disables packages in your application and is managed automatically by
 :doc:`Symfony Flex </setup/flex>`.
 
-The most important element inside ``config/`` is the ``packages/`` directory,
-which stores the configuration of every package installed in your application.
+You'll be working most in the ``config/packages/`` directory. This directory
+stores the configuration of every package installed in your application.
 Packages (also called "bundles" in Symfony and "plugins/modules" in other
 projects) add ready-to-use features to your projects.
 
@@ -57,8 +57,8 @@ and throughout the Symfony documentation, all configuration examples will be
 shown in these three formats.
 
 There isn't any practical difference between formats. In fact, Symfony
-transforms all of them into PHP before running the application, so there's not
-even any performance difference between them.
+transforms and caches all of them into PHP before running the application, so
+there's not even any performance difference between them.
 
 YAML is used by default when installing packages because it's concise and very
 readable. These are the main advantages and disadvantages of each format:
@@ -188,8 +188,8 @@ reusable configuration value. By convention, parameters are defined under the
         // ...
 
 Once defined, you can reference this parameter value from any other
-configuration file using a special syntax: wrap the parameter name with two
-``%`` (e.g. ``%app.admin_email%``):
+configuration file using a special syntax: wrap the parameter name in two ``%``
+(e.g. ``%app.admin_email%``):
 
 .. configuration-block::
 
@@ -215,9 +215,9 @@ configuration file using a special syntax: wrap the parameter name with two
                 https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
             <!-- any string surrounded by two % is replaced by that parameter value -->
-            <some-package email-address="%app.admin_email%">
+            <some-package:config email-address="%app.admin_email%">
                 <!-- ... -->
-            </some-package>
+            </some-package:config>
         </container>
 
     .. code-block:: php
@@ -258,26 +258,19 @@ to behave differently at different times:
 * After deploying to **production**, you want that same application to be
   optimized for speed and only log errors.
 
-In Symfony this is implemented with **environments**, which is a set of
-configuration files that define the application behavior. A typical Symfony
-application begins with three environments: ``dev`` (for local development),
-``prod`` (for production servers) and ``test`` (for
-:doc:`automated tests </testing>`). Each of them defines its own configuration
-files:
+The files stored in ``config/packages/`` are used by Symfony to configure the
+:doc:`application services </service_container>`. In other words, you can change
+the application behavior by changing which configuration files are loaded.
+That's the idea of Symfony's **configuration environments**.
 
-* for the ``dev`` environment: ``config/packages/dev/``
-* for the ``prod`` environment: ``config/packages/prod/``
-* for the ``test`` environment: ``config/packages/test/``
-
-In reality, each environment differs only somewhat from others. This means that
-all environments share a large base of common configurations, which is put in
-files directly in the ``config/packages/`` directory.
-
-When running the application, Symfony loads the configuration files in this
-order (the last files can override the values set in the previous ones):
+A typical Symfony application begins with three environments: ``dev`` (for local
+development), ``prod`` (for production servers) and ``test`` (for
+:doc:`automated tests </testing>`). When running the application, Symfony loads
+the configuration files in this order (the last files can override the values
+set in the previous ones):
 
 #. ``config/packages/*.yaml`` (and ``.xml`` and ``*.php`` files too);
-#. ``config/packages/<environment>/*.yaml`` (and ``.xml`` and ``*.php`` files too);
+#. ``config/packages/<environment-name>/*.yaml`` (and ``.xml`` and ``*.php`` files too);
 #. ``config/packages/services.yaml`` (and ``services.xml`` and ``services.php`` files too);
 
 Take the ``framework`` package, installed by default, as an example:
@@ -292,6 +285,10 @@ Take the ``framework`` package, installed by default, as an example:
   is loaded to override some of the settings previously configured in
   ``config/packages/framework.yaml``.
 
+In reality, each environment differs only somewhat from others. This means that
+all environments share a large base of common configurations, which is put in
+files directly in the ``config/packages/`` directory.
+
 .. seealso::
 
     See the ``configureContainer()`` method of
@@ -311,10 +308,10 @@ Open the ``.env`` file and edit the value of the ``APP_ENV`` variable to change
 the environment in which the application runs. For example, to run the
 application in production:
 
-```bash
-# .env
-APP_ENV=prod
-```
+.. code-block:: bash
+
+    # .env
+    APP_ENV=prod
 
 This value is used both for the web and for the console commands. However, you
 can override it for commands by setting the ``APP_ENV`` value before running them:
@@ -336,9 +333,9 @@ Creating a New Environment
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The default three environments provided by Symfony are enough for most projects,
-but you can define more environments if you want to. For example, this is how
-you can define a ``staging`` environment where the client can test the project
-before going to production:
+but you can define your own environments too. For example, this is how you can
+define a ``staging`` environment where the client can test the project before
+going to production:
 
 #. Create a configuration directory with the same name as the environment (in
    this case, ``config/packages/staging/``);
@@ -349,20 +346,27 @@ before going to production:
 #. Select the ``staging`` environment using the ``APP_ENV`` env var as explained
    in the previous section.
 
+.. tip::
+
+    It's common for environments to be similar between each other, so you can
+    use `symbolic links`_ between ``config/packages/<environment-name>/``
+    directories to reuse the same configuration.
+
 .. _config-env-vars:
 
 Configuration Based on Environment Variables
 --------------------------------------------
 
 Using `environment variables`_ (or "env vars" for short) is a common practice to
-configure sensitive options such as credentials and passwords. Instead of
-defining the values of those options in the configuration files, you add a
-reference to an environment variable which will be resolved at runtime (only
-once per request, to not impact performance).
+configure options that depend on where the application is run (e.g. the database
+credentials are usually different in production and in your local machine).
+
+Instead of defining those as regular options, you can define them as environment
+variables and reference them in the configuration files using the special syntax
+``%env(ENV_VAR_NAME)%``. The values of these options are resolved at runtime
+(only once per request, to not impact performance).
 
-Environment variables can be used in any configuration file and they are
-referenced with the special syntax ``%env(ENV_VAR_NAME)%``. This example shows
-how to configure the database connection using an env var:
+This example shows how to configure the database connection using an env var:
 
 .. configuration-block::
 
@@ -588,4 +592,5 @@ Learn more
     configuration/*
 
 .. _`environment variables`: https://en.wikipedia.org/wiki/Environment_variable
+.. _`symbolic links`: https://en.wikipedia.org/wiki/Symbolic_link
 .. _`utilities to manage env vars`: https://symfony.com/doc/master/cloud/cookbooks/env.html
diff --git a/configuration/front_controllers_and_kernel.rst b/configuration/front_controllers_and_kernel.rst
@@ -179,7 +179,7 @@ parameter used, for example, to turn Twig's debug mode on:
         <?xml version="1.0" encoding="UTF-8" ?>
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xmlns:doctrine="http://symfony.com/schema/dic/doctrine"
+            xmlns:twig="http://symfony.com/schema/dic/twig"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
                 https://symfony.com/schema/dic/services/services-1.0.xsd
                 http://symfony.com/schema/dic/twig
