From 0520bf1617b38a93d35d3a61f56c670b33dbff87 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 28 May 2014 17:24:08 +0200 Subject: [PATCH 1/9] Firest draft of the "How to Organize Configuration Files" cookbook --- .../configuration_organization.rst | 258 ++++++++++++++++++ cookbook/configuration/index.rst | 1 + 2 files changed, 259 insertions(+) create mode 100644 cookbook/configuration/configuration_organization.rst diff --git a/cookbook/configuration/configuration_organization.rst b/cookbook/configuration/configuration_organization.rst new file mode 100644 index 00000000000..a4a9772d890 --- /dev/null +++ b/cookbook/configuration/configuration_organization.rst @@ -0,0 +1,258 @@ +.. index:: + single: Configuration, Environments + +How to Organize Configuration Files +=================================== + +The default Symfony2 Standard Edition defines three +:doc:`execution environments ` called +``dev``, ``prod``, and ``test``. An environment simply represents a way to +execute the same codebase with different configuration. + +In order to select the configuration file to load for each environment, Symfony +executes the ``registerContainerConfiguration()`` method of the ``AppKernel`` +class:: + + // app/AppKernel.php + class AppKernel extends Kernel + { + // ... + + public function registerContainerConfiguration(LoaderInterface $loader) + { + $loader->load(__DIR__.'/config/config_'.$this->getEnvironment().'.yml'); + } + } + +This method loads the ``app/config/config_dev.yml`` file for the ``dev`` +environment and so on. In turn, this file loads the common configuration file +located at ``app/config/config.yml``. Therefore, the configuration files of the +default Symfony Standard Edition follow this structure: + +.. code-block:: text + + / + ├─ app/ + │ └─ config/ + │ ├─ config.yml + │ ├─ config_dev.yml + │ ├─ config_prod.yml + │ ├─ config_test.yml + │ ├─ parameters.yml + │ ├─ parameters.yml.dist + │ ├─ routing.yml + │ ├─ routing_dev.yml + │ └─ security.yml + ├─ src/ + ├─ vendor/ + └─ web/ + +This default structure was choosen for its simplicity — one file per environment. +But as any other Symfony feature, you can customize it to better suit your needs. +The following sections explain different ways to organize your configuration +files. In order to simplify the examples, only the ``dev`` and ``prod`` +environments are taken into account. + +Different Directories per Environment +------------------------------------- + +Instead of suffixing the files with ``_dev`` and ``_prod``, this technique +groups all the related configuration files under a directory with the same +name as the environment: + +.. code-block:: text + + / + ├─ app/ + │ └─ config/ + │ ├─ common/ + │ │ ├─ config.yml + │ │ ├─ parameters.yml + │ │ ├─ routing.yml + │ │ └─ security.yml + │ ├─ dev/ + │ │ ├─ config.yml + │ │ ├─ parameters.yml + │ │ ├─ routing.yml + │ │ └─ security.yml + │ └─ prod/ + │ ├─ config.yml + │ ├─ parameters.yml + │ ├─ routing.yml + │ └─ security.yml + ├─ src/ + ├─ vendor/ + └─ web/ + +To make it work, change the code of the ``registerContainerConfiguration()`` +method:: + + // app/AppKernel.php + class AppKernel extends Kernel + { + // ... + + public function registerContainerConfiguration(LoaderInterface $loader) + { + $loader->load(__DIR__.'/config/'.$this->getEnvironment().'/config.yml'); + } + } + +Then, make sure that each ``config.yml`` file loads the rest of the configuration +files, including the common files: + +.. code-block:: yaml + + # app/config/dev/config.yml + imports: + - { resource: '../config.yml' } + - { resource: 'parameters.yml' } + - { resource: 'security.yml' } + + # ... + + # app/config/prod/config.yml + imports: + - { resource: '../config.yml' } + - { resource: 'parameters.yml' } + - { resource: 'security.yml' } + + # ... + + + # app/config/common/config.yml + imports: + - { resource: 'parameters.yml' } + - { resource: 'security.yml' } + + # ... + + +Semantic Configuration Files +---------------------------- + +A different organization strategy may be needed for complex applications with +large configuration files. You could for instance create one file per bundle +and several files to define all the application services: + +.. code-block:: text + + / + ├─ app/ + │ └─ config/ + │ ├─ bundles/ + │ │ ├─ bundle1.yml + │ │ ├─ bundle2.yml + │ │ ├─ ... + │ │ └─ bundleN.yml + │ ├─ environments/ + │ │ ├─ common.yml + │ │ ├─ dev.yml + │ │ └─ prod.yml + │ ├─ routing/ + │ │ ├─ common.yml + │ │ ├─ dev.yml + │ │ └─ prod.yml + │ └─ services/ + │ ├─ frontend.yml + │ ├─ backend.yml + │ ├─ ... + │ └─ security.yml + ├─ src/ + ├─ vendor/ + └─ web/ + +Again, change the code of the ``registerContainerConfiguration()`` method to +make Symfony aware of the new file organization:: + + // app/AppKernel.php + class AppKernel extends Kernel + { + // ... + + public function registerContainerConfiguration(LoaderInterface $loader) + { + $loader->load(__DIR__.'/config/environments/'.$this->getEnvironment().'.yml'); + } + } + +Advanced Tecniques +------------------ + +Symfony loads configuration files using the ``Config component ``, +which provides some advanced features. + +Mix and Match Configuration Formats +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Configuration files can import files defined with any other built-in configuration +format (``.yml``, ``.xml``, ``.php``, ``.ini``): + +.. code-block:: yaml + + # app/config/config.yml + imports: + - { resource: 'parameters.yml' } + - { resource: 'services.xml' } + - { resource: 'security.yml' } + - { resource: 'legacy.php' } + + # ... + +If you use any other configuration format, you have to define your own loader +class extending it from ``Symfony\Component\DependencyInjection\Loader\FileLoader``. +When the configuration values are dynamic, you can use the PHP configuration +file to execute your own logic. In addition, you can define your own services +to load configuration from databases and web services. + +Directory Loading +~~~~~~~~~~~~~~~~~ + +Splitting configuration into lots of smaller files can rapidly become cumbersome +when importing those files from the main configuration file. Avoid these problems +by loading an entire directory: + +.. code-block:: yaml + + # app/config/config.yml + imports: + - { resource: 'bundles/' } + - { resource: 'services/' } + + # ... + +The Config component will look for recursively in the ``bundles/`` and ``services/`` +directories and it will load any supported file format (``.yml``, ``.xml``, +``.php``, ``.ini``). + +Global Configuration Files +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Some system administrators may prefer to store sensitive parameteres in global +configuration files under the ``/etc`` directory. Imagine that the database +credentials for your website are stored in the ``/etc/sites/mysite.com/parameters.yml``. +Loading this file is as simple as indicating the full file path when importing +it from any other configuration file: + +.. code-block:: yaml + + # app/config/config.yml + imports: + - { resource: 'parameters.yml' } + - { resource: '/etc/sites/mysite.com/parameters.yml' } + + # ... + +Most of the time, local developers won't have the same files that exist in the +production servers. For that reason, the Config component provides the +``ignore_errors`` option to silently discard errors when the loaded file +doesn't exist: + +.. code-block:: yaml + + # app/config/config.yml + imports: + - { resource: 'parameters.yml' } + - { resource: '/etc/sites/mysite.com/parameters.yml', ignore_errors: true } + + # ... diff --git a/cookbook/configuration/index.rst b/cookbook/configuration/index.rst index 69250747457..35b87ef0f2e 100644 --- a/cookbook/configuration/index.rst +++ b/cookbook/configuration/index.rst @@ -12,3 +12,4 @@ Configuration pdo_session_storage apache_router web_server_configuration + configuration_organization From d861be32fbd9bea8aedb49b055b03eb514d9e74e Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 2 Jun 2014 18:04:16 +0200 Subject: [PATCH 2/9] Added all the suggestions made by reviewers --- .../configuration_organization.rst | 263 ++++++++++++++---- cookbook/map.rst.inc | 1 + 2 files changed, 216 insertions(+), 48 deletions(-) diff --git a/cookbook/configuration/configuration_organization.rst b/cookbook/configuration/configuration_organization.rst index a4a9772d890..1850d0a9aed 100644 --- a/cookbook/configuration/configuration_organization.rst +++ b/cookbook/configuration/configuration_organization.rst @@ -1,5 +1,5 @@ .. index:: - single: Configuration, Environments + single: Configuration How to Organize Configuration Files =================================== @@ -47,7 +47,7 @@ default Symfony Standard Edition follow this structure: ├─ vendor/ └─ web/ -This default structure was choosen for its simplicity — one file per environment. +This default structure was chosen for its simplicity — one file per environment. But as any other Symfony feature, you can customize it to better suit your needs. The following sections explain different ways to organize your configuration files. In order to simplify the examples, only the ``dev`` and ``prod`` @@ -101,38 +101,104 @@ method:: Then, make sure that each ``config.yml`` file loads the rest of the configuration files, including the common files: -.. code-block:: yaml +.. configuration-block:: - # app/config/dev/config.yml - imports: - - { resource: '../config.yml' } - - { resource: 'parameters.yml' } - - { resource: 'security.yml' } + .. code-block:: yaml - # ... + # app/config/dev/config.yml + imports: + - { resource: '../common/config.yml' } + - { resource: 'parameters.yml' } + - { resource: 'security.yml' } - # app/config/prod/config.yml - imports: - - { resource: '../config.yml' } - - { resource: 'parameters.yml' } - - { resource: 'security.yml' } + # ... - # ... + .. code-block:: xml + + + + + + - # app/config/common/config.yml - imports: - - { resource: 'parameters.yml' } - - { resource: 'security.yml' } + - # ... + .. code-block:: php + // app/config/dev/config.php + $loader->import('../common/config.php'); + $loader->import('parameters.php'); + $loader->import('security.php'); + + // ... + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/prod/config.yml + imports: + - { resource: '../common/config.yml' } + - { resource: 'parameters.yml' } + - { resource: 'security.yml' } + + # ... + + .. code-block:: xml + + + + + + + + + + + .. code-block:: php + + // app/config/prod/config.php + $loader->import('../common/config.php'); + $loader->import('parameters.php'); + $loader->import('security.php'); + + // ... + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + imports: + - { resource: 'parameters.yml' } + - { resource: 'security.yml' } + + # ... + + .. code-block:: xml + + + + + + + + + + .. code-block:: php + + // app/config/config.php + $loader->import('parameters.php'); + $loader->import('security.php'); + + // ... Semantic Configuration Files ---------------------------- A different organization strategy may be needed for complex applications with -large configuration files. You could for instance create one file per bundle +large configuration files. For instance, you could create one file per bundle and several files to define all the application services: .. code-block:: text @@ -176,6 +242,10 @@ make Symfony aware of the new file organization:: } } +Following the same technique explained in the previous section, make sure to +load the appropriate configuration files from each main file (``common.yml``, +``dev.yml`` and ``prod.yml``). + Advanced Tecniques ------------------ @@ -188,19 +258,50 @@ Mix and Match Configuration Formats Configuration files can import files defined with any other built-in configuration format (``.yml``, ``.xml``, ``.php``, ``.ini``): -.. code-block:: yaml +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + imports: + - { resource: 'parameters.yml' } + - { resource: 'services.xml' } + - { resource: 'security.yml' } + - { resource: 'legacy.php' } + + # ... + + .. code-block:: xml + + + + + + + + + + - # app/config/config.yml - imports: - - { resource: 'parameters.yml' } - - { resource: 'services.xml' } - - { resource: 'security.yml' } - - { resource: 'legacy.php' } + .. code-block:: php - # ... + // app/config/config.php + $loader->import('parameters.yml'); + $loader->import('services.xml'); + $loader->import('security.yml'); + $loader->import('legacy.php'); + + // ... + +.. caution:: + + The ``IniFileLoader`` parses the file contents using the + :phpfunction:`parse_ini_file` function, therefore, you can only set + parameters to string values. To set parameters to other data types + (e.g. boolean, integer, etc), the other loaders are recommended. If you use any other configuration format, you have to define your own loader -class extending it from ``Symfony\Component\DependencyInjection\Loader\FileLoader``. +class extending it from :class:`Symfony\\Component\\DependencyInjection\\Loader\\FileLoader`. When the configuration values are dynamic, you can use the PHP configuration file to execute your own logic. In addition, you can define your own services to load configuration from databases and web services. @@ -212,14 +313,35 @@ Splitting configuration into lots of smaller files can rapidly become cumbersome when importing those files from the main configuration file. Avoid these problems by loading an entire directory: -.. code-block:: yaml +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + imports: + - { resource: 'bundles/' } + - { resource: 'services/' } + + # ... + + .. code-block:: xml - # app/config/config.yml - imports: - - { resource: 'bundles/' } - - { resource: 'services/' } + + + + + + + + + .. code-block:: php + + // app/config/config.php + $loader->import('bundles/'); + $loader->import('services/'); + + // ... - # ... The Config component will look for recursively in the ``bundles/`` and ``services/`` directories and it will load any supported file format (``.yml``, ``.xml``, @@ -234,25 +356,70 @@ credentials for your website are stored in the ``/etc/sites/mysite.com/parameter Loading this file is as simple as indicating the full file path when importing it from any other configuration file: -.. code-block:: yaml +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + imports: + - { resource: 'parameters.yml' } + - { resource: '/etc/sites/mysite.com/parameters.yml' } - # app/config/config.yml - imports: - - { resource: 'parameters.yml' } - - { resource: '/etc/sites/mysite.com/parameters.yml' } + # ... - # ... + .. code-block:: xml + + + + + + + + + + .. code-block:: php + + // app/config/config.php + $loader->import('parameters.yml'); + $loader->import('/etc/sites/mysite.com/parameters.yml'); + + // ... Most of the time, local developers won't have the same files that exist in the production servers. For that reason, the Config component provides the ``ignore_errors`` option to silently discard errors when the loaded file doesn't exist: -.. code-block:: yaml +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + imports: + - { resource: 'parameters.yml' } + - { resource: '/etc/sites/mysite.com/parameters.yml', ignore_errors: true } - # app/config/config.yml - imports: - - { resource: 'parameters.yml' } - - { resource: '/etc/sites/mysite.com/parameters.yml', ignore_errors: true } + # ... + + .. code-block:: xml + + + + + + + + + + .. code-block:: php + + // app/config/config.php + $loader->import('parameters.yml'); + $loader->import('/etc/sites/mysite.com/parameters.yml', null, true); + + // ... - # ... +As you've seen, there are lots of ways to organize your configuration files. You +can choose one of these or even create your own custom way of organizing the +files. Don't feel limited by the standard edition that comes with Symfony. For even +more customization, see ":doc:`dir_structure`". diff --git a/cookbook/map.rst.inc b/cookbook/map.rst.inc index 9eb4b0ab330..fd2cad7623c 100644 --- a/cookbook/map.rst.inc +++ b/cookbook/map.rst.inc @@ -30,6 +30,7 @@ * :doc:`/cookbook/configuration/pdo_session_storage` * :doc:`/cookbook/configuration/apache_router` * :doc:`/cookbook/configuration/web_server_configuration` + * :doc:`/cookbook/configuration/configuration_organization` * :doc:`/cookbook/console/index` From 2a32b2331a927c250de881dcfdb74e66c04abffb Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 2 Jun 2014 22:31:55 +0200 Subject: [PATCH 3/9] Added the latest suggestions made by reviewers --- .../configuration_organization.rst | 186 +++++++++++------- 1 file changed, 119 insertions(+), 67 deletions(-) diff --git a/cookbook/configuration/configuration_organization.rst b/cookbook/configuration/configuration_organization.rst index 1850d0a9aed..277a735a974 100644 --- a/cookbook/configuration/configuration_organization.rst +++ b/cookbook/configuration/configuration_organization.rst @@ -6,8 +6,8 @@ How to Organize Configuration Files The default Symfony2 Standard Edition defines three :doc:`execution environments ` called -``dev``, ``prod``, and ``test``. An environment simply represents a way to -execute the same codebase with different configuration. +``dev``, ``prod`` and ``test``. An environment simply represents a way to +execute the same codebase with different configurations. In order to select the configuration file to load for each environment, Symfony executes the ``registerContainerConfiguration()`` method of the ``AppKernel`` @@ -115,14 +115,21 @@ files, including the common files: .. code-block:: xml - - - - - - + + + - + + + + + + + + .. code-block:: php @@ -147,12 +154,21 @@ files, including the common files: .. code-block:: xml - - - - - - + + + + + + + + + + + + @@ -178,13 +194,20 @@ files, including the common files: .. code-block:: xml - - - - - + + + - + + + + + + + .. code-block:: php @@ -243,14 +266,15 @@ make Symfony aware of the new file organization:: } Following the same technique explained in the previous section, make sure to -load the appropriate configuration files from each main file (``common.yml``, +import the appropriate configuration files from each main file (``common.yml``, ``dev.yml`` and ``prod.yml``). -Advanced Tecniques ------------------- +Advanced Techniques +------------------- -Symfony loads configuration files using the ``Config component ``, -which provides some advanced features. +Symfony loads configuration files using the +``Config component ``, which provides some +advanced features. Mix and Match Configuration Formats ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -273,15 +297,22 @@ format (``.yml``, ``.xml``, ``.php``, ``.ini``): .. code-block:: xml - - - - - - - + + + - + + + + + + + + + .. code-block:: php @@ -297,8 +328,8 @@ format (``.yml``, ``.xml``, ``.php``, ``.ini``): The ``IniFileLoader`` parses the file contents using the :phpfunction:`parse_ini_file` function, therefore, you can only set - parameters to string values. To set parameters to other data types - (e.g. boolean, integer, etc), the other loaders are recommended. + parameters to string values. Use one of the other loaders if you want + to use other data types (e.g. boolean, integer, etc.). If you use any other configuration format, you have to define your own loader class extending it from :class:`Symfony\\Component\\DependencyInjection\\Loader\\FileLoader`. @@ -319,20 +350,27 @@ by loading an entire directory: # app/config/config.yml imports: - - { resource: 'bundles/' } - - { resource: 'services/' } + - { resource: 'bundles/' } + - { resource: 'services/' } # ... .. code-block:: xml - - - - - + + + - + + + + + + + .. code-block:: php @@ -343,18 +381,18 @@ by loading an entire directory: // ... -The Config component will look for recursively in the ``bundles/`` and ``services/`` +The Config component will recursively look in the ``bundles/`` and ``services/`` directories and it will load any supported file format (``.yml``, ``.xml``, ``.php``, ``.ini``). Global Configuration Files ~~~~~~~~~~~~~~~~~~~~~~~~~~ -Some system administrators may prefer to store sensitive parameteres in global -configuration files under the ``/etc`` directory. Imagine that the database -credentials for your website are stored in the ``/etc/sites/mysite.com/parameters.yml``. -Loading this file is as simple as indicating the full file path when importing -it from any other configuration file: +Some system administrators may prefer to store sensitive parameters in files +outside the project directory. Imagine that the database credentials for your +website are stored in the ``/etc/sites/mysite.com/parameters.yml``. Loading this +file is as simple as indicating the full file path when importing it from any +other configuration file: .. configuration-block:: @@ -362,20 +400,27 @@ it from any other configuration file: # app/config/config.yml imports: - - { resource: 'parameters.yml' } - - { resource: '/etc/sites/mysite.com/parameters.yml' } + - { resource: 'parameters.yml' } + - { resource: '/etc/sites/mysite.com/parameters.yml' } # ... .. code-block:: xml - - - - - + + + - + + + + + + + .. code-block:: php @@ -385,7 +430,7 @@ it from any other configuration file: // ... -Most of the time, local developers won't have the same files that exist in the +Most of the time, local developers won't have the same files that exist on the production servers. For that reason, the Config component provides the ``ignore_errors`` option to silently discard errors when the loaded file doesn't exist: @@ -396,20 +441,27 @@ doesn't exist: # app/config/config.yml imports: - - { resource: 'parameters.yml' } - - { resource: '/etc/sites/mysite.com/parameters.yml', ignore_errors: true } + - { resource: 'parameters.yml' } + - { resource: '/etc/sites/mysite.com/parameters.yml', ignore_errors: true } # ... .. code-block:: xml - - - - - + + + - + + + + + + + .. code-block:: php From 4a87cfb02bef83061577f8ef1fa3d5a807f0d9e5 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 2 Jun 2014 22:52:24 +0200 Subject: [PATCH 4/9] Fixed the link to another cookbook article --- cookbook/configuration/configuration_organization.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cookbook/configuration/configuration_organization.rst b/cookbook/configuration/configuration_organization.rst index 277a735a974..91f9b59ef5f 100644 --- a/cookbook/configuration/configuration_organization.rst +++ b/cookbook/configuration/configuration_organization.rst @@ -273,7 +273,7 @@ Advanced Techniques ------------------- Symfony loads configuration files using the -``Config component ``, which provides some +:doc:`Config component `, which provides some advanced features. Mix and Match Configuration Formats From af5d47826899c40551d6ce19ee095e39502f77f3 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Tue, 3 Jun 2014 08:49:24 +0200 Subject: [PATCH 5/9] Added suggestions made by @cordoval --- cookbook/configuration/configuration_organization.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/cookbook/configuration/configuration_organization.rst b/cookbook/configuration/configuration_organization.rst index 91f9b59ef5f..7384ac97358 100644 --- a/cookbook/configuration/configuration_organization.rst +++ b/cookbook/configuration/configuration_organization.rst @@ -84,7 +84,8 @@ name as the environment: ├─ vendor/ └─ web/ -To make it work, change the code of the ``registerContainerConfiguration()`` +To make this work, change the code of the +:method:`Symfony\\Component\\HttpKernel\\KernelInterface::registerContainerConfiguration` method:: // app/AppKernel.php @@ -107,7 +108,7 @@ files, including the common files: # app/config/dev/config.yml imports: - - { resource: '../common/config.yml' } + - { resource: '../common/config.yml' } - { resource: 'parameters.yml' } - { resource: 'security.yml' } @@ -222,7 +223,7 @@ Semantic Configuration Files A different organization strategy may be needed for complex applications with large configuration files. For instance, you could create one file per bundle -and several files to define all the application services: +and several files to define all application services: .. code-block:: text @@ -473,5 +474,5 @@ doesn't exist: As you've seen, there are lots of ways to organize your configuration files. You can choose one of these or even create your own custom way of organizing the -files. Don't feel limited by the standard edition that comes with Symfony. For even +files. Don't feel limited by the Standard Edition that comes with Symfony. For even more customization, see ":doc:`dir_structure`". From da3e1d0c8595bb2a88266438186cf9f389131a14 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Tue, 3 Jun 2014 09:01:28 +0200 Subject: [PATCH 6/9] Fixed the target of one cookbook article link --- cookbook/configuration/configuration_organization.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cookbook/configuration/configuration_organization.rst b/cookbook/configuration/configuration_organization.rst index 7384ac97358..cc866b0221d 100644 --- a/cookbook/configuration/configuration_organization.rst +++ b/cookbook/configuration/configuration_organization.rst @@ -475,4 +475,4 @@ doesn't exist: As you've seen, there are lots of ways to organize your configuration files. You can choose one of these or even create your own custom way of organizing the files. Don't feel limited by the Standard Edition that comes with Symfony. For even -more customization, see ":doc:`dir_structure`". +more customization, see ":doc:`/cookbook/configuration/override_dir_structure`". From be414e046c8d7338af99aa408dfd1caf2c56c6bf Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Tue, 3 Jun 2014 12:18:21 +0200 Subject: [PATCH 7/9] Removed the "Directory Loading" section because it doesn't work out of the box --- .../configuration_organization.rst | 48 ------------------- 1 file changed, 48 deletions(-) diff --git a/cookbook/configuration/configuration_organization.rst b/cookbook/configuration/configuration_organization.rst index cc866b0221d..8072c686544 100644 --- a/cookbook/configuration/configuration_organization.rst +++ b/cookbook/configuration/configuration_organization.rst @@ -338,54 +338,6 @@ When the configuration values are dynamic, you can use the PHP configuration file to execute your own logic. In addition, you can define your own services to load configuration from databases and web services. -Directory Loading -~~~~~~~~~~~~~~~~~ - -Splitting configuration into lots of smaller files can rapidly become cumbersome -when importing those files from the main configuration file. Avoid these problems -by loading an entire directory: - -.. configuration-block:: - - .. code-block:: yaml - - # app/config/config.yml - imports: - - { resource: 'bundles/' } - - { resource: 'services/' } - - # ... - - .. code-block:: xml - - - - - - - - - - - - - - .. code-block:: php - - // app/config/config.php - $loader->import('bundles/'); - $loader->import('services/'); - - // ... - - -The Config component will recursively look in the ``bundles/`` and ``services/`` -directories and it will load any supported file format (``.yml``, ``.xml``, -``.php``, ``.ini``). - Global Configuration Files ~~~~~~~~~~~~~~~~~~~~~~~~~~ From 68a7d2a5b83236f03c0a81ebde9ee473a56be15a Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 4 Jun 2014 20:42:51 +0200 Subject: [PATCH 8/9] Added more suggestions made by @xabbuh --- .../configuration_organization.rst | 33 ++++++++++++------- 1 file changed, 21 insertions(+), 12 deletions(-) diff --git a/cookbook/configuration/configuration_organization.rst b/cookbook/configuration/configuration_organization.rst index 8072c686544..3e3f92c9839 100644 --- a/cookbook/configuration/configuration_organization.rst +++ b/cookbook/configuration/configuration_organization.rst @@ -14,6 +14,9 @@ executes the ``registerContainerConfiguration()`` method of the ``AppKernel`` class:: // app/AppKernel.php + use Symfony\Component\HttpKernel\Kernel; + use Symfony\Component\Config\Loader\LoaderInterface; + class AppKernel extends Kernel { // ... @@ -89,6 +92,9 @@ To make this work, change the code of the method:: // app/AppKernel.php + use Symfony\Component\HttpKernel\Kernel; + use Symfony\Component\Config\Loader\LoaderInterface; + class AppKernel extends Kernel { // ... @@ -110,7 +116,7 @@ files, including the common files: imports: - { resource: '../common/config.yml' } - { resource: 'parameters.yml' } - - { resource: 'security.yml' } + - { resource: 'security.yml' } # ... @@ -147,9 +153,9 @@ files, including the common files: # app/config/prod/config.yml imports: - - { resource: '../common/config.yml' } + - { resource: '../common/config.yml' } - { resource: 'parameters.yml' } - - { resource: 'security.yml' } + - { resource: 'security.yml' } # ... @@ -189,7 +195,7 @@ files, including the common files: # app/config/config.yml imports: - { resource: 'parameters.yml' } - - { resource: 'security.yml' } + - { resource: 'security.yml' } # ... @@ -256,6 +262,9 @@ Again, change the code of the ``registerContainerConfiguration()`` method to make Symfony aware of the new file organization:: // app/AppKernel.php + use Symfony\Component\HttpKernel\Kernel; + use Symfony\Component\Config\Loader\LoaderInterface; + class AppKernel extends Kernel { // ... @@ -290,9 +299,9 @@ format (``.yml``, ``.xml``, ``.php``, ``.ini``): # app/config/config.yml imports: - { resource: 'parameters.yml' } - - { resource: 'services.xml' } - - { resource: 'security.yml' } - - { resource: 'legacy.php' } + - { resource: 'services.xml' } + - { resource: 'security.yml' } + - { resource: 'legacy.php' } # ... @@ -328,7 +337,7 @@ format (``.yml``, ``.xml``, ``.php``, ``.ini``): .. caution:: The ``IniFileLoader`` parses the file contents using the - :phpfunction:`parse_ini_file` function, therefore, you can only set + :phpfunction:`parse_ini_file` function. Therefore, you can only set parameters to string values. Use one of the other loaders if you want to use other data types (e.g. boolean, integer, etc.). @@ -336,16 +345,16 @@ If you use any other configuration format, you have to define your own loader class extending it from :class:`Symfony\\Component\\DependencyInjection\\Loader\\FileLoader`. When the configuration values are dynamic, you can use the PHP configuration file to execute your own logic. In addition, you can define your own services -to load configuration from databases and web services. +to load configurations from databases or web services. Global Configuration Files ~~~~~~~~~~~~~~~~~~~~~~~~~~ Some system administrators may prefer to store sensitive parameters in files outside the project directory. Imagine that the database credentials for your -website are stored in the ``/etc/sites/mysite.com/parameters.yml``. Loading this -file is as simple as indicating the full file path when importing it from any -other configuration file: +website are stored in the ``/etc/sites/mysite.com/parameters.yml`` file. Loading +this file is as simple as indicating the full file path when importing it from +any other configuration file: .. configuration-block:: From 4241ee5d0ca57c475e2663a28cbdfac1fbd7bed7 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 4 Jun 2014 22:49:48 +0200 Subject: [PATCH 9/9] Removed redundant configuration blocks --- .../configuration_organization.rst | 80 +------------------ 1 file changed, 2 insertions(+), 78 deletions(-) diff --git a/cookbook/configuration/configuration_organization.rst b/cookbook/configuration/configuration_organization.rst index 3e3f92c9839..52c5c0f0d4a 100644 --- a/cookbook/configuration/configuration_organization.rst +++ b/cookbook/configuration/configuration_organization.rst @@ -106,7 +106,8 @@ method:: } Then, make sure that each ``config.yml`` file loads the rest of the configuration -files, including the common files: +files, including the common files. For instance, this would be the imports +needed for the ``app/config/dev/config.yml`` file: .. configuration-block:: @@ -147,83 +148,6 @@ files, including the common files: // ... -.. configuration-block:: - - .. code-block:: yaml - - # app/config/prod/config.yml - imports: - - { resource: '../common/config.yml' } - - { resource: 'parameters.yml' } - - { resource: 'security.yml' } - - # ... - - .. code-block:: xml - - - - - - - - - - - - - - - - - .. code-block:: php - - // app/config/prod/config.php - $loader->import('../common/config.php'); - $loader->import('parameters.php'); - $loader->import('security.php'); - - // ... - -.. configuration-block:: - - .. code-block:: yaml - - # app/config/config.yml - imports: - - { resource: 'parameters.yml' } - - { resource: 'security.yml' } - - # ... - - .. code-block:: xml - - - - - - - - - - - - - - .. code-block:: php - - // app/config/config.php - $loader->import('parameters.php'); - $loader->import('security.php'); - - // ... - Semantic Configuration Files ----------------------------