From 0f8f9fdf0d6203dac18555fd1805fe2eff00fa40 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 25 May 2015 16:03:14 +0200 Subject: [PATCH 1/3] Documented the useAttributeAsKey() method --- components/config/definition.rst | 70 +++++++++++++++++++++++++------- 1 file changed, 55 insertions(+), 15 deletions(-) diff --git a/components/config/definition.rst b/components/config/definition.rst index b79ad3853a2..c6a26f35469 100644 --- a/components/config/definition.rst +++ b/components/config/definition.rst @@ -200,25 +200,58 @@ Array Node Options Before defining the children of an array node, you can provide options like: -``useAttributeAsKey()`` - Provide the name of a child node, 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). ``addDefaultsIfNotSet()`` - If any child nodes have default values, use them if explicit values haven't been provided. + If any child nodes have default values, use them if explicit values haven't + been provided. +``requiresAtLeastOneElement()`` + There should be at least one element in the array (works only when + ``isRequired()`` is also called). +``useAttributeAsKey()`` + Provide the name of a child node, whose value should be used as the key in + the resulting array. This method also defines the way config array keys are + treated, as explained in the following example. + +When the ``useAttributeAsKey()`` method is not used, the names of the array +elements (i.e. the array keys) are ignored when parsing the configuration. +Consider this example:: + + $rootNode + ->children() + ->arrayNode('parameters') + ->prototype('array') + ->children() + ->scalarNode('parameter1')->end() + ->scalarNode('parameter2')->end() + ->end() + ->end() + ->end() + ->end() + ; + +In YAML, the configuration might look like this: + +.. code-block:: yaml + + database: + parameters: [ 'value1', 'value2' ] -An example of this:: +In XML, the configuration might look like this: + +.. code-block:: xml + + ... + +However, if the ``useAttributeAsKey()`` method is set, the parsed configuration +will be completely different:: $rootNode ->children() ->arrayNode('parameters') - ->isRequired() - ->requiresAtLeastOneElement() - ->useAttributeAsKey('name') + ->useAttributeAsKey('value') ->prototype('array') ->children() - ->scalarNode('value')->isRequired()->end() + ->scalarNode('parameter1')->end() + ->scalarNode('parameter2')->end() ->end() ->end() ->end() @@ -231,12 +264,19 @@ In YAML, the configuration might look like this: database: parameters: - param1: { value: param1val } + parameter1: { value: 'value1' } + parameter2: { value: 'value2' } + +In XML, the configuration might look like this: + +.. code-block:: xml + + ... -In XML, each ``parameters`` node would have a ``name`` attribute (along with +In XML, each ``parameters`` node has a ``value`` attribute (along with ``value``), which would be removed and used as the key for that element in -the final array. The ``useAttributeAsKey`` is useful for normalizing how -arrays are specified between different formats like XML and YAML. +the final array. The ``useAttributeAsKey()`` method is useful for normalizing +how arrays are specified between different formats like XML and YAML. Default and required Values --------------------------- From e77c3b28e8c78863f97e202f2d4709a50dc347b1 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 25 May 2015 17:04:28 +0200 Subject: [PATCH 2/3] Rewritten the explanation about the useAttributeAsKey() method --- components/config/definition.rst | 143 +++++++++++++++++++++++-------- 1 file changed, 109 insertions(+), 34 deletions(-) diff --git a/components/config/definition.rst b/components/config/definition.rst index c6a26f35469..f77855870f9 100644 --- a/components/config/definition.rst +++ b/components/config/definition.rst @@ -211,72 +211,147 @@ Before defining the children of an array node, you can provide options like: the resulting array. This method also defines the way config array keys are treated, as explained in the following example. -When the ``useAttributeAsKey()`` method is not used, the names of the array -elements (i.e. the array keys) are ignored when parsing the configuration. -Consider this example:: +A basic prototyped array configuration can be defined as follows:: - $rootNode + $node + ->fixXmlConfig('driver') ->children() - ->arrayNode('parameters') - ->prototype('array') - ->children() - ->scalarNode('parameter1')->end() - ->scalarNode('parameter2')->end() - ->end() - ->end() + ->arrayNode('drivers') + ->prototype('scalar')->end() ->end() ->end() ; -In YAML, the configuration might look like this: +When using the following YAML configuration: .. code-block:: yaml - database: - parameters: [ 'value1', 'value2' ] + drivers: ['mysql', 'sqlite'] -In XML, the configuration might look like this: +Or the following XML configuration: .. code-block:: xml - ... + msyql + sqlite -However, if the ``useAttributeAsKey()`` method is set, the parsed configuration -will be completely different:: +The processed configuration is:: - $rootNode + Array( + [0] => 'mysql' + [1] => 'sqlite' + ) + +A more complex example would be to define a prototyped array with children: + + $node + ->fixXmlConfig('connection') ->children() - ->arrayNode('parameters') - ->useAttributeAsKey('value') + ->arrayNode('connections') ->prototype('array') ->children() - ->scalarNode('parameter1')->end() - ->scalarNode('parameter2')->end() + ->scalarNode('table')->end() + ->scalarNode('user')->end() + ->scalarNode('password')->end() ->end() ->end() ->end() ->end() ; -In YAML, the configuration might look like this: +When using the following YAML configuration: .. code-block:: yaml - database: - parameters: - parameter1: { value: 'value1' } - parameter2: { value: 'value2' } + connections: + - { table: symfony, user: root, password: ~ } + - { table: foo, user: root, password: pa$$ } -In XML, the configuration might look like this: +Or the following XML configuration: .. code-block:: xml - ... + + + +The processed configuration is:: + + Array( + [0] => Array( + [table] => 'symfony' + [user] => 'root' + [password] => null + ) + [1] => Array( + [table] => 'foo' + [user] => 'root' + [password] => 'pa$$' + ) + ) + +The previous output matches the expected result. However, given the configuration +tree, when using the following YAML configuration: + +.. code-block:: yaml + + connections: + sf_connection: + table: symfony + user: root + password: ~ + default: + table: foo + user: root + password: pa$$ + +The output configuration will be exactly the same as before. In other words, the +``sf_connection`` and ``default`` configuration keys are lost. The reason is that +the Symfony Config component treats arrays as lists by default. + +In order to maintain the array keys use the ``useAttributeAsKey()`` method:: + + $node + ->fixXmlConfig('connection') + ->children() + ->arrayNode('connections') + ->prototype('array') + ->useAttributeAsKey('name') + ->children() + ->scalarNode('table')->end() + ->scalarNode('user')->end() + ->scalarNode('password')->end() + ->end() + ->end() + ->end() + ->end() + ; + +The argument of this method (``name`` in the example above) defines the name of +the attribute added to each XML node to differentiate them. Now you can use the +same YAML configuration showed before or the following XML configuration: + +.. code-block:: xml -In XML, each ``parameters`` node has a ``value`` attribute (along with -``value``), which would be removed and used as the key for that element in -the final array. The ``useAttributeAsKey()`` method is useful for normalizing -how arrays are specified between different formats like XML and YAML. + + + +In both cases, the processed configuration maintains the ``sf_connection`` and +``default`` keys:: + + Array( + [sf_connection] => Array( + [table] => 'symfony' + [user] => 'root' + [password] => null + ) + [default] => Array( + [table] => 'foo' + [user] => 'root' + [password] => 'pa$$' + ) + ) Default and required Values --------------------------- From 9fe902060cf1a957998bba52c551f23c36fe6ef1 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Tue, 26 May 2015 12:48:00 +0200 Subject: [PATCH 3/3] Fixed a minor syntax issue --- components/config/definition.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/config/definition.rst b/components/config/definition.rst index f77855870f9..abce20b6a2c 100644 --- a/components/config/definition.rst +++ b/components/config/definition.rst @@ -242,7 +242,7 @@ The processed configuration is:: [1] => 'sqlite' ) -A more complex example would be to define a prototyped array with children: +A more complex example would be to define a prototyped array with children:: $node ->fixXmlConfig('connection')