Documented the useAttributeAsKey() method

[javiereguiluz]

Q	A
Doc fix?	no
New docs?	yes
Applies to	all
Fixed tickets	#4509

Two comments:

• I've reordered the list of methods (addDefaultsIfNotSet, requiresAtLeastOneElement, useAttributeAsKey) to display it alphabetically and because it's better to have useAttributeAsKey at the end, just before showing the example.
• I've left the XML code blocks empty and I'd like some XML expert to help me fill them.

[wouterj]

missing ->fixXmlConfig('parameter') before line 219

[wouterj]

I think you got confused by the config tree :) Let's show some examples:

Basic Prototyped Array (list)

$node ->fixXmlConfig('driver') ->children() ->arrayNode('drivers') ->prototype('scalar')->end() ->end() // drivers ->end() ;

drivers: ['mysql', 'sqlite']

<driver>msyql</driver> <driver>sqlite</driver>

Output after processing:

Array( [0] => 'mysql' [1] => 'sqlite' )

Prototyped Array With Children (list)

$node ->fixXmlConfig('connection') ->children() ->arrayNode('connections') ->prototype('array') ->children() ->scalarNode('table')->end() ->scalarNode('user')->end() ->scalarNode('password')->end() ->end() ->end() ->end() // connections ->end() ;

connections: - { table: symfony, user: root, password: ~ } - { table: foo, user: root, password: pa$$ }

<connection table="symfony" user="root" password="null" /> <connection table="foo" user="root" password="pa$$" />

Output after processing:

Array( [0] => Array( [table] => 'symfony' [user] => 'root' [password] => null ) [1] => Array( [table] => 'foo' [user] => 'root' [password] => 'pa$$' ) )

Prototyped Array (list) With Wrong Usage

Assume same tree as previous example, but now this yaml:

connections: sf_connection: table: symfony user: root password: ~ default: table: foo user: root password: pa$$

The outcome will be exactly the same as the previous example, as the config component still handles connections as a list.

Prototyped Array (map)

Now, we can fix it using ->useAttributeAsKey():

$node ->fixXmlConfig('connection') ->children() ->arrayNode('connections') ->prototype('array') ->useAttributeAsKey('name') ->children() ->scalarNode('table')->end() ->scalarNode('user')->end() ->scalarNode('password')->end() ->end() ->end() ->end() // connections ->end() ;

Yaml is the same as previous example.

<connection name="sf_connection" table="symfony" user="root" password="null" /> <connection name="default" table="foo" user="root" password="pa$$" />

Output after processing:

Array( [sf_connection] => Array( [table] => 'symfony' [user] => 'root' [password] => null ) [default] => Array( [table] => 'foo' [user] => 'root' [password] => 'pa$$' ) )

[javiereguiluz]

@wouterj thanks a lot for your excellent and insightful explanation. I've reused your exact same example to explain the method. Thanks!

[javiereguiluz]

I wonder if we can label this PR as finished instead of in progress

[xabbuh]

Is that actually true when using the YAML format? Isn't the useAttributeAsKey() method only necessary when using the XML format because XML itself does not know anything like hashes?

[stof]

@xabbuh actually, there is an inconsistency in Symfony currently: if we need to merge lists coming from multiple files, the keys are lost (merging them in a new list indexed numerically). However, in case merging is not necessary (a single file configures this list), we currently don't reset keys

[stof]

@javiereguiluz please also document the ->normalizeKeys() method and advocate the usage of ->normalizeKeys(false) for prototyped associative array nodes. Keys defined by the user should not have dashes normalized to underscores as it causes confusion.
The ->normalizeKeys() method was added in 2.2 to solve this issue because of the design mistake in 2.0. But ideally, it would not exist and we would automatically skip the dash-to-underscore normalization for prototyped nodes.

[OskarStark]

is this also possible?

drivers: - mysql - sqlite

[stof]

yes it is, because this is exactly the same in YAML, so the Config component receives the same input.

[OskarStark]

ok, but we don't want to write this example explicitly, too?

[wouterj]

I see no need in doing that, this chapter is teaching you the Config component, not the Yaml syntax :)

[wouterj]

@javiereguiluz do you maybe have time to finish this PR?

[weaverryan]

Merged and continued in #5787