.. index::

single: Config; Caching based on resources

Caching based on resources

When all configuration resources are loaded, you may want to process the configuration values and

combine them all in one file. This file acts like a cache. It’s contents don’t have to be

regenerated every time the application runs – only when the configuration resources are modified.

For example, the Symfony Routing component allows you to load all routes, and then dump a URL

matcher or a URL generator based on these routes. In this case, when one of the resources is

modified (and you are working in a development environment), the generated file should be

invalidated and regenerated. This can be accomplished by making use of the

:class:`Symfony\\Component\\Config\\ConfigCache` class.

The example below shows you how to collect resources, then generate some code based on the

resources that were loaded, and write this code to the cache. The cache also receives the

collection of resources that were used for generating the code. By looking at the “last modified”

timestamp of these resources, the cache can tell if it is still fresh or that it’s contents should

be regenerated.

.. code-block:: php

A ``.meta`` file is created in the same directory as the cache file itself. This ``.meta`` file

contains the serialized resources, for later reference.

.. index::

single: Config; Define and process configuration values

Define and process configuration values

Validate configuration values

After loading configuration values from all kinds of resources, the values and their structure can

be validated using the "Definition" part of the Config Component. Configuration values are usually

expected to show some kind of hierarchy. Also, values should be of a certain type, be restricted in

number or be one of a given set of values. For example, the following configuration (in Yaml) shows

a clear hierarchy and some validation rules that should be applied to it (like: "the value for

'auto_connect' must be a boolean value"):

.. code-block:: yaml

When loading multiple configuration files, it should be possible to merge and overwrite some

values. Other values should not be merged and stay as they are when first encountered. Also,

some keys are only available, when another key has a specific value (in the sample configuration

above: the "memory" key only makes sense when the "driver" is "sqlite").

Define a hierarchy of configuration values using the TreeBuilder

All the rules concerning configuration values can be defined using the

:class:`Symfony\\Component\\Config\\Definition\\Builder\\TreeBuilder`.

A :class:`Symfony\\Component\\Config\\Definition\\Builder\\TreeBuilder` instance should be returned

from a custom ``Configuration`` class which implements the

:class:`Symfony\\Component\\Config\\Definition\\ConfigurationInterface`:

.. code-block:: php

Add node definitions to the tree

Variable nodes

A tree contains node definitions which can be layed out in a semantic way. This means, using

indentation and the fluent notation, it is possible to reflect the real structure of the

configuration values:

.. code-block:: php

The root node itself is an array node, and has children, like the boolean node "auto_connect"

and the scalar node "default_connection". In general: after defining a node, a call to ``end()``

takes you one step up in the hierarchy.

Array nodes

It is possible to add a deeper level to the hierarchy, by adding an array node. The array node

itself, may have a pre-defined set of variable nodes:

.. code-block:: php

Or you may define a prototype for each node inside an array node:

.. code-block:: php

A prototype can be used to add a definition which may be repeated many times inside the current

node. According to the prototype definition in the example above, it is possible to have multiple

connection arrays (containing a "driver", "host", etc.).

Array node options

Before defining the children of an array node, you can provide options like:

``useAttributeAsKey()``

Provide the name of a childnode, whose value should be used as the key in the resulting array

``requiresAtLeastOneElement()``

There should be at least one element in the array (works only when ``isRequired()`` is also

called).

An example of this:

.. code-block:: php

Default and required values

For all node types, it is possible to define default values and replacement values in case a node

has a certain value:

``defaultValue()``

Set a default value

``isRequired()``

Must be defined (but may be empty)

``cannotBeEmpty()``

may not contain an empty value

``default*()``

(``Null``, ``True``, ``False``), shortcut for ``defaultValue()``

``treat*Like()``

(``Null``, ``True``, ``False``), provide a replacement value in case the value is *.

.. code-block:: php

Merging options

Extra options concerning the merge process may be provided. For arrays:

``performNoDeepMerging()``

When the value is also defined in a second configuration array, don’t try to merge an array,

but overwrite it entirely

For all nodes:

``cannotBeOverwritten()``

don’t let other configuration arrays overwrite an existing value for this node

Validation rules

More advanced validation rules can be provided using the

:class:`Symfony\\Component\\Config\\Definition\\Builder\\ExprBuilder`. This builder implements a

fluent interface for a well-known control structure. The builder is used for adding advanced

validation rules to node definitions, like:

.. code-block:: php

A validation rule always has an "if" part. You can specify this part in the following ways:

- ``ifTrue()``

- ``ifString()``

- ``ifNull()``

- ``ifArray()``

- ``ifInArray()``

- ``ifNotInArray()``

A validation rule also requires a "then" part:

- ``then()``

- ``thenEmptyArray()``

- ``thenInvalid()``

- ``thenUnset()``

The only exception is of course:

- ``always()``

Usually, “then” is a closure. It’s return value will be used as a new value for the node, instead

of the node’s original value.

Processing configuration values

The :class:`Symfony\\Component\\Config\\Definition\\Processor` uses the tree as it was built

using the :class:`Symfony\\Component\\Config\\Definition\\Builder\\TreeBuilder` to process

multiple arrays of configuration values that should be merged. If any value is not of the

expected type, is mandatory and yet undefined, or could not be validated in some other way,

an exception will be thrown. Otherwise the result is a clean array of configuration values.

.. code-block:: php

Config

.. toctree::

:maxdepth: 2

introduction

resources

caching

definition

.. index::

single: Config

The Config Component

Introduction

The Config Component provides several classes to help you find, load, combine, autofill and

validate configuration values of any kind, whatever their source may be (Yaml, XML, INI files, or

for instance a database).

Installation

You can install the component in many different ways:

* Use the official Git repository (https://github.com/symfony/Config);

* Install it via PEAR ( `pear.symfony.com/Config`);

* Install it via Composer (`symfony/config` on Packagist).