Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 6fd1c27

Browse filesBrowse files
weaverryanweaverryan
committed
Merge branch '2.1'
2 parents 65f33b7 + c893ed4 commit 6fd1c27
Copy full SHA for 6fd1c27

File tree

Expand file treeCollapse file tree

10 files changed

+176
-11
lines changed
Filter options
Expand file treeCollapse file tree

10 files changed

+176
-11
lines changed

‎book/routing.rst

Copy file name to clipboardExpand all lines: book/routing.rst
+4-2Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -179,8 +179,10 @@ file:
179179
.. tip::
180180

181181
Even though all routes are loaded from a single file, it's common practice
182-
to include additional routing resources from inside the file. See the
183-
:ref:`routing-include-external-resources` section for more information.
182+
to include additional routing resources. To do so, just point out in the
183+
main routing configuration file which external files should be included.
184+
See the :ref:`routing-include-external-resources` section for more
185+
information.
184186

185187
Basic Route Configuration
186188
~~~~~~~~~~~~~~~~~~~~~~~~~

‎book/templating.rst

Copy file name to clipboardExpand all lines: book/templating.rst
+1-1Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -644,7 +644,7 @@ Asynchronous Content with hinclude.js
644644
.. versionadded:: 2.1
645645
hinclude.js support was added in Symfony 2.1
646646

647-
Controllers can be embedded asyncronous using the hinclude.js_ javascript library.
647+
Controllers can be embedded asyncronously using the hinclude.js_ javascript library.
648648
As the embedded content comes from another page (or controller for that matter),
649649
Symfony2 uses the standard ``render`` helper to configure ``hinclude`` tags:
650650

‎components/config/definition.rst

Copy file name to clipboardExpand all lines: components/config/definition.rst
+163Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -212,6 +212,168 @@ For all nodes:
212212
``cannotBeOverwritten()``
213213
don’t let other configuration arrays overwrite an existing value for this node
214214

215+
Appending sections
216+
------------------
217+
218+
If you have a complex configuration to validate then the tree can grow to
219+
be large and you may want to split it up into sections. You can do this by
220+
making a section a separate node and then appending it into the main tree
221+
with ``append()``::
222+
223+
public function getConfigTreeBuilder()
224+
{
225+
$treeBuilder = new TreeBuilder();
226+
$rootNode = $treeBuilder->root('database');
227+
228+
$rootNode
229+
->arrayNode('connection')
230+
->children()
231+
->scalarNode('driver')
232+
->isRequired()
233+
->cannotBeEmpty()
234+
->end()
235+
->scalarNode('host')
236+
->defaultValue('localhost')
237+
->end()
238+
->scalarNode('username')->end()
239+
->scalarNode('password')->end()
240+
->booleanNode('memory')
241+
->defaultFalse()
242+
->end()
243+
->end()
244+
->append($this->addParametersNode())
245+
->end()
246+
;
247+
248+
return $treeBuilder;
249+
}
250+
251+
public function addParametersNode()
252+
{
253+
$builder = new TreeBuilder();
254+
$node = $builder->root('parameters');
255+
256+
$node
257+
->isRequired()
258+
->requiresAtLeastOneElement()
259+
->useAttributeAsKey('name')
260+
->prototype('array')
261+
->children()
262+
->scalarNode('name')->isRequired()->end()
263+
->scalarNode('value')->isRequired()->end()
264+
->end()
265+
->end()
266+
;
267+
268+
return $node;
269+
}
270+
271+
This is also useful to help you avoid repeating yourself if you have sections
272+
of the config that are repeated in different places.
273+
274+
Normalization
275+
-------------
276+
277+
When the config files are processed they are first normalized, then merged
278+
and finally the tree is used to validate the resulting array. The normalization
279+
process is used to remove some of the differences that result from different
280+
configuration formats, mainly the differences between Yaml and XML.
281+
282+
The separator used in keys is typically ``_`` in Yaml and ``-`` in XML. For
283+
example, ``auto_connect`` in Yaml and ``auto-connect``. The normalization would
284+
make both of these ``auto_connect``.
285+
286+
Another difference between Yaml and XML is in the way arrays of values may
287+
be represented. In Yaml you may have:
288+
289+
.. code-block:: yaml
290+
291+
twig:
292+
extensions: ['twig.extension.foo', 'twig.extension.bar']
293+
294+
and in XML:
295+
296+
.. code-block:: xml
297+
298+
<twig:config>
299+
<twig:extension>twig.extension.foo</twig:extension>
300+
<twig:extension>twig.extension.bar</twig:extension>
301+
</twig:config>
302+
303+
This difference can be removed in normalization by pluralizing the key used
304+
in XML. You can specify that you want a key to be pluralized in this way with
305+
``fixXmlConfig()``::
306+
307+
$rootNode
308+
->fixXmlConfig('extension')
309+
->children()
310+
->arrayNode('extensions')
311+
->prototype('scalar')->end()
312+
->end()
313+
->end()
314+
;
315+
316+
If it is an irregular pluralization you can specify the plural to use as
317+
a second argument::
318+
319+
$rootNode
320+
->fixXmlConfig('child', 'children')
321+
->children()
322+
->arrayNode('children')
323+
->end()
324+
;
325+
326+
As well as fixing this, ``fixXmlConfig`` ensures that single xml elements
327+
are still turned into an array. So you may have:
328+
329+
.. code-block:: xml
330+
331+
<connection>default</connection>
332+
<connection>extra</connection>
333+
334+
and sometimes only:
335+
336+
.. code-block:: xml
337+
338+
<connection>default</connection>
339+
340+
By default ``connection`` would be an array in the first case and a string
341+
in the second making it difficult to validate. You can ensure it is always
342+
an array with with ``fixXmlConfig``.
343+
344+
You can further control the normalization process if you need to. For example,
345+
you may want to allow a string to be set and used as a particular key or several
346+
keys to be set explicitly. So that, if everything apart from id is optional in this
347+
config:
348+
349+
.. code-block:: yaml
350+
351+
connection:
352+
name: my_mysql_connection
353+
host: localhost
354+
driver: mysql
355+
username: user
356+
password: pass
357+
358+
you can allow the following as well:
359+
360+
.. code-block:: yaml
361+
362+
connection: my_mysql_connection
363+
364+
By changing a string value into an associative array with ``name`` as the key::
365+
366+
$rootNode
367+
->arrayNode('connection')
368+
->beforeNormalization()
369+
->ifString()
370+
->then(function($v) { return array('name'=> $v); })
371+
->end()
372+
->scalarValue('name')->isRequired()
373+
// ...
374+
->end()
375+
;
376+
215377
Validation rules
216378
----------------
217379

@@ -278,3 +440,4 @@ Otherwise the result is a clean array of configuration values::
278440
$processor = new Processor();
279441
$configuration = new DatabaseConfiguration;
280442
$processedConfiguration = $processor->processConfiguration($configuration, $configs);
443+

‎components/dependency_injection/compilation.rst

Copy file name to clipboardExpand all lines: components/dependency_injection/compilation.rst
+1-1Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -278,7 +278,7 @@ will then be called when the container is compiled::
278278
.. note::
279279

280280
Compiler passes are registered differently is you are using the full
281-
stack framework, see :doc:`cookbook/service_container/compiler_passes`
281+
stack framework, see :doc:`/cookbook/service_container/compiler_passes`
282282
for more details.
283283

284284
Controlling the Pass Ordering

‎components/dependency_injection/tags.rst

Copy file name to clipboardExpand all lines: components/dependency_injection/tags.rst
+1-1Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -161,7 +161,7 @@ run when the container is compiled::
161161
.. note::
162162

163163
Compiler passes are registered differently is you are using the full
164-
stack framework, see :doc:`cookbook/service_container/compiler_passes`
164+
stack framework, see :doc:`/cookbook/service_container/compiler_passes`
165165
for more details.
166166

167167
Adding additional attributes on Tags

‎components/http_foundation/sessions.rst

Copy file name to clipboardExpand all lines: components/http_foundation/sessions.rst
+1-1Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -200,7 +200,7 @@ the array::
200200
$tokens['c'] = $value;
201201
$session->set('tokens', $tokens);
202202

203-
With structured namespacing, the the key can be translated to the array
203+
With structured namespacing, the key can be translated to the array
204204
structure like this using a namespace character (defaults to `/`)::
205205

206206
$session->set('tokens/c', $value);

‎components/map.rst.inc

Copy file name to clipboardExpand all lines: components/map.rst.inc
+1-1Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@
3131

3232
* **DOM Crawler**
3333

34-
* :doc:`/components/dom_crawler`
34+
* :doc:`/components/dom_crawler`
3535

3636
* :doc:`/components/event_dispatcher/index`
3737

‎components/process.rst

Copy file name to clipboardExpand all lines: components/process.rst
+1-1Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ a command in a sub-process::
2828
$process->setTimeout(3600);
2929
$process->run();
3030
if (!$process->isSuccessful()) {
31-
throw new RuntimeException($process->getErrorOutput());
31+
throw new \RuntimeException($process->getErrorOutput());
3232
}
3333

3434
print $process->getOutput();

‎contributing/code/conventions.rst

Copy file name to clipboardExpand all lines: contributing/code/conventions.rst
+2-2Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -74,5 +74,5 @@ must be used instead (where ``XXX`` is the name of the related thing):
7474

7575
While "setXXX" and "replaceXXX" are very similar, there is one notable
7676
difference: "setXXX" may replace, or add new elements to the relation.
77-
"replaceXXX" on the other hand is specifically forbidden to add new
78-
elements, but most throw an exception in these cases.
77+
"replaceXXX", on the other hand, cannot add new elements. If an unrecognized
78+
key as passed to "replaceXXX" it must throw an exception.

‎contributing/code/standards.rst

Copy file name to clipboardExpand all lines: contributing/code/standards.rst
+1-1Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -96,7 +96,7 @@ Naming Conventions
9696
* Use camelCase, not underscores, for variable, function and method
9797
names, arguments;
9898

99-
* Use underscores for option, parameter names;
99+
* Use underscores for option names and parameter names;
100100

101101
* Use namespaces for all classes;
102102

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.