Skip to content

[RFR] Added "How to Organize Configuration Files" cookbook #3885

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 9 commits into from
Aug 16, 2014
Merged

[RFR] Added "How to Organize Configuration Files" cookbook #3885

Changes from 1 commit
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
0520bf1
Firest draft of the "How to Organize Configuration Files" cookbook
javiereguiluz May 28, 2014
d861be3
Added all the suggestions made by reviewers
javiereguiluz Jun 2, 2014
2a32b23
Added the latest suggestions made by reviewers
javiereguiluz Jun 2, 2014
4a87cfb
Fixed the link to another cookbook article
javiereguiluz Jun 2, 2014
af5d478
Added suggestions made by @cordoval
javiereguiluz Jun 3, 2014
da3e1d0
Fixed the target of one cookbook article link
javiereguiluz Jun 3, 2014
be414e0
Removed the "Directory Loading" section because it doesn't work out o…
javiereguiluz Jun 3, 2014
68a7d2a
Added more suggestions made by @xabbuh
javiereguiluz Jun 4, 2014
4241ee5
Removed redundant configuration blocks
javiereguiluz Jun 4, 2014
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Added the latest suggestions made by reviewers
  • Loading branch information
@javiereguiluz
javiereguiluz committed Jun 2, 2014
commit 2a32b2331a927c250de881dcfdb74e66c04abffb
186 changes: 119 additions & 67 deletions cookbook/configuration/configuration_organization.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,8 @@ How to Organize Configuration Files

The default Symfony2 Standard Edition defines three
:doc:`execution environments </cookbook/configuration/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``
Expand Down Expand Up @@ -115,14 +115,21 @@ files, including the common files:

.. code-block:: xml

<!-- # app/config/dev/config.xml -->
<imports>
<import resource="../common/config.xml" />
<import resource="parameters.xml" />
<import resource="security.xml" />
</imports>
<!-- app/config/dev/config.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/dic/services 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">

<!-- ... -->
<imports>
<import resource="../common/config.xml" />
<import resource="parameters.xml" />
<import resource="security.xml" />
</imports>

<!-- ... -->
</container>

.. code-block:: php

Expand All @@ -147,12 +154,21 @@ files, including the common files:

.. code-block:: xml

<!-- # app/config/prod/config.xml -->
<imports>
<import resource="../common/config.xml" />
<import resource="parameters.xml" />
<import resource="security.xml" />
</imports>
<!-- app/config/prod/config.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/dic/services 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">

<imports>
<import resource="../common/config.xml" />
<import resource="parameters.xml" />
<import resource="security.xml" />
</imports>

<!-- ... -->
</container>

<!-- ... -->

Expand All @@ -178,13 +194,20 @@ files, including the common files:

.. code-block:: xml

<!-- # app/config/config.xml -->
<imports>
<import resource="parameters.xml" />
<import resource="security.xml" />
</imports>
<!-- app/config/config.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/dic/services 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">

<!-- ... -->
<imports>
<import resource="parameters.xml" />
<import resource="security.xml" />
</imports>

<!-- ... -->
</container>

.. code-block:: php

Expand Down Expand Up @@ -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 </components/config>``,
which provides some advanced features.
Symfony loads configuration files using the
``Config component </components/config/introduction>``, which provides some
advanced features.

Mix and Match Configuration Formats
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Expand All @@ -273,15 +297,22 @@ format (``.yml``, ``.xml``, ``.php``, ``.ini``):

.. code-block:: xml

<!-- # app/config/config.xml -->
<imports>
<import resource="parameters.yml" />
<import resource="services.xml" />
<import resource="security.yml" />
<import resource="legacy.php" />
</imports>
<!-- app/config/config.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/dic/services 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">

<!-- ... -->
<imports>
<import resource="parameters.yml" />
<import resource="services.xml" />
<import resource="security.yml" />
<import resource="legacy.php" />
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it would be inconsistent since we don't do that in xml 😊

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wouodn't. Those are 2 very different things

</imports>

<!-- ... -->
</container>

.. code-block:: php

Expand All @@ -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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[...] function. Therefore, you [...]

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`.
Expand All @@ -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

<!-- # app/config/config.xml -->
<imports>
<import resource="bundles/" />
<import resource="services/" />
</imports>
<!-- app/config/config.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/dic/services 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">

<!-- ... -->
<imports>
<import resource="bundles/" />
<import resource="services/" />
</imports>

<!-- ... -->
</container>

.. code-block:: php

Expand All @@ -343,39 +381,46 @@ 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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[...] are stored in the [...] file.

file is as simple as indicating the full file path when importing it from any
other configuration file:

.. configuration-block::

.. code-block:: yaml

# 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' }
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The style of the YAML files should be consistent throughout the article.


# ...

.. code-block:: xml

<!-- # app/config/config.xml -->
<imports>
<import resource="parameters.yml" />
<import resource="/etc/sites/mysite.com/parameters.yml" />
</imports>
<!-- app/config/config.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/dic/services 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">

<!-- ... -->
<imports>
<import resource="parameters.yml" />
<import resource="/etc/sites/mysite.com/parameters.yml" />
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

maybe we can do a ClosureLoader that does not throw an exception when one of the imports does not exist, currently I don't know the behavior of this but that could also be a usecase to explore?, nevermind i see below the ignore errors 😊

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

has that ever existed or was plugged recently in which version, maybe add a note on it?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't understand what you mean. The way to ignore errors in case the file is missing is described in the next example

</imports>

<!-- ... -->
</container>

.. code-block:: php

Expand All @@ -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:
Expand All @@ -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

<!-- # app/config/config.xml -->
<imports>
<import resource="parameters.yml" />
<import resource="/etc/sites/mysite.com/parameters.yml" ignore-errors="true" />
</imports>
<!-- app/config/config.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/dic/services 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">

<!-- ... -->
<imports>
<import resource="parameters.yml" />
<import resource="/etc/sites/mysite.com/parameters.yml" ignore-errors="true" />
</imports>

<!-- ... -->
</container>

.. code-block:: php

Expand Down