Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit cf7da60

Browse files
weaverryanweaverryan
committed
Merge branch '2.0'
2 parents c7f3353 + 75aa9d6 commit cf7da60

File tree

10 files changed

+694
-1
lines changed

10 files changed

+694
-1
lines changed

‎components/config/caching.rst

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
.. index::
2+
single: Config; Caching based on resources
3+
4+
Caching based on resources
5+
==========================
6+
7+
When all configuration resources are loaded, you may want to process the configuration
8+
values and combine them all in one file. This file acts like a cache. Its
9+
contents don’t have to be regenerated every time the application runs – only
10+
when the configuration resources are modified.
11+
12+
For example, the Symfony Routing component allows you to load all routes,
13+
and then dump a URL matcher or a URL generator based on these routes. In
14+
this case, when one of the resources is modified (and you are working in a
15+
development environment), the generated file should be invalidated and regenerated.
16+
This can be accomplished by making use of the :class:`Symfony\\Component\\Config\\ConfigCache`
17+
class.
18+
19+
The example below shows you how to collect resources, then generate some code
20+
based on the resources that were loaded, and write this code to the cache. The
21+
cache also receives the collection of resources that were used for generating
22+
the code. By looking at the "last modified" timestamp of these resources,
23+
the cache can tell if it is still fresh or that its contents should be regenerated::
24+
25+
use Symfony\Component\Config\ConfigCache;
26+
use Symfony\Component\Config\Resource\FileResource;
27+
28+
$cachePath = __DIR__.'/cache/appUserMatcher.php';
29+
30+
// the second argument indicates whether or not we are in debug mode
31+
$userMatcherCache = new ConfigCache($cachePath, true);
32+
33+
if (!$userMatcherCache->isFresh()) {
34+
// fill this with an array of 'users.yml' file paths
35+
$yamlUserFiles = ...;
36+
37+
$resources = array();
38+
39+
foreach ($yamlUserFiles as $yamlUserFile) {
40+
$delegatingLoader->load($yamlUserFile);
41+
$resources[] = new FileResource($yamlUserFile);
42+
}
43+
44+
// the code for the UserMatcher is generated elsewhere
45+
$code = ...;
46+
47+
$userMatcherCache->write($code, $resources);
48+
}
49+
50+
// you may want to require the cached code:
51+
require $cachePath;
52+
53+
In debug mode, a ``.meta`` file will be created in the same directory as the
54+
cache file itself. This ``.meta`` file contains the serialized resources,
55+
whose timestamps are used to determine if the cache is still fresh. When not
56+
in debug mode, the cache is considered to be "fresh" as soon as it exists,
57+
and therefore no ``.meta`` file will be generated.

‎components/config/definition.rst

Lines changed: 280 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,280 @@
1+
.. index::
2+
single: Config; Define and process configuration values
3+
4+
Define and process configuration values
5+
=======================================
6+
7+
Validate configuration values
8+
-----------------------------
9+
10+
After loading configuration values from all kinds of resources, the values
11+
and their structure can be validated using the "Definition" part of the Config
12+
Component. Configuration values are usually expected to show some kind of
13+
hierarchy. Also, values should be of a certain type, be restricted in number
14+
or be one of a given set of values. For example, the following configuration
15+
(in Yaml) shows a clear hierarchy and some validation rules that should be
16+
applied to it (like: "the value for ``auto_connect`` must be a boolean value"):
17+
18+
.. code-block:: yaml
19+
20+
auto_connect: true
21+
default_connection: mysql
22+
connections:
23+
mysql:
24+
host: localhost
25+
driver: mysql
26+
username: user
27+
password: pass
28+
sqlite:
29+
host: localhost
30+
driver: sqlite
31+
memory: true
32+
username: user
33+
password: pass
34+
35+
When loading multiple configuration files, it should be possible to merge
36+
and overwrite some values. Other values should not be merged and stay as
37+
they are when first encountered. Also, some keys are only available when
38+
another key has a specific value (in the sample configuration above: the
39+
``memory`` key only makes sense when the ``driver`` is ``sqlite``).
40+
41+
Define a hierarchy of configuration values using the TreeBuilder
42+
----------------------------------------------------------------
43+
44+
All the rules concerning configuration values can be defined using the
45+
:class:`Symfony\\Component\\Config\\Definition\\Builder\\TreeBuilder`.
46+
47+
A :class:`Symfony\\Component\\Config\\Definition\\Builder\\TreeBuilder` instance
48+
should be returned from a custom ``Configuration`` class which implements the
49+
:class:`Symfony\\Component\\Config\\Definition\\ConfigurationInterface`::
50+
51+
namespace Acme\DatabaseConfiguration;
52+
53+
use Symfony\Component\Config\Definition\ConfigurationInterface;
54+
use Symfony\Component\Config\Definition\Builder\TreeBuilder;
55+
56+
class DatabaseConfiguration implements ConfigurationInterface
57+
{
58+
public function getConfigTreeBuilder()
59+
{
60+
$treeBuilder = new TreeBuilder();
61+
$rootNode = $treeBuilder->root('database');
62+
63+
// ... add node definitions to the root of the tree
64+
65+
return $treeBuilder;
66+
}
67+
}
68+
69+
Add node definitions to the tree
70+
--------------------------------
71+
72+
Variable nodes
73+
~~~~~~~~~~~~~~
74+
75+
A tree contains node definitions which can be layed out in a semantic way.
76+
This means, using indentation and the fluent notation, it is possible to
77+
reflect the real structure of the configuration values::
78+
79+
$rootNode
80+
->children()
81+
->booleanNode('auto_connect')
82+
->defaultTrue()
83+
->end()
84+
->scalarNode('default_connection')
85+
->defaultValue('default')
86+
->end()
87+
->end()
88+
;
89+
90+
The root node itself is an array node, and has children, like the boolean
91+
node ``auto_connect`` and the scalar node ``default_connection``. In general:
92+
after defining a node, a call to ``end()`` takes you one step up in the hierarchy.
93+
94+
Array nodes
95+
~~~~~~~~~~~
96+
97+
It is possible to add a deeper level to the hierarchy, by adding an array
98+
node. The array node itself, may have a pre-defined set of variable nodes:
99+
100+
.. code-block:: php
101+
102+
$rootNode
103+
->arrayNode('connection')
104+
->scalarNode('driver')->end()
105+
->scalarNode('host')->end()
106+
->scalarNode('username')->end()
107+
->scalarNode('password')->end()
108+
->end()
109+
;
110+
111+
Or you may define a prototype for each node inside an array node:
112+
113+
.. code-block:: php
114+
115+
$rootNode
116+
->arrayNode('connections')
117+
->prototype('array')
118+
->children()
119+
->scalarNode('driver')->end()
120+
->scalarNode('host')->end()
121+
->scalarNode('username')->end()
122+
->scalarNode('password')->end()
123+
->end()
124+
->end()
125+
->end()
126+
;
127+
128+
A prototype can be used to add a definition which may be repeated many times
129+
inside the current node. According to the prototype definition in the example
130+
above, it is possible to have multiple connection arrays (containing a ``driver``,
131+
``host``, etc.).
132+
133+
Array node options
134+
~~~~~~~~~~~~~~~~~~
135+
136+
Before defining the children of an array node, you can provide options like:
137+
138+
``useAttributeAsKey()``
139+
Provide the name of a child node, whose value should be used as the key in the resulting array
140+
``requiresAtLeastOneElement()``
141+
There should be at least one element in the array (works only when ``isRequired()`` is also
142+
called).
143+
144+
An example of this:
145+
146+
.. code-block:: php
147+
148+
$rootNode
149+
->arrayNode('parameters')
150+
->isRequired()
151+
->requiresAtLeastOneElement()
152+
->prototype('array')
153+
->useAttributeAsKey('name')
154+
->children()
155+
->scalarNode('name')->isRequired()->end()
156+
->scalarNode('value')->isRequired()->end()
157+
->end()
158+
->end()
159+
->end()
160+
;
161+
162+
Default and required values
163+
---------------------------
164+
165+
For all node types, it is possible to define default values and replacement
166+
values in case a node
167+
has a certain value:
168+
169+
``defaultValue()``
170+
Set a default value
171+
``isRequired()``
172+
Must be defined (but may be empty)
173+
``cannotBeEmpty()``
174+
May not contain an empty value
175+
``default*()``
176+
(``null``, ``true``, ``false``), shortcut for ``defaultValue()``
177+
``treat*Like()``
178+
(``null``, ``true``, ``false``), provide a replacement value in case the value is ``*.``
179+
180+
.. code-block:: php
181+
182+
$rootNode
183+
->arrayNode('connection')
184+
->children()
185+
->scalarNode('driver')
186+
->isRequired()
187+
->cannotBeEmpty()
188+
->end()
189+
->scalarNode('host')
190+
->defaultValue('localhost')
191+
->end()
192+
->scalarNode('username')->end()
193+
->scalarNode('password')->end()
194+
->booleanNode('memory')
195+
->defaultFalse()
196+
->end()
197+
->end()
198+
->end()
199+
;
200+
201+
Merging options
202+
---------------
203+
204+
Extra options concerning the merge process may be provided. For arrays:
205+
206+
``performNoDeepMerging()``
207+
When the value is also defined in a second configuration array, don’t
208+
try to merge an array, but overwrite it entirely
209+
210+
For all nodes:
211+
212+
``cannotBeOverwritten()``
213+
don’t let other configuration arrays overwrite an existing value for this node
214+
215+
Validation rules
216+
----------------
217+
218+
More advanced validation rules can be provided using the
219+
:class:`Symfony\\Component\\Config\\Definition\\Builder\\ExprBuilder`. This
220+
builder implements a fluent interface for a well-known control structure.
221+
The builder is used for adding advanced validation rules to node definitions, like::
222+
223+
$rootNode
224+
->arrayNode('connection')
225+
->children()
226+
->scalarNode('driver')
227+
->isRequired()
228+
->validate()
229+
->ifNotInArray(array('mysql', 'sqlite', 'mssql'))
230+
->thenInvalid('Invalid database driver "%s"')
231+
->end()
232+
->end()
233+
->end()
234+
->end()
235+
;
236+
237+
A validation rule always has an "if" part. You can specify this part in the
238+
following ways:
239+
240+
- ``ifTrue()``
241+
- ``ifString()``
242+
- ``ifNull()``
243+
- ``ifArray()``
244+
- ``ifInArray()``
245+
- ``ifNotInArray()``
246+
- ``always()``
247+
248+
A validation rule also requires a "then" part:
249+
250+
- ``then()``
251+
- ``thenEmptyArray()``
252+
- ``thenInvalid()``
253+
- ``thenUnset()``
254+
255+
Usually, "then" is a closure. Its return value will be used as a new value
256+
for the node, instead
257+
of the node's original value.
258+
259+
Processing configuration values
260+
-------------------------------
261+
262+
The :class:`Symfony\\Component\\Config\\Definition\\Processor` uses the tree
263+
as it was built using the :class:`Symfony\\Component\\Config\\Definition\\Builder\\TreeBuilder`
264+
to process multiple arrays of configuration values that should be merged.
265+
If any value is not of the expected type, is mandatory and yet undefined,
266+
or could not be validated in some other way, an exception will be thrown.
267+
Otherwise the result is a clean array of configuration values::
268+
269+
use Symfony\Component\Yaml\Yaml;
270+
use Symfony\Component\Config\Definition\Processor;
271+
use Acme\DatabaseConfiguration;
272+
273+
$config1 = Yaml::parse(__DIR__.'/src/Matthias/config/config.yml');
274+
$config2 = Yaml::parse(__DIR__.'/src/Matthias/config/config_extra.yml');
275+
276+
$configs = array($config1, $config2);
277+
278+
$processor = new Processor();
279+
$configuration = new DatabaseConfiguration;
280+
$processedConfiguration = $processor->processConfiguration($configuration, $configs);

‎components/config/index.rst

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
Config
2+
======
3+
4+
.. toctree::
5+
:maxdepth: 2
6+
7+
introduction
8+
resources
9+
caching
10+
definition

‎components/config/introduction.rst

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
.. index::
2+
single: Config
3+
4+
The Config Component
5+
====================
6+
7+
Introduction
8+
------------
9+
10+
The Config Component provides several classes to help you find, load, combine,
11+
autofill and validate configuration values of any kind, whatever their source
12+
may be (Yaml, XML, INI files, or for instance a database).
13+
14+
Installation
15+
------------
16+
17+
You can install the component in many different ways:
18+
19+
* Use the official Git repository (https://github.com/symfony/Config);
20+
* Install it via PEAR ( `pear.symfony.com/Config`);
21+
* Install it via Composer (`symfony/config` on Packagist).
22+
23+
Sections
24+
--------
25+
26+
* :doc:`/components/config/resources`
27+
* :doc:`/components/config/caching`
28+
* :doc:`/components/config/definition`

0 commit comments

Comments
 (0)