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