diff --git a/configuration.rst b/configuration.rst
index 1b120db7e1a..3c5060ff7ad 100644
--- a/configuration.rst
+++ b/configuration.rst
@@ -4,94 +4,75 @@
Configuring Symfony (and Environments)
======================================
-Every Symfony application consists of a collection of bundles that add useful tools
-(:doc:`services `) to your project. Each bundle can be customized
-via configuration files that live - by default - in the ``app/config`` directory.
+Symfony applications can install third-party packages (bundles, libraries, etc.)
+to bring in new features (:doc:`services `) to your project.
+Each package can be customized via configuration files that live - by default -
+in the ``config/`` directory.
-Configuration: config.yml
--------------------------
+Configuration: config/packages/
+-------------------------------
-The main configuration file is called ``config.yml``:
+The configuration for each package can be found in ``config/packages/``. For
+instance, the framework bundle is configured in ``config/packages/framework.yaml``:
.. configuration-block::
.. code-block:: yaml
- # app/config/config.yml
- imports:
- - { resource: parameters.yml }
- - { resource: security.yml }
- - { resource: services.yml }
-
+ # config/packages/framework.yaml
framework:
- secret: '%secret%'
- router: { resource: '%kernel.project_dir%/app/config/routing.yml' }
- # ...
-
- # Twig Configuration
- twig:
- debug: '%kernel.debug%'
- strict_variables: '%kernel.debug%'
-
- # ...
+ secret: '%env(APP_SECRET)%'
+ #default_locale: en
+ #csrf_protection: ~
+ #http_method_override: true
+ #trusted_hosts: ~
+ # https://symfony.com/doc/current/reference/configuration/framework.html#handler-id
+ #session:
+ # # The native PHP session handler will be used
+ # handler_id: ~
+ #esi: ~
+ #fragments: ~
+ php_errors:
+ log: true
.. code-block:: xml
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
.. code-block:: php
- // app/config/config.php
- $this->import('parameters.yml');
- $this->import('security.yml');
- $this->import('services.yml');
-
- $container->loadFromExtension('framework', array(
- 'secret' => '%secret%',
- 'router' => array(
- 'resource' => '%kernel.project_dir%/app/config/routing.php',
- ),
- // ...
- ));
-
- // Twig Configuration
- $container->loadFromExtension('twig', array(
- 'debug' => '%kernel.debug%',
- 'strict_variables' => '%kernel.debug%',
- ));
-
- // ...
-
-Most top-level keys - like ``framework`` and ``twig`` - are configuration for a
-specific bundle (i.e. ``FrameworkBundle`` and ``TwigBundle``).
+ # config/packages/framework.php
+ $container->loadFromExtension('framework', [
+ 'secret' => '%env(APP_SECRET)%',
+ //'default_locale' => 'en',
+ //'csrf_protection' => null,
+ //'http_method_override' => true,
+ //'trusted_hosts' => null,
+ // https://symfony.com/doc/current/reference/configuration/framework.html#handler-id
+ //'session' => [
+ // // The native PHP session handler will be used
+ // 'handler_id' => null,
+ //],
+ //'esi' => null,
+ //'fragments' => null,
+ 'php_errors' => [
+ 'log' => true,
+ ],
+ ]);
+
+The top-level key (here ``framework``) references configuration for a specific
+bundle (``FrameworkBundle`` in this case).
.. sidebar:: Configuration Formats
@@ -100,9 +81,7 @@ specific bundle (i.e. ``FrameworkBundle`` and ``TwigBundle``).
choose whatever you like best. There is no performance difference:
* :doc:`/components/yaml/yaml_format`: Simple, clean and readable;
-
* *XML*: More powerful than YAML at times & supports IDE autocompletion;
-
* *PHP*: Very powerful but less readable than standard configuration formats.
Configuration Reference & Dumping
@@ -111,15 +90,14 @@ Configuration Reference & Dumping
There are *two* ways to know *what* keys you can configure:
#. Use the :doc:`Reference Section `;
-
#. Use the ``config:dump-reference`` command.
-For example, if you want to configure something in Twig, you can see an example
-dump of all available configuration options by running:
+For example, if you want to configure something related to the framework bundle,
+you can see an example dump of all available configuration options by running:
.. code-block:: terminal
- $ php bin/console config:dump-reference twig
+ $ php bin/console config:dump-reference framework
.. index::
single: Environments; Introduction
@@ -127,127 +105,68 @@ dump of all available configuration options by running:
.. _page-creation-environments:
.. _page-creation-prod-cache-clear:
-The imports Key: Loading other Configuration Files
---------------------------------------------------
+.. _config-parameter-intro:
+
+The parameters Key: Parameters (Variables)
+------------------------------------------
-Symfony's main configuration file is ``app/config/config.yml``. But, for organization,
-it *also* loads other configuration files via its ``imports`` key:
+The configuration has some special top-level keys. One of them is called
+``parameters``: it's used to define *variables* that can be referenced in *any*
+other configuration file. For example, when you install the *translation*
+package, a ``locale`` parameter is added to ``config/services.yaml``:
.. configuration-block::
.. code-block:: yaml
- # app/config/config.yml
- imports:
- - { resource: parameters.yml }
- - { resource: security.yml }
- - { resource: services.yml }
+ # config/services.yaml
+ parameters:
+ locale: en
+
# ...
.. code-block:: xml
-
+
+ http://symfony.com/schema/dic/services/services-1.0.xsd
+ http://symfony.com/schema/dic/symfony
+ http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
-
-
-
-
-
+
+ en
+
.. code-block:: php
- // app/config/config.php
- $this->import('parameters.yml');
- $this->import('security.yml');
- $this->import('services.yml');
-
+ // config/services.php
+ $container->setParameter('locale', 'en');
// ...
-The ``imports`` key works a lot like the PHP ``include()`` function: the contents of
-``parameters.yml``, ``security.yml`` and ``services.yml`` are read and loaded. You
-can also load XML files or PHP files.
-
-.. tip::
-
- If your application uses unconventional file extensions (for example, your
- YAML files have a ``.res`` extension) you can set the file type explicitly
- with the ``type`` option:
-
- .. configuration-block::
-
- .. code-block:: yaml
-
- # app/config/config.yml
- imports:
- - { resource: parameters.res, type: yml }
- # ...
-
- .. code-block:: xml
-
-
-
-
-
-
-
-
-
-
-
- .. code-block:: php
-
- // app/config/config.php
- $this->import('parameters.res', 'yml');
- // ...
-
-.. _config-parameter-intro:
-
-The parameters Key: Parameters (Variables)
-------------------------------------------
-
-Another special key is called ``parameters``: it's used to define *variables* that
-can be referenced in *any* other configuration file. For example, in ``config.yml``,
-a ``locale`` parameter is defined and then referenced below under the ``framework``
-key:
+This parameter is then referenced in the framework config in
+``config/packages/translation.yaml``:
.. configuration-block::
.. code-block:: yaml
- # app/config/config.yml
- # ...
-
- parameters:
- locale: en
-
+ # config/packages/translation.yaml
framework:
- # ...
-
# any string surrounded by two % is replaced by that parameter value
- default_locale: "%locale%"
+ default_locale: '%locale%'
- # ...
+ # ...
.. code-block:: xml
-
+
-
-
- en
-
-
+
-
-
.. code-block:: php
- // app/config/config.php
- // ...
-
- $container->setParameter('locale', 'en');
-
+ // config/packages/translation.php
$container->loadFromExtension('framework', array(
+ // any string surrounded by two % is replaced by that parameter value
'default_locale' => '%locale%',
+
// ...
));
- // ...
-
You can define whatever parameter names you want under the ``parameters`` key of
-any configuration file. To reference a parameter, surround its name with two percent
-signs - e.g. ``%locale%``.
+any configuration file. To reference a parameter, surround its name with two
+percent signs - e.g. ``%locale%``.
.. seealso::
@@ -296,118 +205,45 @@ For more information about parameters - including how to reference them from ins
a controller - see :ref:`service-container-parameters`.
.. _config-dot-env:
+.. _config-parameters-yml:
The .env File
~~~~~~~~~~~~~
-There is also a ``.env`` file which is loaded. Its contents become environment variables
-in the dev environment, making it easier to reference environment variables in your
-code.
-
-.. _config-parameters-yml:
-
-The Special parameters.yml File
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-On the surface, ``parameters.yml`` is just like any other configuration file: it
-is imported by ``config.yml`` and defines several parameters:
-
-.. code-block:: yaml
-
- parameters:
- # ...
- database_user: root
- database_password: ~
-
-Not surprisingly, these are referenced from inside of ``config.yml`` and help to
-configure DoctrineBundle and other parts of Symfony:
-
-.. configuration-block::
-
- .. code-block:: yaml
-
- # app/config/config.yml
- doctrine:
- dbal:
- driver: pdo_mysql
- # ...
- user: '%database_user%'
- password: '%database_password%'
-
- .. code-block:: xml
-
-
-
-
-
-
-
-
-
-
- .. code-block:: php
-
- // app/config/config.php
- $container->loadFromExtension('doctrine', array(
- 'dbal' => array(
- 'driver' => 'pdo_mysql',
- // ...
-
- 'user' => '%database_user%',
- 'password' => '%database_password%',
- ),
- ));
-
-But the ``parameters.yml`` file *is* special: it defines the values that usually
-change on each server. For example, the database credentials on your local
-development machine might be different from your workmates. That's why this file
-is not committed to the shared repository and is only stored on your machine.
-
-Because of that, **parameters.yml is not committed to your version control**. In fact,
-the ``.gitignore`` file that comes with Symfony prevents it from being committed.
-
-However, a ``parameters.yml.dist`` file *is* committed (with dummy values). This file
-isn't read by Symfony: it's just a reference so that Symfony knows which parameters
-need to be defined in the ``parameters.yml`` file. If you add or remove keys to
-``parameters.yml``, add or remove them from ``parameters.yml.dist`` too so both
-files are always in sync.
+There is also a ``.env`` file which is loaded. Its contents become environment
+variables in the dev environment, making it easier to reference environment
+variables in your code.
-.. sidebar:: The Interactive Parameter Handler
+The ``.env`` file is special, because it defines the values that usually change
+on each server. For example, the database credentials on your local development
+machine might be different from your workmates. That's why this file is **not
+committed to the shared repository** and is only stored on your machine. In
+fact, the ``.gitignore`` file that comes with Symfony prevents it from being
+committed.
- When you :ref:`install an existing Symfony project `, you
- will need to create the ``parameters.yml`` file using the committed ``parameters.yml.dist``
- file as a reference. To help with this, after you run ``composer install``, a
- Symfony script will automatically create this file by interactively asking you
- to supply the value for each parameter defined in ``parameters.yml.dist``. For
- more details - or to remove or control this behavior - see the
- `Incenteev Parameter Handler`_ documentation.
+However, a ``.env.dist`` file *is* committed (with dummy values). This file
+isn't read by Symfony: it's just a reference so that Symfony knows which
+variables need to be defined in the ``.env`` file. If you add or remove keys to
+``.env``, add or remove them from ``.env.dist`` too, so both files are always
+in sync.
Environments & the Other Config Files
-------------------------------------
-You have just *one* app, but whether you realize it or not, you need it to behave
-*differently* at different times:
+You have just *one* app, but whether you realize it or not, you need it to
+behave *differently* at different times:
-* While **developing**, you want your app to log everything and expose nice debugging
- tools;
+* While **developing**, you want your app to log everything and expose nice
+ debugging tools;
-* After deploying to **production**, you want that *same* app to be optimized for
- speed and only log errors.
+* After deploying to **production**, you want that *same* app to be optimized
+ for speed and only log errors.
-How can you make *one* application behave in two different ways? With *environments*.
+How can you make *one* application behave in two different ways? With
+*environments*.
-You've probably already been using the ``dev`` environment without even knowing it.
-After you deploy, you'll use the ``prod`` environment.
+You've probably already been using the ``dev`` environment without even knowing
+it. After you deploy, you'll use the ``prod`` environment.
To learn more about *how* to execute and control each environment, see
:doc:`/configuration/environments`.